mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/longform/recall.py

@@ -0,0 +1,195 @@
+"""RECALL (DESIGN §6.4, §8.3): the model searches this conversation's earlier tasks and this task's notebook."""
+
+import re
+
+from ..agent_hooks import Prepared, SkillResult
+from .notebook import cut
+
+OP = "RECALL"
+PROMPT = ("- RECALL text: search this conversation's earlier tasks and this task's notebook for text. The matching "
+          "lines come back on the next turn.")
+MAX_LINES = 12
+LINE_CHARS = 240
+STOP = frozenset({"the", "and", "for", "with", "that", "this", "what", "which", "from", "about", "was", "were", "are",
+                  "you", "your", "my", "one", "ones", "did", "does", "its", "it's", "of", "to", "in", "on", "a", "an"})
+NO_TEXT = "RECALL needs the words to look for in text."
+NOTHING = "RECALL found nothing for {query!r} in this conversation or this task's notebook."
+
+
+def words(query):
+    return [w for w in re.findall(r"[a-z0-9@#$'.-]{2,}", str(query or "").casefold()) if w.strip(".-'") not in STOP]
+
+
+def notebook_lines(book, label=None):
+    """(line, recency) for a notebook's items and facts; ``label`` ("turn 3") marks an earlier run's."""
+    out = []
+    prefix = f"{label}, " if label else ""
+    with book.lock if hasattr(book, "lock") else _Null():
+        for index, item in enumerate(book.items):
+            if item.skip is not None:
+                continue
+            extract = item.extract or {}
+            text = " ".join(str(x) for x in (item.who(), item.summary(), " ".join(extract.get("tags") or ()),
+                                             " ".join(str(c) for c in extract.get("claims") or ()),
+                                             item.text.get("caption") or "") if x)
+            out.append((f"[{prefix}{item.id}] {text}", index))
+        for index, fact in enumerate(book.facts):
+            out.append((f"[{prefix}{fact.id}] {fact.text}", len(book.items) + index))
+    return out
+
+
+class _Null:
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        return False
+
+
+def thread_lines(ctx):
+    """(line, recency) for the thread's earlier exchanges, and their notebooks while retained."""
+    thread_id = getattr(ctx, "thread_id", None)
+    if not thread_id:
+        return []
+    try:
+        from ..threads.context import exchanges
+        from ..threads.service import service_for
+    except ImportError:
+        return []
+    service = service_for(ctx.runtime)
+    if service is None:
+        return []
+    try:
+        done = exchanges(service.store.items(thread_id), exclude_run=ctx.run_id)
+    except Exception:  # noqa: BLE001
+        return []
+    out = []
+    journal = getattr(ctx.runtime, "journal", None)
+    for turn, exchange in enumerate(done, 1):
+        label = f"turn {turn}"
+        recency = turn * 1000
+        out.append((f"[{label}] asked: {exchange['ask']}", recency))
+        context = exchange.get("context") or {}
+        answer = context.get("answer") or (exchange.get("result") or {}).get("answer")
+        if answer:
+            out.append((f"[{label}] answer: {answer}", recency + 1))
+        for note in context.get("notes") or ():
+            out.append((f"[{label}] note: {note}", recency + 2))
+        for referent in context.get("referents") or ():
+            out.append((f"[{label}] {referent.get('rank')}. {referent.get('text')}", recency + 3))
+        if context.get("report"):
+            for line in str(context["report"]).splitlines():
+                out.append((f"[{label}] report: {line}", recency + 4))
+        try:
+            from .notebook import Notebook
+            from .store import load_notebook
+            data = load_notebook(journal, exchange["runId"])
+        except Exception:  # noqa: BLE001
+            data = None
+        if data:
+            book = Notebook.from_dict(data)
+            out += [(line, recency + 5) for line, _ in notebook_lines(book, label)]
+    return out
+
+
+def search(query, lines):
+    """The best MAX_LINES of ``lines`` for ``query``: most query words matched, then the newest."""
+    wanted = words(query)
+    if not wanted:
+        return []
+    scored = []
+    for line, recency in lines:
+        folded = line.casefold()
+        score = sum(1 for word in wanted if word in folded)
+        if score:
+            scored.append((score, recency, line))
+    scored.sort(key=lambda entry: (-entry[0], -entry[1]))
+    best = scored[:MAX_LINES]
+    best.sort(key=lambda entry: entry[1])
+    return [cut(line, LINE_CHARS) for _, _, line in best]
+
+
+class Recall:
+    """agent_hooks.Skill: RECALL."""
+
+    op = OP
+    prompt = PROMPT
+    needs_target = False
+
+    def __init__(self, ctx):
+        self.ctx = ctx
+
+    def prepare(self, ctx, act, snapshot):
+        return Prepared(None)   # reading notes approves nothing
+
+    def perform(self, ctx, prepared, act, snapshot):
+        query = " ".join(str(act.get("text") or act.get("target_label") or "").split())[:200]
+        if not query:
+            return SkillResult(NO_TEXT)
+        from .session import for_run
+        lines = thread_lines(self.ctx)
+        session = for_run(self.ctx.run_id)
+        if session is not None:
+            lines += [(line, 10 ** 7 + recency) for line, recency in notebook_lines(session.notebook)]
+        found = search(query, lines)
+        if not found:
+            return SkillResult(NOTHING.format(query=query))
+        from ..harness_api import fence
+        text = "\n".join(found).replace("<<<", "‹‹‹").replace(">>>", "›››")
+        return SkillResult(fence(f"RECALL found {len(found)} lines for {query!r}", text), changed=False)
+
+
+def factory(ctx):
+    """register_tool's factory: RECALL in a long run, or in a run in a thread with earlier tasks; else None."""
+    if getattr(ctx, "engine", None) != "smart":
+        return None
+    from .session import for_run
+    if for_run(ctx.run_id) is not None:
+        return Recall(ctx)
+    thread_id = getattr(ctx, "thread_id", None)
+    if not thread_id:
+        return None
+    try:
+        from ..threads.service import service_for
+        service = service_for(ctx.runtime)
+        earlier = service is not None and any(
+            item.get("kind") == "run" and item.get("runId") != ctx.run_id for item in service.store.items(thread_id))
+    except Exception:  # noqa: BLE001
+        earlier = False
+    return Recall(ctx) if earlier else None
+
+
+EARLIER_RUNS = 5
+
+
+def earlier_identities(runtime, thread_id, run_id, kind=None):
+    """The item identities the conversation's earlier long tasks (the newest EARLIER_RUNS, of ``kind`` when given)
+    saw and kept, from their notebooks while their runs are retained: a "scroll again" skips what the person already
+    has."""
+    if not thread_id:
+        return set()
+    try:
+        from ..threads.context import exchanges
+        from ..threads.service import service_for
+        from .store import load_notebook
+        service = service_for(runtime)
+        if service is None:
+            return set()
+        done = exchanges(service.store.items(thread_id), exclude_run=run_id)
+    except Exception:  # noqa: BLE001
+        return set()
+    journal = getattr(runtime, "journal", None)
+    found, runs = set(), 0
+    for exchange in reversed(done):
+        if not (exchange.get("context") or {}).get("report"):
+            continue
+        data = load_notebook(journal, exchange["runId"])
+        if not data or (kind and data.get("kind") != kind):
+            continue
+        found |= {item.get("identity") for item in data.get("items") or ()
+                  if item.get("identity") and item.get("skip") in (None, "off_topic")}
+        found |= set(data.get("earlier") or ())
+        runs += 1
+        if runs == EARLIER_RUNS:
+            break
+    return found

