mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/wireless/switch.py

@@ -0,0 +1,77 @@
+"""Turning Wi-Fi on or off for one phone: what `mobster wifi on|off` and POST /api/devices/{device}/wifi share."""
+
+from . import pair, store
+
+# What the pair tool says when the phone or this Mac said no before anything changed on the phone.
+SAID_NO = ("needs_cable", "not_trusted", "refused")
+
+
+class SwitchRefused(Exception):
+    """The switch didn't happen; ``code`` is a ``words.PROBLEMS`` key."""
+
+    def __init__(self, code):
+        super().__init__(code)
+        self.code = code
+
+
+def turn_on(data_dir, udid, listing):
+    if listing is None:
+        raise SwitchRefused("needs_cable")
+    if not listing.get("trusted"):
+        raise SwitchRefused("not_trusted")
+    if not store.is_set_up(data_dir, udid):
+        raise SwitchRefused("not_set_up")
+    before = noted(data_dir, udid)
+    via = "mobster"
+    try:
+        pair.run(udid, "enable")
+    except LookupError:
+        via = "xcode"   # no pair tool: nothing was sent, the person ticks it in Xcode
+    except pair.PairError as error:
+        if error.code in SAID_NO:
+            put_back(data_dir, udid, before)
+        raise SwitchRefused(error.code if error.code in SAID_NO else "refused") from None
+    except RuntimeError:
+        put_back(data_dir, udid, before)   # devices are off in this process: nothing was sent
+        raise
+    store.put(data_dir, udid, True, via)
+    return via
+
+
+def noted(data_dir, udid):
+    """Mobster's list notes that Mobster may turn on the phone's switch, before the pair tool runs: an exit or crash
+    before the answer still leaves the record a later `mobster wifi off` clears it from. Returns the record as it was,
+    for put_back. LookupError when the phone isn't set up here."""
+    before = store.get(data_dir, udid)
+    if not before["enabled"]:
+        store.put(data_dir, udid, False, "mobster")
+    return before
+
+
+def put_back(data_dir, udid, before):
+    """The phone said no, or nothing was sent: the record goes back to what ``noted`` found."""
+    if not before["enabled"]:
+        store.put(data_dir, udid, False, before["via"])
+
+
+def turn_off(data_dir, udid, listing):
+    """Wi-Fi off for the phone in Mobster at once, then the phone's own switch when Mobster turned that on, over the
+    cable with the phone trusting this Mac. Returns None when no switch is left on that Mobster knows of, else the
+    ``words.PROBLEMS`` key of the one left on: "still_on" (not on the cable, or not trusted), "off_failed" (the pair
+    tool couldn't) or "xcode_on" (turned on in Xcode, which Mobster leaves alone)."""
+    via = store.get(data_dir, udid)["via"]
+    try:
+        store.put(data_dir, udid, False, "mobster" if via == "mobster" else None)
+    except LookupError:
+        raise SwitchRefused("not_set_up") from None
+    if via != "mobster":
+        return "xcode_on" if via == "xcode" else None
+    if listing is None or not listing.get("trusted"):
+        return "still_on"
+    try:
+        if pair.run(udid, "disable") is not False:
+            return "off_failed"
+    except (LookupError, RuntimeError):   # no tool, devices off in this process, or the tool said no (PairError)
+        return "off_failed"
+    store.put(data_dir, udid, False)
+    return None

mobile_agent/wireless/transport.py

