mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/longform/blocks.py

@@ -0,0 +1,117 @@
+"""A long task's results as result blocks: the report's ``blocks`` envelope, which the run view draws as cards."""
+
+from collections import Counter
+
+from .notebook import cut
+
+VIDEO_KINDS = ("reel", "tiktok", "short")
+NOUNS = {"reel": "Reels", "tiktok": "TikToks", "short": "Shorts", "post": "posts"}
+MAX_ITEMS = 60
+MAX_BLOCKS = 8
+MIN_FORMAT_COUNT = 2
+
+
+def review_queue(session, app_names=None):
+    """The inbox sweep's review queue as a review_queue block, or None when it read no conversation."""
+    from .inbox import OPENER_BUCKETS, REPLY_BUCKETS, queue_report, title, wants_openers
+    queue = queue_report(session, app_names)
+    items = []
+    for row in queue["items"]:
+        if not row["to"]:
+            continue    # a queue item goes to someone the screen named; without one it can't be a draft to approve
+        items.append({key: value for key, value in {
+            "id": row["id"], "bucket": row["bucket"], "to": row["to"], "handle": row.get("handle"), "app": row["app"],
+            "bundleId": row["bundleId"],
+            "context": row["summary"], "lastMessage": row["lastMessage"], "draft": row["draft"],
+            "decision": row["decision"], "frameId": row["frameId"]}.items() if value is not None})
+    if not items:
+        return None
+    budget = getattr(session, "budget", None)
+    return {"type": "review_queue", "id": "queue", "title": title(session, getattr(budget, "item_noun", None)),
+            "action": "send_message", "items": items,
+            "buckets": [{"id": bucket, "label": label} for bucket, label in (
+                OPENER_BUCKETS if wants_openers(getattr(session, "request", "")) else REPLY_BUCKETS)]}
+
+
+def _kept(session, kinds):
+    book = getattr(session, "notebook", None)
+    return [item for item in (book.kept_items() if book is not None else ()) if item.kind in kinds]
+
+
+def media_list(session):
+    """The kept videos as a media_list block: what each was about, its creator, its key frame and its sound."""
+    kept = _kept(session, VIDEO_KINDS)[:MAX_ITEMS]
+    items = []
+    for item in kept:
+        extract = item.extract or {}
+        title = extract.get("topic") or extract.get("summary") or item.text.get("caption")
+        if extract.get("format"):
+            title = f"{title}: {extract['format']}" if title else extract["format"]
+        entry = {"id": item.id, "title": cut(title, 200) or None, "creator": item.who() or None,
+                 "frameId": item.frame_id, "sounds": [cut(item.text["audio"], 80)] if item.text.get("audio") else None}
+        entry = {key: value for key, value in entry.items() if value}
+        if len(entry) > 1:
+            items.append(entry)
+    if not items:
+        return None
+    noun = NOUNS.get(kept[0].kind, "videos")
+    return {"type": "media_list", "id": "media", "title": f"{len(items)} {noun} watched", "items": items}
+
+
+def formats_chart(session):
+    """How many kept videos share each format, when at least two formats repeat: a bar chart."""
+    counts = Counter(" ".join(str((item.extract or {}).get("format") or "").casefold().split())
+                     for item in _kept(session, VIDEO_KINDS))
+    counts.pop("", None)
+    top = [(name, count) for name, count in counts.most_common(8) if count >= MIN_FORMAT_COUNT]
+    if len(top) < 2:
+        return None
+    total = len(_kept(session, VIDEO_KINDS))
+    noun = NOUNS.get(_kept(session, VIDEO_KINDS)[0].kind, "videos")
+    return {"type": "chart", "id": "formats", "title": f"Formats in {total} {noun}", "kind": "bar",
+            "x": [name[:1].upper() + name[1:] for name, _ in top],
+            "series": [{"label": noun, "values": [c for _, c in top]}]}
+
+
+def posts_table(session):
+    """The kept posts as a table: creator, topic and what each says, each row with its frame."""
+    kept = _kept(session, ("post",))[:MAX_ITEMS]
+    rows = []
+    for item in kept:
+        extract = item.extract or {}
+        row = {"cells": {"creator": item.who() or "", "topic": cut(extract.get("topic"), 80),
+                         "says": cut(extract.get("summary") or item.text.get("caption"), 300)}}
+        if item.frame_id:
+            row["frameId"] = item.frame_id
+        if any(row["cells"].values()):
+            rows.append(row)
+    if not rows:
+        return None
+    return {"type": "table", "id": "posts", "title": f"{len(rows)} posts", "rows": rows,
+            "columns": [{"key": "creator", "label": "Creator", "type": "text"},
+                        {"key": "topic", "label": "Topic", "type": "text"},
+                        {"key": "says", "label": "What it says", "type": "text"}]}
+
+
+def for_session(session, app_names=None):
+    """The blocks a long task's report carries, in the order the run view shows them; [] when it has none."""
+    from .inbox import wants_queue
+    blocks = []
+    if wants_queue(getattr(session, "request", "")):
+        blocks.append(review_queue(session, app_names))
+    blocks += [formats_chart(session), media_list(session), posts_table(session)]
+    return [block for block in blocks if block][:MAX_BLOCKS]
+
+
+def attach(session, report, app_names=None):
+    """The report with ``blocks`` (the envelope {"v": 1, "blocks": [...]})
+    when the task has any; unchanged otherwise."""
+    if not isinstance(report, dict):
+        return report
+    try:
+        blocks = for_session(session, app_names)
+    except Exception:  # noqa: BLE001 -- the report stands without its cards
+        blocks = []
+    if blocks:
+        report["blocks"] = {"v": 1, "blocks": blocks}
+    return report