mobile_agent/longform/receipts.py

@@ -0,0 +1,81 @@
+"""Bounded outcome snapshots from the run's existing proof-gated task contract.
+
+Plan steps describe navigation. These snapshots describe what the contract could actually
+confirm, with the source run retained so a resumed task never conflates item numbers.
+"""
+
+MAX_RUNS = 12
+MAX_ITEMS = 24                    # contract.MAX_ITEMS
+MAX_EVIDENCE = 8
+
+
+def _text(book, value, limit=300):
+    text = " ".join(str(value or "").split())
+    text = " ".join(str(book.mask(text) or "").split())
+    return text[:limit - 1].rstrip() + "…" if len(text) > limit else text
+
+
+def status(items):
+    """Only an explicit receipt can make an outcome complete."""
+    positive = [item for item in items if item["kind"] != "FORBID"]
+    if positive and all(item["outcome"] == "completed" for item in positive):
+        return "completed"
+    if any(item["outcome"] in ("completed", "partial") for item in positive):
+        return "partial"
+    return "unverified"
+
+
+def snapshot(book, contract, *, final=False):
+    """Copy a contract's current facts; never retain the live mutable contract or raw screen data."""
+    if contract is None:
+        return None
+    rows = []
+    for item in list(getattr(contract, "items", ()) or ())[:MAX_ITEMS]:
+        try:
+            gated, reason = contract.proof(item)
+        except Exception:  # proof failure cannot become completion
+            gated, reason = False, "proof could not be checked"
+        evidence = []
+        all_receipts = item.receipts or ()
+        confirmed_count = sum(bool(receipt.get("receipt")) and receipt.get("receipt") != "screen changed"
+                              for receipt in all_receipts) if item.kind == "COMMIT" else 0
+        for receipt in all_receipts[:MAX_EVIDENCE]:
+            line = _text(book, receipt.get("receipt"))
+            if line:
+                evidence.append({"kind": "screen_change" if line == "screen changed" else "screen_receipt",
+                                 "runId": book.run_id,
+                                 "turn": receipt.get("step") if type(receipt.get("step")) is int else None,
+                                 "text": line, "screen": None})
+        needed = item.needed() if item.kind == "COMMIT" else None
+        # An open-ended "each" count, a forbidden action, and a gate satisfied by a model
+        # claim alone have no bounded positive completion receipt.
+        complete = bool(item.kind == "COMMIT" and gated and needed is not None
+                        and confirmed_count >= needed)
+        outcome = "completed" if complete else "partial" if confirmed_count else "unverified"
+        rows.append({"id": item.id, "kind": item.kind, "app": _text(book, item.app, 80) or None,
+                     "what": _text(book, item.what, 200), "requested": _text(book, item.payload, 200) or None,
+                     "recordedValue": _text(book, item.value, 300) if item.kind == "REPORT" and item.value else None,
+                     "valueTurn": item.value_step if type(item.value_step) is int else None,
+                     "gateSatisfied": bool(gated), "reason": _text(book, reason or item.reason, 200) or None,
+                     "outcome": outcome, "evidence": evidence,
+                     "evidenceOmitted": max(0, len(all_receipts) - len(evidence))})
+    return {"runId": book.run_id, "final": bool(final), "outcome": status(rows), "items": rows}
+
+
+def put(book, entry):
+    """Replace this run's checkpoint snapshot; keep older source runs separate on pickup."""
+    if entry is None:
+        return
+    with book.lock:
+        book.receipts = [old for old in book.receipts if old.get("runId") != entry["runId"]]
+        book.receipts.append(entry)
+        if len(book.receipts) > MAX_RUNS:
+            book.receipt_runs_omitted += len(book.receipts) - MAX_RUNS
+            book.receipts = book.receipts[-MAX_RUNS:]
+        book.revision += 1
+
+
+def overall(entries, run_id):
+    """Only this run's contract can determine its outcome; older runs remain provenance."""
+    current = next((entry for entry in reversed(entries) if entry.get("runId") == run_id), None)
+    return current.get("outcome", "unverified") if current and current.get("final") else "unverified"