@@ -0,0 +1,118 @@
+"""Cable or Wi-Fi: choosing the transport, the reconnect backoff, and each phone's link state (SPEC §3.7)."""
+
+import threading
+import time
+from dataclasses import dataclass, replace
+from typing import Optional
+
+# Seconds before each reconnect attempt after a failure: 1, 2, 4, 8, ... at most 60.
+BACKOFF = (1, 2, 4, 8, 16, 32, 60)
+
+
+def choose(usb_attached, wifi_enabled, tunnel_up):
+    """The transport a phone should use now: "usb", "wifi" or None (unplugged and not reachable)."""
+    if usb_attached:
+        return "usb"
+    if wifi_enabled and tunnel_up:
+        return "wifi"
+    return None
+
+
+def next_step(current, desired, busy):
+    if current == desired:
+        return "stay"
+    return "wait" if busy else "switch"
+
+
+class Backoff:
+    """Reconnect delays: after the n-th failure in a row, wait BACKOFF[n-1] seconds (60 s from then on)."""
+
+    def __init__(self, schedule=BACKOFF):
+        self.schedule = tuple(schedule)
+        self.failures = 0
+        self.next_at = 0.0
+
+    def delay(self):
+        if self.failures <= 0:
+            return 0
+        return self.schedule[min(self.failures, len(self.schedule)) - 1]
+
+    def ready(self, now):
+        return now >= self.next_at
+
+    def fail(self, now):
+        """Count a failure; returns the seconds until the next attempt."""
+        self.failures += 1
+        wait = self.delay()
+        self.next_at = now + wait
+        return wait
+
+    def reset(self):
+        self.failures = 0
+        self.next_at = 0.0
+
+
+@dataclass(frozen=True)
+class Link:
+    """One phone's connection as Mobster sees it now."""
+    udid: str
+    transport: Optional[str] = None      # "usb" | "wifi" | None: what its runner uses now
+    tunnel: str = "unknown"              # "up" | "connecting" | "down" | "unknown"
+    reachable: bool = False              # its WebDriverAgent answers through this Mac's relay or iproxy
+    last_seen_at: Optional[int] = None   # ms: the last time it answered
+    problem: Optional[str] = None        # a words.PROBLEMS code, or None
+    switching: bool = False              # a change of transport is pending or under way
+
+
+_links = {}
+_lock = threading.Lock()
+
+
+def link(udid) -> Optional[Link]:
+    with _lock:
+        return _links.get(_key(udid))
+
+
+def update(udid, **changes):
+    """Set fields of ``udid``'s link; returns (before, after). ``reachable`` True stamps ``last_seen_at``."""
+    key = _key(udid)
+    with _lock:
+        before = _links.get(key)
+        current = before or Link(udid=udid)
+        if changes.get("reachable"):
+            changes.setdefault("last_seen_at", round(time.time() * 1000))
+        after = replace(current, **changes)
+        _links[key] = after
+        return before, after
+
+
+def forget(udid=None):
+    """Drop one phone's link state, or every phone's (tests, a monitor that stops)."""
+    with _lock:
+        if udid is None:
+            _links.clear()
+        else:
+            _links.pop(_key(udid), None)
+
+
+def _key(udid):
+    return str(udid or "").upper()
+
+
+# What lockscreen.DetectGuard.attached() returns when Wi-Fi has nothing to say about a phone: it then asks USB.
+NOT_WIFI = object()
+
+
+def attached(udid):
+    state = link(udid)
+    if state is None or state.transport != "wifi":
+        return NOT_WIFI   # on the cable (a task started there still stops as unplugged when it's pulled)
+    if state.switching:
+        return None
+    return True if state.reachable else None
+
+
+def lost(udid):
+    """Whether ``udid`` was running over Wi-Fi and its link went down (not a switch Mobster is making)."""
+    state = link(udid)
+    return state is not None and state.transport == "wifi" and not state.reachable and not state.switching

mobile_agent/wireless/words.py

