yothere 1.5.2__py3-none-any.whl

yothere/__init__.py

@@ -0,0 +1,10 @@
+"""yothere — an ambient-agent cockpit (formerly relay-cockpit).
+
+Importing the package installs the YOTHERE_* <-> RELAY_* env aliasing so a host
+that still exports the legacy RELAY_* names keeps working unchanged. This is a
+pure os.environ read/fill with no filesystem side effects (importing yothere.*
+stays side-effect-free for the config/onboarding modules that rely on it).
+"""
+from yothere.envcompat import apply_process_aliases as _apply_env_aliases
+
+_apply_env_aliases()

yothere/attention.py

@@ -0,0 +1,236 @@
+"""Relay attention router — the moat.
+
+Camp-A cockpits decide which AGENT runs next. Relay decides which thread wants
+the HUMAN's eyes next, and protects focus while the rest of the fleet churns.
+This module is that decision, kept deterministic and offline-first so it is
+unit-testable and never depends on a model being reachable. The moat is this
+deterministic ranking — NOT an online learning loop (there is none; nothing
+here adapts from past recommendations).
+
+This module's one responsibility: rank_fleet / recommend_focus — score every
+normalized fleet row, order them, and name the one thread Phil should look at
+next.
+
+The Licklider ping guardrails (pull-on-glance default, quiet hours, focus
+protection, rate-limit) live in the runner's inline gate, not here.
+
+Autonomous advance selection (which non-focus threads to progress while Phil is
+busy) is owned solely by runner.plan_tick, not this module.
+"""
+from __future__ import annotations
+
+import datetime as _dt
+from dataclasses import dataclass
+
+try:  # zoneinfo is stdlib on 3.9+; degrade to host-local time if tz is unknown
+    from zoneinfo import ZoneInfo
+except Exception:  # pragma: no cover - zoneinfo always present on our runtime
+    ZoneInfo = None  # type: ignore
+
+# The fleet state vocabulary is owned by fleet_state (the normalization layer);
+# import it here instead of re-typing the literals.
+from yothere.fleet_state import BLOCKED, IDLE, READY, RUNNING
+
+# State base scores. Blocked beats ready: a blocked thread is stalled ON Phil
+# and burns no compute waiting; a ready one is finished and can sit.
+_STATE_BASE = {BLOCKED: 40.0, READY: 30.0, RUNNING: 5.0, IDLE: 0.0}
+
+
+@dataclass
+class RouterConfig:
+    timezone: str = "Europe/Berlin"
+    quiet_start_hour: int = 22
+    quiet_end_hour: int = 8
+    max_concurrent_advances: int = 2
+    min_advance_interval_s: int = 180
+    close_epsilon: float = 8.0
+
+
+@dataclass(frozen=True)
+class ScoreBreakdown:
+    row_id: str
+    source: str
+    title: str
+    state: str
+    needs_eyes: bool
+    total: float
+    parts: dict
+    reasons: tuple
+    focus: bool = False
+
+
+def _now() -> _dt.datetime:
+    return _dt.datetime.now(_dt.timezone.utc).astimezone()
+
+
+def _parse_iso(s: str | None) -> _dt.datetime | None:
+    if not s:
+        return None
+    try:
+        dt = _dt.datetime.fromisoformat(s)
+    except ValueError:
+        return None
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=_dt.timezone.utc)
+    return dt
+
+
+def _age_minutes(row: dict, now: _dt.datetime) -> float:
+    dt = _parse_iso(row.get("updated_at"))
+    if not dt:
+        return 0.0
+    return max(0.0, (now - dt).total_seconds() / 60.0)
+
+
+def score_row(row: dict, now: _dt.datetime) -> ScoreBreakdown:
+    """Additive weighted score: higher = wants Phil's eyes more, now."""
+    parts: dict = {}
+    reasons: list[str] = []
+
+    if row.get("needs_eyes"):
+        parts["needs_eyes"] = 100.0
+        reasons.append("needs your eyes")
+    else:
+        parts["needs_eyes"] = 0.0
+
+    state = row.get("state", RUNNING)
+    parts["state"] = _STATE_BASE.get(state, 0.0)
+
+    priority = (row.get("priority") or "normal").lower()
+    if priority == "urgent":
+        parts["urgency"] = 50.0
+        reasons.append("urgent")
+    elif priority == "high":
+        parts["urgency"] = 15.0
+        reasons.append("high priority")
+    elif priority == "low":
+        parts["urgency"] = -10.0
+    else:
+        parts["urgency"] = 0.0
+
+    # Deliverable is a TIEBREAK among ready threads, deliberately smaller than the
+    # blocked-vs-ready base gap (40-30=10) so a finished artifact never outranks a
+    # blocked thread that is actively stalling the fleet on Phil.
+    deliverable = state == READY and bool(row.get("artifacts") or row.get("last_progress"))
+    parts["deliverable"] = 8.0 if deliverable else 0.0
+    if deliverable:
+        reasons.append("has a finished artifact")
+
+    age = _age_minutes(row, now)
+    parts["staleness"] = min(15.0, age * 0.05)
+
+    if row.get("focus"):
+        parts["focus_pin"] = 12.0
+        reasons.append("you pinned this")
+    else:
+        parts["focus_pin"] = 0.0
+
+    total = round(sum(parts.values()), 3)
+    if state == BLOCKED:
+        reasons.append("blocked, waiting on you")
+    elif state == READY and not deliverable:
+        reasons.append("finished")
+    return ScoreBreakdown(
+        row_id=row["id"], source=row.get("source", "relay"), title=row.get("title", row["id"]),
+        state=state, needs_eyes=bool(row.get("needs_eyes")), total=total,
+        parts=parts, reasons=tuple(reasons), focus=bool(row.get("focus")),
+    )
+
+
+def rank_fleet(rows: list[dict], now: _dt.datetime | None = None,
+               cfg: RouterConfig | None = None) -> list[ScoreBreakdown]:
+    # cfg is accepted for caller parity but no longer read here: scoring is
+    # cfg-free and recommend_focus owns the close_epsilon read.
+    now = now or _now()
+    scored = [score_row(r, now) for r in rows]
+    # Sort: score desc, then needs_eyes, then older-first (updated_at), then id.
+    age_by_id = {r["id"]: _age_minutes(r, now) for r in rows}
+    scored.sort(key=lambda s: (-s.total, not s.needs_eyes, -age_by_id.get(s.row_id, 0.0), s.row_id))
+    return scored
+
+
+def recommend_focus(ranked: list[ScoreBreakdown], cfg: RouterConfig | None = None) -> dict | None:
+    """The single 'look at this next' rec.
+
+    Focus is single-source: the meta `focus` flag carried on each row (set by
+    `relay focus`/`spawn --focus`). A manually pinned thread wins even if it
+    ranks below the deterministic top; `margin` is signed (negative means the
+    pin overrode a higher-scored thread) and `pin_overrode_top` flags that so a
+    caller never mistakes the margin for an absolute gap.
+    """
+    cfg = cfg or RouterConfig()
+    if not ranked:
+        return None
+    pinned = next((s for s in ranked if s.focus), None)
+    if pinned is not None:
+        top, source_reason = pinned, "manual pin"
+    else:
+        top, source_reason = ranked[0], "top-ranked"
+    # Runner-up is the best score among the OTHER threads (always the true next-best).
+    runner_up = max((s.total for s in ranked if s.row_id != top.row_id), default=0.0)
+    margin = round(top.total - runner_up, 3)
+    pin_overrode_top = source_reason == "manual pin" and top.row_id != ranked[0].row_id
+    if pin_overrode_top:
+        confidence = "pinned"
+    elif len(ranked) == 1:
+        # A one-thread fleet is not a contest: do not imply a margin it never had.
+        confidence = "only"
+    else:
+        confidence = "close" if margin <= cfg.close_epsilon else "clear"
+    return {
+        "focus_id": top.row_id,
+        "focus_title": top.title,
+        "focus_source": source_reason,
+        "score": top.total,
+        "runner_up_score": runner_up,
+        "margin": margin,
+        "pin_overrode_top": pin_overrode_top,
+        "confidence": confidence,
+        "reasons": list(top.reasons),
+    }
+
+
+# ── Licklider guardrails ─────────────────────────────────────────────────────
+
+def in_quiet_hours(now: _dt.datetime, cfg: RouterConfig) -> bool:
+    # Quiet hours are defined in cfg.timezone (Berlin by default), not host-local
+    # time. Convert before reading the hour so a runner on a non-Berlin clock
+    # still respects Phil's nights. Read the field defensively: runner passes a
+    # RunnerConfig that may lack .timezone, and an unknown tz falls back to
+    # host-local, so neither caller breaks.
+    tz = getattr(cfg, "timezone", None)
+    if tz and ZoneInfo is not None:
+        try:
+            now = now.astimezone(ZoneInfo(tz))
+        except Exception:
+            pass
+    h = now.hour
+    if cfg.quiet_start_hour <= cfg.quiet_end_hour:
+        return cfg.quiet_start_hour <= h < cfg.quiet_end_hour
+    return h >= cfg.quiet_start_hour or h < cfg.quiet_end_hour
+
+
+if __name__ == "__main__":
+    cfg = RouterConfig()
+    # Fixed afternoon time so the selftest is deterministic (never trips quiet hours).
+    now = _dt.datetime(2026, 6, 8, 14, 0, tzinfo=_dt.timezone.utc).astimezone()
+    rows = [
+        {"id": "a", "title": "Vault synthesis", "state": "blocked", "needs_eyes": True,
+         "priority": "normal", "updated_at": now.isoformat()},
+        {"id": "b", "title": "News scan", "state": "running", "needs_eyes": False,
+         "priority": "normal", "updated_at": (now - _dt.timedelta(minutes=5)).isoformat()},
+        {"id": "c", "title": "LinkedIn draft", "state": "ready", "needs_eyes": True,
+         "priority": "normal", "artifacts": ["x.md"], "updated_at": now.isoformat()},
+        {"id": "d", "title": "Background crawl", "state": "running", "needs_eyes": False,
+         "priority": "low", "updated_at": (now - _dt.timedelta(minutes=20)).isoformat()},
+    ]
+    ranked = rank_fleet(rows, now, cfg)
+    assert ranked[0].row_id == "a", [s.row_id for s in ranked]  # blocked+eyes wins
+    rec = recommend_focus(ranked, cfg)
+    assert rec["focus_id"] == "a"
+    # Advance selection lives in runner.plan_tick, and the ping guardrails live in
+    # the runner's inline gate, not here — see runner.py.
+    # A one-thread fleet is reported as "only", not a fake "clear" contest.
+    solo = recommend_focus(rank_fleet([rows[0]], now, cfg), cfg)
+    assert solo["confidence"] == "only", solo
+    print("attention selftest ok")