mobile_agent/longform/budget.py

@@ -0,0 +1,265 @@
+"""Budgets for long tasks (DESIGN §3): what "for 10 minutes", "30 reels" or "every match" means, decided by code."""
+
+import math
+import re
+from dataclasses import asdict, dataclass, replace
+
+# What a person spends on one item, in seconds: the human-equivalent conversion.
+HUMAN_SECONDS_PER_ITEM = {"reel": 12, "tiktok": 10, "short": 12, "post": 8, "profile": 45, "chat": 30, "row": 20,
+                          "result": 20}
+MINUTES_RANGE = (1.0, 120.0)
+ITEMS_RANGE = (1, 500)
+# "every match", "all my DMs": up to ALL_CAP items, which the plan card can raise to ALL_MAX.
+ALL_CAP, ALL_MAX = 40, 100
+DEFAULT_ITEMS = {"feed": 30, "browse": 20}
+# The longest a long task may hold the phone when nothing else bounds it (a chain, a survey).
+DEFAULT_PHONE_SECONDS = {"feed": 600.0, "survey": 900.0, "chain": 900.0, "browse": 600.0}
+
+NUMBER_WORDS = {"a": 1, "an": 1, "one": 1, "two": 2, "three": 3, "four": 4, "five": 5, "six": 6, "seven": 7,
+                "eight": 8, "nine": 9, "ten": 10, "eleven": 11, "twelve": 12, "fifteen": 15, "twenty": 20,
+                "thirty": 30, "forty": 40, "forty-five": 45, "fifty": 50, "sixty": 60, "ninety": 90, "hundred": 100,
+                "a dozen": 12, "a couple": 2, "a couple of": 2, "a few": 5, "several": 5}
+UNITS = {"s": 1 / 60, "sec": 1 / 60, "secs": 1 / 60, "second": 1 / 60, "seconds": 1 / 60, "m": 1.0, "min": 1.0,
+         "mins": 1.0, "minute": 1.0, "minutes": 1.0, "h": 60.0, "hr": 60.0, "hrs": 60.0, "hour": 60.0,
+         "hours": 60.0}
+# Collection nouns -> (item kind, the noun the plan card shows).
+NOUNS = {"reels": ("reel", "Reels"), "reel": ("reel", "Reels"), "videos": ("reel", "videos"),
+         "video": ("reel", "videos"), "shorts": ("short", "Shorts"), "tiktoks": ("tiktok", "TikToks"),
+         "tiktok": ("tiktok", "TikToks"), "posts": ("post", "posts"), "profiles": ("profile", "profiles"),
+         "matches": ("profile", "matches"), "messages": ("chat", "messages"), "chats": ("chat", "chats"),
+         "conversations": ("chat", "chats"), "dms": ("chat", "DMs"), "emails": ("row", "emails"),
+         "results": ("result", "results"), "places": ("result", "places"), "restaurants": ("result", "restaurants"),
+         "listings": ("result", "listings"), "items": ("row", "items"), "match": ("profile", "matches"),
+         "profile": ("profile", "profiles"), "dm": ("chat", "DMs"), "chat": ("chat", "chats"),
+         "message": ("chat", "messages"), "email": ("row", "emails"), "result": ("result", "results"),
+         "place": ("result", "places"), "restaurant": ("result", "restaurants"), "listing": ("result", "listings"),
+         "post": ("post", "posts")}
+
+_NUM = r"(\d+(?:\.\d+)?|" + "|".join(sorted((re.escape(w) for w in NUMBER_WORDS), key=len, reverse=True)) + r")"
+# Item counts take digits or a real number word: "a short video" or "a profile" is no count.
+_COUNT = r"(\d+|" + "|".join(sorted((re.escape(w) for w in NUMBER_WORDS if w not in (
+    "a", "an", "a couple", "a couple of", "a few", "several")), key=len, reverse=True)) + r")"
+_UNIT = r"(" + "|".join(sorted(UNITS, key=len, reverse=True)) + r")\b"
+_LEAD = (
+    r"(?:for|about|around|spend|spending|scroll(?:ing)? for|watch(?:ing)? for|over|during|keep going for|"
+    r"nonstop for)")
+TIME = re.compile(rf"\b{_LEAD}\s+(?:the\s+(?:full|whole|entire)\s+|a\s+good\s+)?{_NUM}\s*-?\s*{_UNIT}", re.I)
+TIME_PHRASES = ((re.compile(r"\b(?:for|about|around|spend|over)\s+(?:the\s+(?:full|whole|entire)\s+)?half an hour\b",
+                            re.I), 30.0),
+                (re.compile(r"\b(?:for|about|around|spend|over)\s+(?:the\s+(?:full|whole|entire)\s+)?an hour\b", re.I),
+                 60.0),
+                (re.compile(r"\b(?:for|about|around|spend|over)\s+a few minutes\b", re.I), 5.0),
+                (re.compile(r"\b(?:for|about|around|spend|over)\s+a couple (?:of )?minutes\b", re.I), 2.0))
+STRICT = re.compile(r"\b(?:the\s+(?:full|whole|entire)|keep going for|nonstop for)\b", re.I)
+# "the whole 10 minutes" with no lead word ("watch the whole 10 minutes of Reels"): strict time on its own.
+STRICT_TIME = re.compile(rf"\bthe\s+(?:full|whole|entire)\s+{_NUM}\s*-?\s*{_UNIT}", re.I)
+ITEMS = re.compile(r"\b(?:the\s+(?:next|first|last|top)\s+|next\s+|first\s+|top\s+)?" + _COUNT
+                   + r"\s+(?:[a-z-]+\s+){0,2}?("
+                   + "|".join(sorted(NOUNS, key=len, reverse=True)) + r")\b", re.I)
+ALL = re.compile(r"\b(?:every|each of my|all (?:of )?my|go(?:ing)? through (?:all (?:of )?)?my|my matches|my dms|"
+                 r"all the|all\s+(?:" + "|".join(sorted(NOUNS, key=len, reverse=True)) + r"))\b", re.I)
+
+
+@dataclass(frozen=True)
+class Budget:
+    kind: str                 # "time" | "items" | "all" | "default"
+    minutes: float | None     # what the person said (time)
+    items: int | None         # item target (time is converted)
+    strict: bool              # True: run the whole time, no item target
+    phone_seconds_cap: float  # never hold the phone longer than this
+    item_noun: str            # "Reels", "TikToks", "profiles", "chats", "results"
+    label: str                # "About 50 Reels", "Up to 40 matches", "10 minutes"
+    item_kind: str = "reel"   # HUMAN_SECONDS_PER_ITEM's key
+    clamped: bool = False     # the request's number was outside the range and was moved into it
+
+    def public(self):
+        """The plan card's camelCase shape."""
+        return {"kind": self.kind, "minutes": self.minutes, "items": self.items, "strict": self.strict,
+                "phoneSecondsCap": round(self.phone_seconds_cap), "itemNoun": self.item_noun, "label": self.label,
+                "clamped": self.clamped}
+
+    def to_dict(self):
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, value):
+        fields = {name: value.get(name) for name in ("kind", "minutes", "items", "strict", "phone_seconds_cap",
+                                                     "item_noun", "label", "item_kind", "clamped")}
+        fields["strict"] = bool(fields["strict"])
+        fields["clamped"] = bool(fields["clamped"])
+        fields["item_kind"] = fields["item_kind"] or "reel"
+        fields["phone_seconds_cap"] = float(fields["phone_seconds_cap"] or 600.0)
+        return cls(**fields)
+
+
+def _number(word):
+    word = word.casefold().strip()
+    if word in NUMBER_WORDS:
+        return float(NUMBER_WORDS[word])
+    try:
+        return float(word)
+    except ValueError:
+        return None
+
+
+def noun_in(goal):
+    """(item kind, card noun) for the collection the request names, or (None, None)."""
+    folded = goal.casefold()
+    best = None
+    for word, value in NOUNS.items():
+        found = re.search(rf"\b{re.escape(word)}\b", folded)
+        if found and (best is None or found.start() < best[0]):
+            best = (found.start(), value)
+    return best[1] if best else (None, None)
+
+
+# A time that is the object of the task, not its budget: "set a timer for 10 minutes", "snooze for 5 minutes".
+NOT_A_BUDGET = re.compile(r"\b(timers?|alarms?|countdown|snooze|remind(?:er|ers)?(?: me)?)\b[^,;.]{0,24}$", re.I)
+
+
+def _minutes(goal):
+    """(minutes, strict) the request asks for, or (None, False)."""
+    for pattern, minutes in TIME_PHRASES:
+        found = pattern.search(goal)
+        if found and not NOT_A_BUDGET.search(goal[:found.start()]):
+            return minutes, bool(STRICT.search(found.group(0)))
+    found = TIME.search(goal) or STRICT_TIME.search(goal)
+    if not found or NOT_A_BUDGET.search(goal[:found.start()]):
+        return None, False
+    number = _number(found.group(1))
+    if number is None:
+        return None, False
+    return number * UNITS[found.group(2).casefold()], bool(STRICT.search(found.group(0)))
+
+
+def parse_budget(goal):
+    """The request's budget, or None when it names none (the plan then picks its kind's default)."""
+    text = " ".join(str(goal or "").split())
+    if not text:
+        return None
+    kind_noun = noun_in(text)
+    item_kind, noun = kind_noun if kind_noun[0] else ("reel", "items")
+    minutes, strict = _minutes(text)
+    if minutes is not None:
+        return time_budget(minutes, item_kind, noun, strict=strict)
+    found = ITEMS.search(text)
+    if found:
+        number = _number(found.group(1))
+        if number is not None and number >= 1:
+            item_kind, noun = NOUNS[found.group(2).casefold()]
+            return items_budget(int(number), item_kind, noun)
+    if ALL.search(text):
+        return all_budget(item_kind, noun)
+    return None
+
+
+def time_budget(minutes, item_kind="reel", noun="Reels", *, strict=False):
+    clamped = not MINUTES_RANGE[0] <= minutes <= MINUTES_RANGE[1]
+    minutes = min(max(minutes, MINUTES_RANGE[0]), MINUTES_RANGE[1])
+    minutes = round(minutes, 2)
+    cap = minutes * 60
+    if strict:
+        return Budget("time", minutes, None, True, cap, noun, minutes_label(minutes), item_kind, clamped)
+    items = human_items(cap, item_kind)
+    return Budget("time", minutes, items, False, cap, noun, f"About {items} {noun}", item_kind, clamped)
+
+
+def items_budget(count, item_kind="reel", noun="Reels"):
+    clamped = not ITEMS_RANGE[0] <= count <= ITEMS_RANGE[1]
+    count = min(max(int(count), ITEMS_RANGE[0]), ITEMS_RANGE[1])
+    from .costs import ITEM_S
+    cap = max(120.0, min(7200.0 - 300, 120 + count * ITEM_S.get(item_kind, 3.0) * 3))
+    return Budget("items", None, count, False, cap, noun, f"{count} {noun}", item_kind, clamped)
+
+
+def all_budget(item_kind="profile", noun="matches", cap_items=ALL_CAP):
+    cap_items = min(max(int(cap_items), 1), ALL_MAX)
+    from .costs import ITEM_S
+    cap = max(300.0, 120 + cap_items * ITEM_S.get(item_kind, 3.0) * 3)
+    return Budget("all", None, cap_items, False, cap, noun, f"Up to {cap_items} {noun}", item_kind)
+
+
+def human_items(seconds, item_kind):
+    """How many items a person sees in ``seconds``."""
+    return max(1, math.ceil(seconds / HUMAN_SECONDS_PER_ITEM.get(item_kind, 12)))
+
+
+def minutes_label(minutes):
+    if minutes >= 60 and minutes % 60 == 0:
+        hours = int(minutes // 60)
+        return f"{hours} hour{'s' if hours != 1 else ''}"
+    if minutes < 1:
+        return f"{round(minutes * 60)} seconds"
+    whole = int(minutes) if float(minutes).is_integer() else minutes
+    return f"{whole} minute{'s' if whole != 1 else ''}"
+
+
+def for_kind(kind, parsed, item_kind, noun):
+    """The budget a plan of ``kind`` runs with: the request's own (``parsed``), else the kind's default."""
+    if parsed is not None:
+        if parsed.kind == "time" and parsed.item_noun == "items" and noun != "items":
+            # "for 10 minutes" with the noun named elsewhere ("Scroll TikTok for 10 minutes")
+            return time_budget(parsed.minutes, item_kind, noun, strict=parsed.strict)
+        if parsed.kind == "all" and parsed.item_noun == "items" and noun != "items":
+            return all_budget(item_kind, noun)
+        return parsed
+    if kind == "survey":
+        return all_budget(item_kind, noun)
+    if kind == "chain":
+        return Budget("default", None, None, False, DEFAULT_PHONE_SECONDS["chain"], noun, "Each step once",
+                      item_kind)
+    count = DEFAULT_ITEMS.get(kind, 20)
+    budget = items_budget(count, item_kind, noun)
+    return replace(budget, kind="default", label=f"About {count} {noun}")
+
+
+def override(budget, change):
+    """``budget`` changed by the plan card or the API's ``longform.budget`` ({items?, minutes?, strict?})."""
+    if not change:
+        return budget
+    if not isinstance(change, dict) or set(change) - {"items", "minutes", "strict"}:
+        raise ValueError("longform.budget takes items, minutes and strict")
+    items, minutes, strict = change.get("items"), change.get("minutes"), change.get("strict")
+    if strict is not None and type(strict) is not bool:
+        raise ValueError("longform.budget.strict is true or false")
+    if minutes is not None:
+        if isinstance(minutes, bool) or not isinstance(minutes, (int, float)) or \
+                not MINUTES_RANGE[0] <= minutes <= MINUTES_RANGE[1]:
+            raise ValueError("longform.budget.minutes is between 1 and 120")
+        return time_budget(float(minutes), budget.item_kind, budget.item_noun, strict=bool(strict))
+    if items is not None:
+        if isinstance(items, bool) or not isinstance(items, int) or not ITEMS_RANGE[0] <= items <= ITEMS_RANGE[1]:
+            raise ValueError("longform.budget.items is a whole number from 1 to 500")
+        if budget.kind == "all":
+            return all_budget(budget.item_kind, budget.item_noun, min(items, ALL_MAX))
+        return items_budget(items, budget.item_kind, budget.item_noun)
+    if strict is not None and budget.minutes is not None:
+        return time_budget(budget.minutes, budget.item_kind, budget.item_noun, strict=strict)
+    return budget
+
+
+def from_cli(value):
+    """``--budget``: 10m, 90s, 1h, 30 (items) or all. ValueError with a sentence otherwise."""
+    text = str(value or "").strip().casefold()
+    if text == "all":
+        return {"items": ALL_CAP}
+    found = re.fullmatch(r"(\d+(?:\.\d+)?)\s*(s|sec|m|min|h|hr)?", text)
+    if not found:
+        raise ValueError("--budget is a time (10m, 90s, 1h), a number of items (30) or all")
+    number, unit = float(found.group(1)), found.group(2)
+    if unit is None:
+        if not number.is_integer() or not ITEMS_RANGE[0] <= number <= ITEMS_RANGE[1]:
+            raise ValueError("--budget takes 1 to 500 items")
+        return {"items": int(number)}
+    minutes = number * UNITS[unit]
+    if not MINUTES_RANGE[0] <= minutes <= MINUTES_RANGE[1]:
+        raise ValueError("--budget takes 1 minute to 2 hours")
+    return {"minutes": round(minutes, 2)}
+
+
+def turn_caps(budget, steps=3):
+    """(max_steps, max_seconds) for a long run (DESIGN §3.3)."""
+    items = budget.items or 0
+    max_steps = min(600, 60 + 12 * max(1, steps) + math.ceil(items / 10))
+    max_seconds = min(7200.0, budget.phone_seconds_cap + 300)
+    return max_steps, max_seconds

mobile_agent/longform/context.py

@@ -0,0 +1,285 @@
+"""What the navigation model sees of a long task (DESIGN §5.2, §5.3, §6.1, §6.2)."""
+
+import re
+
+from .notebook import cut
+
+LONGFORM_SYSTEM = """This is a long task with a budget and a notebook.
+- The code keeps a notebook for you and writes the final report from it after you finish. Your DONE answer needs only \
+one or two sentences; the report does the rest.
+- Use the macros for repeated work. On a full-screen vertical video feed (Reels, TikTok, Shorts) use WATCH_FEED; do \
+not swipe through videos one by one. For a list whose rows each open a page (matches, chats, results) use READ_EACH. \
+Navigate yourself to where a macro starts: search the topic, open the right tab, tap the first video.
+- When a macro returns, read its summary: if the feed drifted off the topic, search again; if the budget is covered, \
+finish.
+- Put what you learn in notes_add, citing items by id ("i12, i15: two drills for footwork"). Facts, not narration.
+- Set step to the plan step you are working on. If a step can't be done, say why in notes_add and go on to the next \
+step unless it depends on this one.
+- The budget line says how much is left. When it says wrap up, finish with DONE."""
+
+EPOCH_HEAD = "Notebook (the code keeps everything here for the report; you see a summary):"
+DELTA_HEAD = "Notebook since the summary above:"
+EPOCH_FACTS, EPOCH_ITEMS = 15, 6
+DELTA_FACTS, DELTA_ITEMS = 10, 6
+EPOCH_CHARS, DELTA_CHARS = 9000, 3000
+EPOCH_EVERY = 10            # new items or facts that make a new epoch
+COMPACT_EVERY = 8           # history lines per log line
+LOG_SHOWN = 6
+STEP_WORDS = {"done": "done", "now": "now", "next": "next", "skipped": "skipped", "failed": "failed"}
+
+
+def plan_steps(plan):
+    """The stable prompt's lines for the plan's steps."""
+    steps = (plan or {}).get("steps") or ()
+    if not steps:
+        return ""
+    lines = [f"{s['id']}. {s['title']}" + (f" ({s['app']})" if s.get("app") else "") for s in steps]
+    text = ("\n\nPlan steps (set step to the one you work on; the code marks them done as you move on):\n"
+            + "\n".join(lines))
+    from .inbox import wants_drafts, wants_openers
+    if (plan or {}).get("kind") == "survey" and wants_drafts((plan or {}).get("title")):
+        # Real iPhone, 13 Oct: a DM sweep read the inbox's previews with READ_LIST and finished without opening one
+        # conversation, so it drafted replies to messages it never saw in full.
+        text += SWEEP_NOTE
+    elif (plan or {}).get("kind") == "survey" and wants_openers((plan or {}).get("title")):
+        text += OPENERS_NOTE
+    return text
+
+
+SWEEP_NOTE = ("\nThis is an inbox sweep: sort and draft from the conversations themselves. Use READ_EACH on the first "
+              "conversation row of each list (newest first) so code opens every one; READ_LIST reads only the "
+              "previews, which are not enough to sort or draft from. Check the other inbox tabs (requests, general) "
+              "the same way. Finish when READ_EACH reaches the end of the lists or the budget.")
+
+
+OPENERS_NOTE = ("\nThis drafts a first message to each person who fits: code drafts them from the posts themselves. "
+                "Use READ_EACH on the first post row of the list so code opens every post; READ_LIST reads only the "
+                "previews. Never open a conversation or send anything: the person reviews every draft. Finish when "
+                "READ_EACH reaches the end of the list or the budget.")
+
+
+def counts_line(notebook):
+    c = notebook.counters
+    return (f"Counts: {c['seen']} seen, {c['kept']} kept, {c['ads']} ads skipped, {c['repeats']} repeats skipped, "
+            f"{c['off_topic']} off topic.")
+
+
+def steps_line(notebook):
+    if not notebook.steps:
+        return ""
+    parts = []
+    for step in notebook.steps:
+        parts.append(f"{step['id']} {STEP_WORDS.get(step['state'], step['state'])}")
+    return "Steps: " + ". ".join(parts) + "."
+
+
+def item_line(item):
+    who = item.who()
+    label = f"{who}: " if who else ""
+    state = {None: "kept", "ad": "ad, skipped", "repeat": "repeat, skipped", "off_topic": "off topic",
+             "unreadable": "unreadable"}[item.skip]
+    summary = item.summary()
+    return f"- {item.id} {label}" + (f"\"{cut(summary, 120)}\" " if summary else "") + f"({state})"
+
+
+def fact_line(fact):
+    ids = f"[{', '.join(fact.item_ids[:6])}] " if fact.item_ids else ""
+    return f"- {fact.id} {ids}{cut(fact.text, 220)}"
+
+
+def render_epoch(notebook):
+    """The notebook's summary for the cached epoch (at most about 2,500 tokens)."""
+    with notebook.lock:
+        lines = [EPOCH_HEAD, counts_line(notebook)]
+        digest = notebook.digest or {}
+        if digest.get("text"):
+            lines.append("Digest: " + cut(digest["text"], 700))
+        themes = digest.get("themes") or ()
+        if themes:
+            lines.append("Themes: " + ", ".join(f"{t.get('name')} ({len(t.get('item_ids') or ())})"
+                                                for t in themes[:10]))
+        facts = notebook.facts[-EPOCH_FACTS:]
+        if facts:
+            lines.append(f"Facts (newest {len(facts)}):")
+            lines += [fact_line(f) for f in reversed(facts)]
+        items = notebook.items[-EPOCH_ITEMS:]
+        if items:
+            lines.append(f"Recent items (newest {len(items)}):")
+            lines += [item_line(i) for i in reversed(items)]
+        steps = steps_line(notebook)
+        if steps:
+            lines.append(steps)
+        text = "\n".join(lines)
+    return text[:EPOCH_CHARS]
+
+
+def render_delta(notebook, since):
+    """What changed since the epoch ``since`` = (items, facts) counts: new facts and items, counts and steps now."""
+    items_at, facts_at = since
+    with notebook.lock:
+        new_items = notebook.items[items_at:]
+        new_facts = notebook.facts[facts_at:]
+        lines = [DELTA_HEAD, counts_line(notebook).replace("Counts:", "Counts now:")]
+        if new_facts:
+            shown = new_facts[-DELTA_FACTS:]
+            lines.append(f"New facts ({len(new_facts)}):" if len(shown) == len(new_facts)
+                         else f"New facts (newest {len(shown)} of {len(new_facts)}):")
+            lines += [fact_line(f) for f in reversed(shown)]
+        if new_items:
+            shown = new_items[-DELTA_ITEMS:]
+            lines.append(f"New items ({len(new_items)}):" if len(shown) == len(new_items)
+                         else f"New items (newest {len(shown)} of {len(new_items)}):")
+            lines += [item_line(i) for i in reversed(shown)]
+        steps = steps_line(notebook)
+        if steps:
+            lines.append(steps)
+        if notebook.log:
+            lines.append(f"Earlier turns, compacted (newest {min(LOG_SHOWN, len(notebook.log))}):")
+            lines += [f"- {line}" for line in notebook.log[-LOG_SHOWN:]]
+        text = "\n".join(lines)
+    return text[:DELTA_CHARS]
+
+
+class Epochs:
+    """When the cached epoch is re-rendered (DESIGN §6.2)."""
+
+    def __init__(self):
+        self.text = None
+        self.since = (0, 0)
+        self.digest_key = None
+        self.steps_key = None
+        self.renders = 0
+
+    def current(self, notebook):
+        """(epoch text, (items, facts) at that epoch): the same text until a refresh trigger."""
+        with notebook.lock:
+            digest = notebook.digest or {}
+            digest_key = (digest.get("turn"), digest.get("up_to_item"), digest.get("text"))
+            steps_key = tuple((s["id"], s["state"]) for s in notebook.steps)
+            items, facts = len(notebook.items), len(notebook.facts)
+            fresh = (self.text is None or digest_key != self.digest_key or steps_key != self.steps_key
+                     or items - self.since[0] >= EPOCH_EVERY or facts - self.since[1] >= EPOCH_EVERY)
+            if fresh:
+                self.text = render_epoch(notebook)
+                self.since = (items, facts)
+                self.digest_key, self.steps_key = digest_key, steps_key
+                self.renders += 1
+        return self.text, self.since
+
+
+def money(usd):
+    return f"${usd:,.2f}"
+
+
+def duration(seconds):
+    seconds = max(0, int(round(seconds)))
+    minutes, rest = divmod(seconds, 60)
+    if minutes and rest:
+        return f"{minutes} min {rest} s"
+    if minutes:
+        return f"{minutes} min"
+    return f"{rest} s"
+
+
+def budget_line(session):
+    """"Budget: 41 of about 50 Reels. 1 min 12 s of phone time used (cap 10 min). $0.08 spent of $1.00 (report
+    reserve $0.06). Wrap up when the items are covered.\""""
+    budget = session.budget
+    kept = session.notebook.watched()
+    parts = []
+    if budget.items and not budget.strict:
+        about = "about " if budget.kind in ("time", "default") else "up to " if budget.kind == "all" else ""
+        parts.append(f"{kept} of {about}{budget.items} {budget.item_noun}.")
+    else:
+        parts.append(f"{kept} {budget.item_noun} so far.")
+    parts.append(f"{duration(session.phone_seconds())} of phone time used (cap {duration(budget.phone_seconds_cap)}).")
+    cap = session.cap_usd
+    spent, reserve = session.spent_usd(), session.reserve_usd()
+    if cap is not None:
+        parts.append(f"{money(spent)} spent of {money(cap)} (report reserve {money(reserve)}).")
+    else:
+        parts.append(f"{money(spent)} spent (report reserve {money(reserve)}).")
+    advice = session.advice()
+    if advice:
+        parts.append(advice)
+    return "Budget: " + " ".join(parts)
+
+
+HISTORY = re.compile(r"^(\d+)(?:\.(\d+))?: (.*)$")
+OP = re.compile(r"^([A-Z][A-Z_]+)\b")
+TEXT = re.compile(r"text='([^']{1,60})")
+WATCHED = re.compile(r"(?:Watched|Read) (\d+) ")
+
+
+def compact_lines(lines, apps_by_turn=None):
+    """One log line for ``lines`` (history lines that left the window): the turns, the apps, op counts, macro
+    outcomes, searches, refusals and failures."""
+    turns, ops, searches, refusals, failures, covered = [], {}, [], 0, 0, 0
+    for line in lines:
+        found = HISTORY.match(str(line))
+        if not found:
+            continue
+        turns.append(int(found.group(1)))
+        rest = found.group(3)
+        op = OP.match(rest)
+        name = op.group(1) if op else None
+        if "refused" in rest:
+            refusals += 1
+        elif "failed" in rest:
+            failures += 1
+        if name:
+            ops[name] = ops.get(name, 0) + 1
+        typed = TEXT.search(rest)
+        if typed and name in ("TYPE_SUBMIT", "TYPE", "SET_TEXT"):
+            searches.append(typed.group(1))
+        watched = WATCHED.search(rest)
+        if watched and name in ("WATCH_FEED", "READ_EACH"):
+            covered += int(watched.group(1))
+    if not turns:
+        return None
+    first, last = min(turns), max(turns)
+    apps = []
+    for turn in range(first, last + 1):
+        app = (apps_by_turn or {}).get(turn)
+        if app and app not in apps:
+            apps.append(app)
+    head = f"Turns {first}-{last}" if first != last else f"Turn {first}"
+    if apps:
+        head += ", " + "/".join(apps[:3])
+    parts = []
+    if searches:
+        parts.append("typed " + ", ".join(f"'{s}'" for s in searches[:3]))
+    for name in ("WATCH_FEED", "READ_EACH", "READ_LIST", "RECALL"):
+        if ops.get(name):
+            times = {1: "once", 2: "twice"}.get(ops[name], f"{ops[name]} times")
+            parts.append(f"{name} {times}" + (f" ({covered} items)" if name in ("WATCH_FEED", "READ_EACH")
+                                              and covered else ""))
+    rest = {k: v for k, v in ops.items() if k not in ("WATCH_FEED", "READ_EACH", "READ_LIST", "RECALL", "TYPE_SUBMIT",
+                                                        "TYPE", "SET_TEXT")}
+    if rest:
+        parts.append(", ".join(f"{k} x{v}" for k, v in sorted(rest.items(), key=lambda kv: -kv[1])[:4]))
+    if refusals:
+        parts.append(f"{refusals} refused")
+    if failures:
+        parts.append(f"{failures} failed")
+    return head + ": " + ("; ".join(parts) if parts else "no actions") + "."
+
+
+class Compactor:
+    """Folds history lines that leave the prompt's window into the notebook's log, 8 at a time."""
+
+    def __init__(self, window=16):
+        self.window = window
+        self.done = 0
+
+    def fold(self, history, notebook, apps_by_turn=None):
+        """Compact what is due; returns the number of new log lines."""
+        added = 0
+        while len(history) - self.window - self.done >= COMPACT_EVERY:
+            chunk = history[self.done:self.done + COMPACT_EVERY]
+            self.done += COMPACT_EVERY
+            line = compact_lines(chunk, apps_by_turn)
+            if line:
+                notebook.add_log(line)
+                added += 1
+        return added