@@ -0,0 +1,81 @@
+
+# code -> (what's wrong, the one fix)
+PROBLEMS = {
+    "needs_cable": ("Plug {name} into this Mac with a cable to turn on Wi-Fi for it.",
+                    "Plug it in, unlock it and tap Trust if it asks, then try again."),
+    "not_trusted": ("{name} doesn't trust this Mac yet.",
+                    "Unlock it and tap Trust, then try again."),
+    "not_set_up": ("{name} isn't set up in Mobster yet.",
+                   "Open Setup with it plugged in and finish the steps, then turn on Wi-Fi."),
+    "needs_xcode": ("Mobster couldn't turn on Wi-Fi for {name} by itself.",
+                    "In Xcode, open Window › Devices and Simulators, select {name} and tick Connect via network."),
+    "refused": ("{name} didn't let Mobster turn on Wi-Fi.",
+                "Unlock it and try again, or tick Connect via network for it in Xcode › Devices and Simulators."),
+    "not_seen": ("{name} isn't reachable over Wi-Fi.",
+                 "Keep it unlocked and on the same Wi-Fi as this Mac, or plug it in."),
+    "route": ("Mobster stopped using Wi-Fi for {name}: this Mac no longer reaches it through the encrypted link.",
+              "Turn off any VPN on this Mac, or plug {name} in."),
+    "tunnel_down": ("The encrypted link to {name} isn't up yet.",
+                    "Unlock it and keep it on the same Wi-Fi as this Mac; Mobster tries again by itself."),
+    "address": ("Wi-Fi isn't available for this iPhone yet.",
+                "Plug it in to use it now."),
+    "devicectl_hang": ("Xcode's device service stopped answering.",
+                       "Plug {name} in once, or restart this Mac if it keeps happening."),
+    "no_xcode": ("Using an iPhone over Wi-Fi needs Xcode on this Mac.",
+                 "Install Xcode from the App Store and open it once."),
+    "identity": ("CoreDevice gave Mobster another iPhone's Wi-Fi address for {name}, so Mobster didn't use it.",
+                 "Plug {name} in; Mobster tries Wi-Fi again by itself."),
+    "runner": ("Mobster's helper didn't start on {name} over Wi-Fi.",
+               "Keep it unlocked and on the charger, or plug it in."),
+    "port_busy": ("Another program is using {name}'s connection on this Mac.",
+                  "Quit the other program, or plug the iPhone in."),
+    "busy": ("A task is running on {name}.",
+             "Stop it first, or wait for it to finish."),
+    "plugged_in": ("{name} is plugged in, so a Wi-Fi check says nothing about it.",
+                   "Unplug the cable, keep it unlocked on the same Wi-Fi as this Mac, then check again."),
+    "probe_running": ("Mobster is already checking Wi-Fi for {name}.",
+                      "Wait for that check to finish."),
+    "probe_timeout": ("The Wi-Fi check for {name} took too long.",
+                      "Keep it unlocked on the same Wi-Fi as this Mac, then check again."),
+    "off": ("Wi-Fi for iPhones is off in this Mobster.",
+            "Turn it on in Settings, or set MOBSTER_WIFI_TRANSPORT=1 in your env file."),
+    # Wi-Fi turned off in Mobster, with the phone's own switch (Connect via network) left on (switch.turn_off).
+    "still_on": ("{name} still accepts Wi-Fi connections from Macs it trusts: Mobster turns its Connect via network "
+                 "switch off only over the cable.",
+                 "Plug {name} in and unlock it, then turn off Wi-Fi for it again."),
+    "off_failed": ("Mobster couldn't turn off {name}'s Connect via network switch, so it still accepts Wi-Fi "
+                   "connections from Macs it trusts.",
+                   "Unlock {name}, keep it plugged in and turn off Wi-Fi for it again, or untick Connect via network "
+                   "for it in Xcode › Window › Devices and Simulators."),
+    "xcode_on": ("{name} may still accept Wi-Fi connections from Macs it trusts: Connect via network was turned on "
+                 "for it in Xcode, so Mobster left it on.",
+                 "In Xcode, open Window › Devices and Simulators, select {name} and untick Connect via network."),
+    # This Mac's network (network.peer_check), when the phone can't be found over Wi-Fi.
+    "network_blocked": ("This network stops devices from seeing each other.",
+                        "Use the cable or your phone's hotspot."),
+    "no_local_network": ("macOS doesn't let Mobster reach devices on your network.",
+                         "Turn on Mobster in System Settings › Privacy & Security › Local Network."),
+    "vpn": ("A VPN on this Mac can keep it and {name} apart.",
+            "Turn the VPN off, or use the cable."),
+}
+
+# network.peer_check's state -> the problem it is, when a phone can't be found over Wi-Fi.
+NETWORK_PROBLEMS = {"blocked": "network_blocked", "no_permission": "no_local_network", "vpn": "vpn"}
+
+# The words a phone's connection shows (CLI `mobster wifi status`; the app's v2 Settings row uses the same).
+ON_WIFI = "On Wi-Fi, encrypted"
+ON_CABLE = "On cable"
+UNREACHABLE = "Not reachable over Wi-Fi"
+OFF = "Wi-Fi off"
+
+
+def problem(code, name=None):
+    """{"code", "message", "fix"} for a problem code, with the phone's name filled in."""
+    message, fix = PROBLEMS[code]
+    who = name or "your iPhone"
+    return {"code": code, "message": _sentence(message.format(name=who)), "fix": _sentence(fix.format(name=who))}
+
+
+def _sentence(text):
+    """A sentence that starts with the phone's name ("your iPhone") starts with a capital."""
+    return text[:1].upper() + text[1:] if text else text