mobile_agent/longform/register.py

@@ -0,0 +1,124 @@
+"""Track ``longform``'s registrations (tracks.load calls ``register(api)`` once per process, staged)."""
+
+import math
+
+from . import TRACK
+
+
+def validate_field(value, runtime):
+    """``longform``: an object with planId (a plan card's id), alternative ("full"), budget and capUsd."""
+    if not isinstance(value, dict) or set(value) - {"planId", "alternative", "budget", "capUsd"}:
+        raise ValueError("longform takes planId, alternative, budget and capUsd")
+    clean = {}
+    if value.get("planId") is not None:
+        if not isinstance(value["planId"], str) or not value["planId"].startswith("p_") or len(value["planId"]) > 20:
+            raise ValueError("longform.planId is a plan's id")
+        clean["planId"] = value["planId"]
+    if value.get("alternative") is not None:
+        if value["alternative"] not in ("full", "more"):
+            raise ValueError("longform.alternative is full or more")
+        clean["alternative"] = value["alternative"]
+    if value.get("budget") is not None:
+        from .budget import ALL_CAP, Budget, override
+        override(Budget("items", None, ALL_CAP, False, 600.0, "items", "", "row"), value["budget"])  # shape check
+        clean["budget"] = dict(value["budget"])
+    if value.get("capUsd") is not None:
+        from ..runtime_limits import TASK_LIMIT_RANGE
+        cap = value["capUsd"]
+        if isinstance(cap, bool) or not isinstance(cap, (int, float)) or not math.isfinite(cap) \
+                or not TASK_LIMIT_RANGE[0] <= cap <= TASK_LIMIT_RANGE[1]:
+            raise ValueError("longform.capUsd is between $0.05 and $100")
+        clean["capUsd"] = round(float(cap), 2)
+    return clean
+
+
+def frontier_options(ctx):
+    """A long run's caps: 60 + 12 a step + 1 per 10 items turns (at most 600), the phone-time cap plus 300 s (at
+    most 7,200)."""
+    from .budget import turn_caps
+    from .session import for_run
+    session = for_run(ctx.run_id)
+    if session is None:
+        return {}
+    steps = len(session.plan.get("steps") or ()) or 1
+    max_steps, max_seconds = turn_caps(session.budget, steps)
+    used = getattr(session, "turns_used", 0) or 0
+    return {"max_steps": int(min(600, max_steps + used)), "max_seconds": float(min(7200.0, max_seconds))}
+
+
+def feed_factory(ctx):
+    from .feed import factory
+    return factory(ctx)
+
+
+def items_factory(ctx):
+    from .items import factory
+    return factory(ctx)
+
+
+def recall_factory(ctx):
+    from .recall import factory
+    return factory(ctx)
+
+
+def pickup(ctx, driver, approve):
+    """Pre-run hook (order 1, after harness's pick-up): a picked-up long run keeps its notebook, its counters, its
+    step states and its remaining budget."""
+    from .. import harness_api
+    source = (ctx.extras or {}).get("resumeFrom")
+    if not source or harness_api.disabled(TRACK):
+        return None
+    from .store import load_notebook
+    runtime = ctx.runtime
+    data = load_notebook(getattr(runtime, "journal", None), source)
+    if data is None:
+        return None
+    from .session import _pickups
+    turns = 0
+    checkpoint_phone = {}
+    try:
+        from ..harness.checkpoints import load
+        state = load(runtime.journal, source) or {}
+        turns = int(state.get("step") or 0)
+        longform = state.get("longform")
+        if isinstance(longform, dict) and "phoneSeconds" in longform:
+            checkpoint_phone["phone_seconds"] = longform["phoneSeconds"]
+        elif longform is not None and not isinstance(longform, dict):
+            checkpoint_phone["phone_seconds"] = None  # damaged checkpoint cannot grant more phone time
+    except Exception:  # noqa: BLE001 -- a damaged checkpoint may not grant a fresh phone budget
+        turns = 0
+        checkpoint_phone["phone_seconds"] = None
+    original = (getattr(runtime, "runs", None) or {}).get(source)
+    _pickups[ctx.run_id] = {"notebook": data, "source": source, "turns": turns,
+                            "cost_usd": getattr(original, "cost_usd", None) or 0.0, **checkpoint_phone}
+    ctx.emit({"event": "longform_picked_up", "from": source, "items": len(data.get("items") or ()),
+              "kept": (data.get("counters") or {}).get("kept", 0)})
+    return None
+
+
+pickup.after_handoff = True
+
+
+def followup_hook(ctx, driver, approve):
+    from .followup import pre_run
+    return pre_run(ctx, driver, approve)
+
+
+followup_hook.before_phone = True
+
+
+def register(api):
+    """``api`` is mobile_agent.harness_api."""
+    from .. import api_routes, journal
+    from . import routes, store
+    journal.register_schema(store.SCHEMA, store.VERSION, store.migrate)
+    api.register_run_field("longform", validate_field)
+    api.register_frontier_options(frontier_options)
+    api.register_tool(feed_factory, order=5)
+    api.register_tool(items_factory, order=5)
+    api.register_tool(recall_factory, order=5)
+    api.register_pre_run(pickup, order=1)
+    api.register_pre_run(followup_hook, order=5)
+    api.register_service(lambda runtime: None, store.close)
+    for route in routes.ROUTES:
+        api_routes.register(route)