yothere/board.py

@@ -0,0 +1,220 @@
+"""Relay board — the standalone glance surface.
+
+The Mission Control "Fleet" card is the at-a-glance summary embedded in the
+Personal OS dashboard. THIS is the dedicated, richer board: the focus
+recommendation up top, then every thread as a card with its state, live
+progress line, needs-eyes badge, deliverable link, age, and source. It is the
+screen half of Relay's voice-primary / screen-secondary model.
+
+Read-only and fail-soft: it reads the fleet via fleet_state.load_fleet() and
+ranks via attention. It NEVER writes thread state and never touches
+reports/mission-control.html (that stays the dashboard's file). Every dynamic
+field is run through html.escape — worker-authored progress strings are
+attacker-influenced (an LLM emits arbitrary text), so this is load-bearing, not
+cosmetic. No PAGE.format(): the HTML is concatenated, so there is no brace trap.
+"""
+from __future__ import annotations
+
+import datetime as _dt
+import html as _html
+import sys
+from pathlib import Path
+
+from yothere import attention as _att  # noqa: E402
+from yothere import card as _cardmod  # noqa: E402  (module alias; _card() below is the row renderer)
+from yothere.config import settings  # noqa: E402
+from yothere.fleet_state import BLOCKED, IDLE, READY, RUNNING, load_fleet  # noqa: E402
+
+OUT = settings.board_html_file
+
+STATE_COLOR = {RUNNING: "#b58900", READY: "#2aa198", BLOCKED: "#dc322f", IDLE: "#8c8c8a"}
+STATE_LABEL = {RUNNING: "WORKING", READY: "READY", BLOCKED: "BLOCKED", IDLE: "PARKED"}
+
+
+def esc(s: object) -> str:
+    return _html.escape(str(s if s is not None else ""))
+
+
+def _age(updated_at: str, now: _dt.datetime) -> str:
+    # Reuse attention._parse_iso so ISO parse + tz-coerce lives in one place.
+    dt = _att._parse_iso(updated_at)
+    if not dt:
+        return ""
+    secs = (now - dt).total_seconds()
+    if secs < 90:
+        return "just now"
+    if secs < 5400:
+        return f"{round(secs / 60)}m ago"
+    if secs < 36 * 3600:
+        return f"{round(secs / 3600)}h ago"
+    return f"{round(secs / 86400)}d ago"
+
+
+def _card(row: dict, now: _dt.datetime, is_focus: bool) -> str:
+    # Axis 3: a thread carrying a structured plan gets the rich progressive card
+    # (server-rendered from card.py, the single owner). card.esc() inside still
+    # escapes every worker-authored field. Threads without a plan keep the flat
+    # card below. build_plan_view returns None when there is no plan.
+    view = _cardmod.build_plan_view(row)
+    if view:
+        rich = _cardmod.render_card(view)
+        if is_focus:
+            rich = rich.replace('<div class="card">', '<div class="card focus">', 1)
+        return rich
+    state = row.get("state", RUNNING)
+    color = STATE_COLOR.get(state, "#8c8c8a")
+    label = STATE_LABEL.get(state, state.upper())
+    eye = '<span class="eye">needs eyes</span>' if row.get("needs_eyes") else ""
+    focus_cls = " focus" if is_focus else ""
+    age = _age(row.get("updated_at", ""), now)
+    prog = (row.get("last_progress") or "").strip()
+    prog_html = f'<div class="prog">{esc(prog[:200])}</div>' if prog else ""
+    # A blocked thread shows the exact decision it is waiting on, so the board
+    # says WHAT it needs, not just the last progress line. Worker-authored -> esc.
+    q_html = ""
+    if state == BLOCKED:
+        question = (row.get("question") or "").strip()
+        if question:
+            opts = [str(o).strip() for o in (row.get("options") or []) if str(o).strip()]
+            opt_html = ""
+            if opts:
+                chips = "".join(f'<span class="opt">{esc(o[:40])}</span>' for o in opts[:4])
+                opt_html = f'<div class="opts">{chips}</div>'
+            q_html = (f'<div class="ask"><span class="ask-l">needs</span> '
+                      f'{esc(question[:240])}</div>{opt_html}')
+    arts = row.get("artifacts") or []
+    art_html = ""
+    if arts:
+        links = " · ".join(esc(Path(str(a)).name) for a in arts[:4])
+        art_html = f'<div class="arts">📄 {links}</div>'
+    src = esc(row.get("source", "relay"))
+    return (
+        f'<div class="card{focus_cls}">'
+        f'<div class="top"><span class="dot" style="background:{color}"></span>'
+        f'<span class="title">{esc(row.get("title", row.get("id", "thread")))}</span>{eye}</div>'
+        f'<div class="meta"><span class="state" style="color:{color}">{label}</span>'
+        f'<span class="src">{src}</span><span class="age">{esc(age)}</span></div>'
+        f'{q_html}{prog_html}{art_html}</div>'
+    )
+
+
+def render_board(fleet: list[dict], now: _dt.datetime | None = None) -> str:
+    now = now or _dt.datetime.now(_dt.timezone.utc).astimezone()
+    cfg = _att.RouterConfig()
+    ranked = _att.rank_fleet(fleet, now, cfg)
+    rec = _att.recommend_focus(ranked, cfg)
+    order = {s.row_id: i for i, s in enumerate(ranked)}
+    fleet_sorted = sorted(fleet, key=lambda r: order.get(r["id"], 999))
+
+    need = sum(1 for r in fleet if r.get("needs_eyes"))
+    running = sum(1 for r in fleet if r.get("state") == RUNNING)
+
+    if rec:
+        reasons = ", ".join(rec.get("reasons") or []) or "top of the queue"
+        focus_html = (
+            f'<div class="focus-banner"><span class="fl">FOCUS</span>'
+            f'<span class="ft">{esc(rec["focus_title"])}</span>'
+            f'<span class="fr">{esc(reasons)}</span></div>'
+        )
+    else:
+        focus_html = ('<div class="focus-banner empty"><span class="ft">'
+                      'Fleet is clear. Nothing needs your eyes.</span></div>')
+
+    cards = "".join(_card(r, now, r["id"] == (rec or {}).get("focus_id")) for r in fleet_sorted)
+    if not fleet:
+        cards = ('<div class="empty-state">No agent threads in flight. '
+                 'Speak or type <code>relay spawn</code> to start one.</div>')
+
+    sub = f"{len(fleet)} threads · {running} working · {need} need eyes"
+    ts = now.strftime("%a %d %b · %H:%M:%S")
+
+    return (
+        "<!DOCTYPE html><html lang=en><head><meta charset=UTF-8>"
+        "<meta name=viewport content='width=device-width, initial-scale=1'>"
+        "<meta name=robots content='noindex, nofollow'>"
+        "<meta http-equiv=refresh content=15>"
+        "<title>Relay · Fleet</title>"
+        "<style>"
+        "*{box-sizing:border-box;margin:0;padding:0}"
+        "body{font:15px/1.5 -apple-system,Inter,Segoe UI,sans-serif;background:#0f1419;color:#e6e6e6;padding:24px;max-width:900px;margin:0 auto}"
+        "header{display:flex;align-items:baseline;gap:14px;margin-bottom:18px}"
+        "h1{font-size:18px;font-weight:700;letter-spacing:-.01em}"
+        ".sub{color:#8b98a5;font-size:13px}.ts{margin-left:auto;color:#5c6670;font-size:12px}"
+        ".focus-banner{display:flex;align-items:center;gap:12px;background:linear-gradient(90deg,#1e2630,#1a212b);"
+        "border:1px solid #2c3744;border-left:3px solid #D97757;border-radius:10px;padding:13px 16px;margin-bottom:16px}"
+        ".focus-banner.empty{border-left-color:#2aa198}"
+        ".fl{font-size:10px;font-weight:700;letter-spacing:.08em;color:#D97757;background:#2a1d18;padding:3px 8px;border-radius:5px}"
+        ".ft{font-weight:600;font-size:15px}.fr{margin-left:auto;color:#8b98a5;font-size:12px;text-align:right}"
+        ".grid{display:flex;flex-direction:column;gap:10px}"
+        ".card{background:#1a212b;border:1px solid #232c38;border-radius:10px;padding:13px 16px}"
+        ".card.focus{border-color:#D97757;box-shadow:0 0 0 1px #D9775733}"
+        ".top{display:flex;align-items:center;gap:9px}"
+        ".dot{width:9px;height:9px;border-radius:50%;flex:0 0 auto}"
+        ".title{font-weight:600;font-size:14.5px}"
+        ".eye{margin-left:auto;font-size:10px;font-weight:700;letter-spacing:.05em;color:#dc322f;background:#2a1517;padding:2px 7px;border-radius:5px}"
+        ".meta{display:flex;gap:12px;align-items:center;margin-top:5px;font-size:11.5px}"
+        ".state{font-weight:700;letter-spacing:.04em}.src{color:#5c6670}.age{margin-left:auto;color:#5c6670;font-variant-numeric:tabular-nums}"
+        ".prog{margin-top:8px;font-size:13px;color:#c4cdd6}"
+        ".ask{margin-top:8px;font-size:13px;color:#e6e6e6;background:#241a17;"
+        "border-left:2px solid #dc322f;border-radius:0 6px 6px 0;padding:6px 10px}"
+        ".ask-l{font-size:10px;font-weight:700;letter-spacing:.05em;color:#dc322f;margin-right:6px;text-transform:uppercase}"
+        ".opts{margin-top:5px;display:flex;gap:6px;flex-wrap:wrap}"
+        ".opt{font-size:11px;color:#c4cdd6;background:#1a212b;border:1px solid #2c3744;border-radius:5px;padding:2px 8px}"
+        ".arts{margin-top:6px;font-size:12px;color:#2aa198}"
+        "a.act-link{margin-left:14px;color:#D97757;font-size:12px;text-decoration:none;font-weight:600}"
+        "a.act-link:hover{text-decoration:underline}"
+        ".empty-state{color:#5c6670;text-align:center;padding:48px 0;font-size:14px}"
+        ".empty-state code{background:#1a212b;padding:2px 7px;border-radius:5px;color:#c4cdd6}"
+        # Card-scoped CSS from card.py so the rich progressive cards (badge, goal,
+        # step tree, next-action) render on the live board, in one place.
+        f"{_cardmod.CARD_CSS}"
+        "</style></head><body>"
+        f"<header><h1>Relay · Fleet</h1><span class=sub>{esc(sub)}</span>"
+        f"<a class=act-link href='http://127.0.0.1:8787/'>act &rarr;</a>"
+        f"<span class=ts>updated {esc(ts)} · 15s</span></header>"
+        f"{focus_html}<div class=grid>{cards}</div></body></html>"
+    )
+
+
+def build(open_after: bool = False) -> Path:
+    # Scope the board to the active user (settings.user). "" -> None -> no
+    # filtering (today's behaviour for the single-user default).
+    fleet = load_fleet(user=settings.user or None)
+    OUT.write_text(render_board(fleet), encoding="utf-8")
+    if open_after:
+        import subprocess
+        subprocess.run(["open", str(OUT)], check=False)
+    return OUT
+
+
+if __name__ == "__main__":
+    if len(sys.argv) > 1 and sys.argv[1] == "selftest":
+        now = _dt.datetime(2026, 6, 8, 14, 0, tzinfo=_dt.timezone.utc).astimezone()
+        # Empty fleet renders a clean empty state, no crash.
+        empty = render_board([], now)
+        assert "in flight" in empty and "FOCUS" not in empty
+        # XSS attempt in a worker-authored field must be escaped — including the
+        # blocked thread's question + options, which are also LLM-authored.
+        evil = [{"id": "x", "title": "<script>alert(1)</script>", "state": "blocked",
+                 "needs_eyes": True, "last_progress": "<img src=x onerror=alert(2)>",
+                 "question": "<b>which</b> path: A or B?",
+                 "options": ["<i>opt A</i>", "opt B"],
+                 "updated_at": now.isoformat(), "artifacts": ["a/b/c.md"]}]
+        html = render_board(evil, now)
+        # The only real vector is an unescaped tag delimiter. All payloads must
+        # appear ONLY in escaped form (inert text), never as live tags.
+        assert "<script>alert(1)" not in html, "raw <script> tag leaked"
+        assert "<img src=x onerror" not in html, "raw <img> tag leaked"
+        assert "<b>which" not in html and "<i>opt A" not in html, "raw question/option tag leaked"
+        assert "&lt;script&gt;alert(1)" in html and "&lt;img src=x onerror" in html
+        assert "c.md" in html  # artifact basename, path stripped
+        assert "FOCUS" in html and "needs eyes" in html
+        # The blocked thread surfaces its question + options, and the board links
+        # to the cockpit for actions.
+        assert "which" in html and "path: A or B" in html, "blocked question not shown"
+        assert "opt B" in html, "blocked options not shown"
+        assert "127.0.0.1:8787" in html, "cockpit deep-link missing"
+        print("board selftest ok")
+    else:
+        out = build(open_after="--open" in sys.argv)
+        print(f"built relay board -> {out}")

yothere/brain/__init__.py

@@ -0,0 +1,16 @@
+"""Brain registry — named brains a Relay thread can target.
+
+A thread no longer has to run on the single hardcoded RELAY_REMOTE_BRAIN_URL.
+``brains.yaml`` (at ``settings.brains_file``) maps a brain name to a connection
+descriptor (local claude, a ubob daemon, or any Brain-Protocol endpoint); a
+thread picks one by setting its meta ``brain`` key, and the fleet path resolves
+the harness + url + token from this registry.
+
+Back-compat: with no brains.yaml the registry falls back to today's env-driven
+behaviour, so existing single-brain fleets are unaffected.
+"""
+from __future__ import annotations
+
+from yothere.brain.registry import BrainDescriptor, load_brains, resolve
+
+__all__ = ["BrainDescriptor", "load_brains", "resolve"]