mobile_agent/wireless/xctestrun.py

@@ -0,0 +1,83 @@
+"""The runner's test plan for a launch over Wi-Fi (SPEC §3.7 item 3)."""
+
+import os
+import plistlib
+import tempfile
+from pathlib import Path
+
+from ..wda.patches import xctestrun_targets as targets
+from .relay import check_target, require_tunnel
+
+FOLDER = "mobster-wifi"
+TESTROOT = "__TESTROOT__"
+
+
+def source_plan(products):
+    """The built ``.xctestrun`` in ``products`` (the newest, when a rebuild left more than one), or LookupError."""
+    plans = sorted(Path(products).glob("*.xctestrun"), key=lambda path: (path.stat().st_mtime, path.name))
+    if not plans:
+        raise LookupError("Build Mobster's helper for this iPhone first.")
+    return plans[-1]
+
+
+def use_ips(plan):
+    """Every USE_IP the plan sets, in order (EnvironmentVariables, then TestingEnvironmentVariables)."""
+    values = []
+    for target in targets(plan):
+        for section in ("EnvironmentVariables", "TestingEnvironmentVariables"):
+            env = target.get(section)
+            if isinstance(env, dict) and "USE_IP" in env:
+                values.append(env["USE_IP"])
+    return values
+
+
+def _spell_out(value, root):
+    if isinstance(value, str):
+        return value.replace(TESTROOT, root)
+    if isinstance(value, list):
+        return [_spell_out(item, root) for item in value]
+    if isinstance(value, dict):
+        return {key: _spell_out(item, root) for key, item in value.items()}
+    return value
+
+
+def prepare(plan, products, address):
+    address = check_target(address)
+    copy = _spell_out(plan, str(Path(products).resolve()))
+    found = targets(copy)
+    if not found:
+        raise LookupError("Mobster's helper build has no test in it. Build it again in Setup.")
+    for target in found:
+        env = target.get("EnvironmentVariables")
+        if not isinstance(env, dict):
+            env = target["EnvironmentVariables"] = {}
+        env["USE_IP"] = address
+        testing = target.get("TestingEnvironmentVariables")
+        if isinstance(testing, dict) and "USE_IP" in testing:
+            testing["USE_IP"] = address
+    if not use_ips(copy) or any(value != address for value in use_ips(copy)):
+        raise ValueError("The helper's address couldn't be set.")
+    return copy
+
+
+# Its own folder, never beside the built plan: the cable's scheme-based launch finds that one by itself.
+def write(products, folder, address, *, through=None):
+    address = require_tunnel(address, through)
+    source = source_plan(products)
+    with open(source, "rb") as stream:
+        plan = plistlib.load(stream)
+    copy = prepare(plan, products, address)
+    folder = Path(folder)
+    folder.mkdir(parents=True, exist_ok=True)
+    os.chmod(folder, 0o700)
+    target = folder / source.name
+    handle, temporary = tempfile.mkstemp(dir=folder, prefix=".xctestrun-")
+    try:
+        with os.fdopen(handle, "wb") as stream:
+            os.fchmod(stream.fileno(), 0o600)
+            plistlib.dump(copy, stream)
+        os.replace(temporary, target)
+    except BaseException:
+        Path(temporary).unlink(missing_ok=True)
+        raise
+    return target

mobile_agent/workflow_tools.py

@@ -0,0 +1,59 @@
+"""Published workflow tool names and schemas shared by REST, MCP and Shortcuts."""
+
+import re
+
+TOOL_PREFIX = "workflow_"
+TOOL_WAIT_MAX = 45                 # seconds a tool call or a REST run waits for the run before it answers "running"
+TOOL_WAIT_DEFAULT = 30
+INPUT_TYPES = {"string": "string", "number": "number", "boolean": "boolean", "list": "array", "object": "object"}
+# Names under /api/workflows/ that are routes of their own: a workflow named like one takes its id in its slug.
+RESERVED_SLUGS = frozenset({"approvals", "draft", "evaluate", "node_types", "preview", "templates", "tools",
+                            "validate"})
+
+
+def tools(workflows):
+    """Each published ``asTool`` workflow as a tool; slugs go oldest first, so a new one never renames an older one."""
+    taken, out = set(), []
+    for workflow, live in sorted(workflows, key=lambda pair: pair[0].get("createdAt") or 0):
+        if not workflow.get("asTool") or not workflow.get("published"):
+            continue
+        slug = re.sub(r"[^a-z0-9]+", "_", str(workflow.get("name") or "").casefold()).strip("_")[:40] or "run"
+        if slug in taken or slug in RESERVED_SLUGS or re.fullmatch(r"[a-f0-9]{12}", slug):
+            slug = f"{slug}_{str(workflow.get('id'))[:4]}"
+        taken.add(slug)
+        steps = " ".join(str(workflow.get("goal") or "").split())
+        tool = {"name": TOOL_PREFIX + slug, "slug": slug, "path": f"/v1/workflows/{slug}",
+                "workflowId": workflow["id"], "workflowName": workflow.get("name"),
+                "description": (f"Run the user's workflow “{workflow.get('name')}” on their iPhone"
+                                + (f": {steps}" if steps else "."))[:220],
+                "inputSchema": tool_schema(workflow)}
+        result = next((n for n in (live or {}).get("nodes") or ()
+                       if n.get("type") == "output" and (n.get("config") or {}).get("schema")), None)
+        if result is not None:
+            tool["outputSchema"] = result["config"]["schema"]
+        out.append(tool)
+    return out
+
+
+def tool_schema(workflow):
+    """A workflow tool's input: its inputs and blanks (typed as declared), each by name, and wait_seconds."""
+    properties, required = {}, []
+    for blank in workflow.get("blanks") or []:
+        kind = INPUT_TYPES.get(blank.get("type") or "string", "string")
+        prop = {"type": kind, **({"maxLength": 300} if kind == "string" else {})}
+        if blank.get("default") is not None:
+            prop["description"] = f"default {blank['default']}"
+        else:
+            required.append(blank["name"])
+        properties[blank["name"]] = prop
+    properties["wait_seconds"] = {"type": "integer", "minimum": 0, "maximum": TOOL_WAIT_MAX,
+                                  "description": f"how long to wait for it to finish before returning (default "
+                                                 f"{TOOL_WAIT_DEFAULT})"}
+    return {"type": "object", "properties": properties, "required": required, "additionalProperties": False}
+
+
+def _as_tool(value):
+    """``asTool``: the workflow is its own tool for AI clients (MCP), typed from its inputs. Off unless turned on."""
+    if type(value) is not bool:
+        raise ValueError("asTool is true or false")
+    return value

mobile_agent/workflows/__init__.py

@@ -0,0 +1,2 @@
+"""Saved workflows: the records and their edits, dispatch and runs, the schedule, triggers, history, health, step cards,
+blanks and the brief step."""

mobile_agent/workflows/brief.py

@@ -0,0 +1,201 @@
+"""The brief: one result put together from the tasks a workflow ran, and the Morning brief job built on it.
+
+A workflow's ``brief`` step (batch.register_step, kind ``brief``) runs after its tasks, with no phone and no model. It
+takes the result of every task this round finished, in order, and makes one finished run of them in the workflow's
+conversation (Runtime.compose_result): their result blocks, each kept as it was (a review queue, a media list, a
+table, notes), and a task with an answer but no blocks as a notes card titled with its words. That run is the
+workflow's last result, so Home's job card, a PDF (POST /api/runs/{id}/artifact) and a share link work on it as on any
+task. It then says "Your brief is ready" as a Mac notification (``batch_notification`` on the workflows topic).
+
+- **Nothing new acts.** The brief only reads results that are already stored. A review queue's Approve on the brief
+  is the Approve of the task that found the item (Runtime.decide_block_item follows ``summary.brief.sources``): the
+  same stored item, the same one follow-up task per item, so approving in both places never sends twice.
+- **Fails closed.** A brief with no finished task before it stops the workflow and says why.
+- **Screen text is data.** The cards are the tasks' validated blocks (result_blocks.validate); nothing from them reaches
+  an instruction.
+
+``morning_brief(niche, at, timezone)`` is the Morning brief job (POST /api/workflows/templates/morning-brief): every
+morning, your DMs that need you, what's trending in your niche and ideas from your saved posts, on Instagram, in one
+result. App packs (feature/app-packs) take its tasks over when they land; until then Mobster's agent runs them.
+"""
+
+import re
+
+from .. import result_blocks
+from ..api_errors import APIError
+from ..graph.catalog import app_missing
+from . import records as batch
+from .health import run_outcome
+
+KIND = "brief"
+TITLE_CHARS = 80
+NOTES_CHARS = 6000
+
+MORNING_BRIEF = "morning-brief"
+INSTAGRAM = "com.burbn.instagram"
+NICHE_CHARS = 60
+DM_TASK = ("Go through my Instagram DMs and sort them into a review queue: needs a reply, can wait, and spam. Draft a "
+           "one-line reply for each one that needs a reply. Don’t send anything.")
+TRENDS_TASK = ("Watch 20 Reels about {niche} and tell me what’s trending: the formats, sounds and topics that keep "
+               "coming up, with an example of each. Don’t like, comment or follow.")
+IDEAS_TASK = ("Go through my newest saved posts on Instagram and give me ideas I could try next, each with the saved "
+              "post it comes from. Don’t like, comment or save anything.")
+
+
+def validate(step, runtime):
+    """The step as saved: an optional ``title`` for the result (default: the workflow's name)."""
+    if set(step) - {"id", "kind", "title"}:
+        raise ValueError("A brief step has only a title")
+    title = step.get("title")
+    if title is not None and (not isinstance(title, str) or not 0 < len(title.strip()) <= TITLE_CHARS):
+        raise ValueError(f"A brief's title is 1 to {TITLE_CHARS} characters")
+    return {"title": " ".join(title.split())} if title else {}
+
+
+def _summary(run):
+    return run.summary if isinstance(getattr(run, "summary", None), dict) else {}
+
+
+def _short(label, limit=60):
+    words = " ".join(str(label).split())
+    first = re.split(r"(?<=[.:!?])\s", words, maxsplit=1)[0]
+    return first if len(first) <= limit else first[:limit - 1].rstrip() + "…"
+
+
+def compose(sources):
+    """(envelope, mapping, answer) for ``sources``: [(label, run)]."""
+    blocks, mapping = [], {}
+    for index, (label, run) in enumerate(sources, start=1):
+        summary = _summary(run)
+        envelope = summary.get("blocks") if isinstance(summary.get("blocks"), dict) else None
+        own = [dict(block) for block in (envelope or {}).get("blocks") or () if isinstance(block, dict)]
+        if own:
+            for block in own:
+                new_id = f"s{index}-{block.get('id') or 'b'}"[:64]
+                mapping[new_id] = [run.id, block.get("id")]
+                blocks.append({**block, "id": new_id, "title": block.get("title") or _short(label)})
+            continue
+        text = summary.get("full_answer") or summary.get("data") or summary.get("answer")
+        if isinstance(text, str) and text.strip():
+            blocks.append({"type": "markdown", "id": f"s{index}-notes", "title": _short(label),
+                           "text": text.strip()[:NOTES_CHARS]})
+    envelope, _problems = result_blocks.validate(blocks[:result_blocks.MAX_BLOCKS])
+    kept = {block["id"] for block in (envelope or {}).get("blocks") or ()}
+    mapping = {key: value for key, value in mapping.items() if key in kept}
+    return envelope, mapping, answer_of(envelope)
+
+
+def answer_of(envelope):
+    """The brief's one line: what it holds, counted from its cards ("6 drafts to approve, 20 videos, 3 notes.")."""
+    parts = []
+    for block in (envelope or {}).get("blocks") or ():
+        kind = block.get("type")
+        if kind == "review_queue":
+            drafts = sum(1 for item in block.get("items") or () if item.get("draft"))
+            items = len(block.get("items") or ())
+            parts.append(f"{drafts} {'draft' if drafts == 1 else 'drafts'} to approve" if drafts
+                         else f"{items} {'conversation' if items == 1 else 'conversations'} sorted")
+        elif kind == "media_list":
+            n = len(block.get("items") or ())
+            parts.append(f"{n} {'video' if n == 1 else 'videos'}")
+        elif kind == "table":
+            n = len(block.get("rows") or ())
+            parts.append(f"{n} {'row' if n == 1 else 'rows'}")
+        elif kind == "checklist":
+            n = len(block.get("items") or ())
+            parts.append(f"{n} {'check' if n == 1 else 'checks'}")
+    notes = sum(1 for block in (envelope or {}).get("blocks") or () if block.get("type") == "markdown")
+    if notes:
+        parts.append(f"{notes} {'note' if notes == 1 else 'notes'}")
+    return ("Your brief: " + ", ".join(parts) + ".") if parts else "Your brief is ready."
+
+
+def run(going, step, values, *, sources, key=None):
+    if not sources:
+        raise batch.Stop("failed", "There's nothing to put in the brief: no task before it finished.")
+    envelope, mapping, answer = compose(sources)
+    if envelope is None:
+        raise batch.Stop("failed", "The tasks before the brief found nothing to put in it.")
+    runtime, workflow, record = going.runtime, going.workflow, going.record
+    title = step.get("title") or workflow.get("name") or "Brief"
+    first = sources[0][1]
+    # Done only when each task it holds is done (proof on the screen, or you marked it OK); its proof is theirs.
+    verified = all(run_outcome(run) == "done" for _, run in sources)
+    proof = [item for _, run in sources for item in (_summary(run).get("proof") or ())[:2]
+             if isinstance(item, dict)][:6]
+    summary = {"event": "result", "status": "completed", "outcome": "done" if verified else "check",
+               "engine": None, "answer": answer, "reason": None if verified else
+               "Mobster put the brief together, but one of its tasks finished without proof on the screen. Check it.",
+               "independently_verified": verified, "actions": 0, "decisions": 0, "elapsed_ms": 0, "model": None,
+               "full_answer": "\n\n".join(
+                   f"**{_short(label, 120)}**\n"
+                   f"{(_summary(run).get('full_answer') or _summary(run).get('answer') or '').strip()}"
+                   for label, run in sources)[:12000],
+               "blocks": envelope, "proof": proof if verified else [],
+               "brief": {"title": title, "runs": [run.id for _, run in sources], "sources": mapping,
+                         "spentUsd": round(going.spent, 6), "seconds": round(going.clock() - going.started, 1),
+                         "workflowId": workflow.get("id")}}
+    extras = {"threadId": record["threadId"]} if record.get("threadId") else {}
+    origin = getattr(first, "origin", None) or "workflow"
+    key = key or f"{record['key']}:b{record['id']}:{KIND}"[:128]
+    made = runtime.compose_result(app=dict(first.app), goal=f"Put together {title}", summary=summary,
+                                  idempotency_key=key, extras=extras, origin=origin,
+                                  device=(getattr(first, "device_id", None), getattr(first, "device_name", None)))
+    # The workflow's last result is the brief: Home's card, its PDF and the run's Needs you read it.
+    going.last = made
+    going._publish({"event": "batch_notification", "title": "Your brief is ready", "body": answer[:240],
+                    "runId": made.id})
+    return {"answer": answer, "line": f"Put together {title}"}
+
+
+def register():
+    if KIND not in batch.step_kinds():
+        batch.register_step(KIND, validate, run)
+
+
+def clean_niche(value):
+    """The niche as the trends task says it: plain words, no braces (a blank's mark), 1 to NICHE_CHARS characters."""
+    if not isinstance(value, str):
+        raise ValueError("Say your niche, like home cooking or streetwear")
+    niche = " ".join(re.sub(r"[{}\[\]<>]", " ", value).split())
+    if not 1 <= len(niche) <= NICHE_CHARS:
+        raise ValueError(f"Say your niche in 1 to {NICHE_CHARS} characters, like home cooking")
+    return niche
+
+
+def morning_brief(niche, at="08:00", timezone=None, app_id=INSTAGRAM):
+    niche = clean_niche(niche)
+    match = re.fullmatch(r"([01]?\d|2[0-3]):([0-5]\d)", at or "")
+    if not match:
+        raise ValueError("Choose a time like 08:00")
+    hour, minute = int(match[1]), int(match[2])
+    body = {"name": "Morning brief", "appId": app_id, "appName": "Instagram",
+            "cron": f"{minute} {hour} * * *", "enabled": True, "sameConversation": True,
+            "produces": ["review_queue", "media_list", "markdown"],
+            "steps": [{"id": "dms", "kind": "task", "text": DM_TASK, "appId": app_id},
+                      {"id": "trends", "kind": "task", "text": TRENDS_TASK.format(niche=niche), "appId": app_id},
+                      {"id": "ideas", "kind": "task", "text": IDEAS_TASK, "appId": app_id},
+                      {"id": "brief", "kind": KIND}],
+            "limits": {"maxSpendUsd": 2.0, "maxMinutes": 60}}
+    if timezone:
+        body["timezone"] = timezone
+    return body
+
+
+TEMPLATES = {MORNING_BRIEF: morning_brief}
+
+
+def create_from_template(workflows, name, body):
+    """POST /api/workflows/templates/{name}: the template's workflow, saved and scheduled (Workflows.create)."""
+    if name not in TEMPLATES:
+        raise APIError("There's no job template by that name.", 404, "template_not_found")
+    if not isinstance(body, dict) or set(body) - {"niche", "time", "timezone"}:
+        raise ValueError("A Morning brief takes niche, time (HH:MM) and timezone")
+    made = TEMPLATES[name](body.get("niche"), body.get("time") or "08:00", body.get("timezone"))
+    try:
+        return workflows.create(made)
+    except ValueError as error:
+        if str(error) == app_missing(INSTAGRAM):
+            raise ValueError("The Morning brief runs in Instagram, and Mobster doesn't see Instagram on your iPhone. "
+                             "Install it or open it once, then set up the brief again.") from None
+        raise