hyperagents 1.2.3rc5.post3__py3-none-any.whl

hyperclaw/brief/service.py

@@ -0,0 +1,424 @@
+"""Run, deliver and schedule the daily brief (docs/DAILY-BRIEF.md).
+
+Owner only: nothing here is reachable from a chat. Delivery goes to the
+terminal (latest.txt, `hyperclaw brief now|last`) and to the owner's Telegram
+chat(s) with link previews off. Failures are named with a fixed reason; a
+brief is never made up.
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+from dataclasses import dataclass, field
+from datetime import date, datetime, timedelta
+from typing import Callable, List, Optional
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+import httpx
+
+from hyperclaw.brief import collect as collect_mod
+from hyperclaw.brief import compose, diff, google_auth, links, store
+from hyperclaw.brief.errors import FIX, TEXT, BriefError, Reason
+from hyperclaw.brief.google import GoogleReader
+from hyperclaw.brief.tasks import read_tasks
+from hyperclaw.chat_scope import OWNER, owner_ids
+
+log = logging.getLogger("hyperclaw.brief")
+
+TELEGRAM_API = "https://api.telegram.org"
+TELEGRAM_LIMIT = 4096
+LATE_GRACE = timedelta(minutes=10)     # later than this after the slot = "late"
+SLEEP_GAP = timedelta(minutes=3)       # a tick gap longer than this = the Mac slept
+
+
+# ── notices (failure-notice standard) ─────────────────────────────────────
+
+def failure_notice(reason: Reason) -> str:
+    """'Sorry, I couldn't write today's brief. <why> <what to do>'. Names the
+    action, never implies success, never carries technical detail."""
+    detail = TEXT[reason][0].upper() + TEXT[reason][1:] + "."
+    fix = FIX.get(reason, "")
+    if fix:
+        detail += " " + fix
+    from hyperclaw.notices import failure_notice as standard
+    return standard(what="write today's brief", detail=detail, retry=False)
+
+
+def activity(status: str, message: str) -> None:
+    """One row in the activity log (tools/ledger.py). Never a link or an id."""
+    try:
+        from hyperclaw.tools.ledger import get_ledger
+        get_ledger().record(conversation="daily_brief", surface="scheduler", tool="daily_brief",
+                            effect="system", target="daily_brief", key=None, status=status,
+                            message=links.scrub(message))
+    except Exception as e:
+        log.warning("brief: could not write the activity log (%s)", type(e).__name__)
+
+
+# ── run ───────────────────────────────────────────────────────────────────
+
+@dataclass
+class Outcome:
+    ok: bool
+    text: str
+    reason: str = ""
+    sent: List[int] = field(default_factory=list)
+
+
+def tz() -> ZoneInfo:
+    name = store.tz_name()
+    if name:
+        try:
+            return ZoneInfo(name)
+        except (ZoneInfoNotFoundError, ValueError):
+            log.warning("brief: unknown timezone in config; using the system zone")
+    local = datetime.now().astimezone().tzinfo
+    return local  # type: ignore[return-value]
+
+
+def run_brief(*, now: Optional[datetime] = None, scope: str = OWNER, opening: List[str] = (),
+              registry=None, client_factory: Optional[Callable] = None, http_client=None,
+              google_http=None, sleep=None) -> Outcome:
+    """Read, write with V2, save. Never raises a BriefError."""
+    links.install_log_filter()
+    if scope != OWNER:
+        return Outcome(False, failure_notice(Reason.NOT_OWNER), Reason.NOT_OWNER.value)
+    now = now or datetime.now(tz())
+
+    def fail(reason: Reason, extra: List[str] = ()) -> Outcome:
+        text = "\n".join([o for o in opening if o] + [failure_notice(reason)] + list(extra))
+        store.save_latest(text)
+        store.update_state(last_result={"ok": False, "reason": reason.value,
+                                        "at": now.isoformat(timespec="seconds")})
+        return Outcome(False, text, reason.value)
+
+    doc_id, sheet_id = store.source_id("doc"), store.source_id("sheet")
+    if not doc_id and not sheet_id:
+        return fail(Reason.NO_SOURCES)
+    try:
+        compose.v2_route(registry)       # refuse before reading anything if V2 can't write it
+        token = google_auth.access_token(http=google_http)
+    except BriefError as e:
+        log.info("brief: not run (%s)", e.reason.value)
+        return fail(e.reason)
+
+    kw = {"client": http_client} if http_client is not None else {}
+    if sleep is not None:
+        kw["sleep"] = sleep
+    reader = GoogleReader(token, **kw)
+    try:
+        got = collect_mod.collect(reader, doc_id, sheet_id)
+    except BriefError as e:
+        log.info("brief: sources not read (%s)", e.reason.value)
+        return fail(e.reason)
+    finally:
+        if http_client is None:
+            reader.close()
+    try:
+        collect_mod.require_something(got)
+    except BriefError as e:
+        return fail(e.reason, [f"- {sk.label}: {TEXT[sk.reason]}." for sk in got.skipped
+                               if sk.role != "linked"])
+    for kind, src in (("doc", got.master), ("sheet", got.todo)):
+        if src is not None and src.title:
+            store.set_title(kind, src.title)
+
+    today = now.date()
+    snap = store.load_snapshot()
+    d = diff.compare(got, snap)
+    tl = read_tasks(got.todo.sheet, today) if got.todo and got.todo.sheet else None
+    model_text = None
+    if got.master:
+        try:
+            model_text = compose.write(got, d, tl, today, registry=registry,
+                                       client_factory=client_factory)
+        except BriefError as e:
+            log.info("brief: not written (%s)", e.reason.value)
+            return fail(e.reason)
+    text = compose.render(got, d, tl, model_text, today, opening=opening)
+    diff.maybe_replace(got, now, snap)
+    store.save_latest(text)
+    store.update_state(last_result={"ok": True, "reason": "",
+                                    "at": now.isoformat(timespec="seconds")})
+    return Outcome(True, text)
+
+
+DAY_HEADING = "Your day"
+
+
+def run_brief_with_day(*, now: Optional[datetime] = None, opening: List[str] = (),
+                       morning_sources=None, **kw) -> Outcome:
+    """The scheduled morning brief: the daily brief plus the "your day"
+    sections (calendar, email that needs you, Slack mentions and DMs, MRs
+    waiting on you) from whichever connectors are present (team.morning).
+    With no doc/sheet configured, the day sections are the brief."""
+    now = now or datetime.now(tz())
+    out = run_brief(now=now, opening=opening, **kw)
+    from hyperclaw.team import morning
+    if kw.get("scope", OWNER) != OWNER or not morning.enabled():
+        return out
+    try:
+        day = morning.render(now, morning_sources)
+    except Exception as e:
+        log.error("brief: day sections not built (%s)", type(e).__name__, exc_info=True)
+        return out
+    if not out.ok and out.reason == Reason.NO_SOURCES.value:
+        text = "\n".join([o for o in opening if o] + [DAY_HEADING, "", day])
+        store.save_latest(text)
+        store.update_state(last_result={"ok": True, "reason": "",
+                                        "at": now.isoformat(timespec="seconds")})
+        return Outcome(True, text)
+    text = out.text.rstrip() + "\n\n" + DAY_HEADING + "\n\n" + day
+    store.save_latest(text)
+    return Outcome(out.ok, text, out.reason, out.sent)
+
+
+# ── delivery ──────────────────────────────────────────────────────────────
+
+def _chunks(text: str, n: int = TELEGRAM_LIMIT) -> List[str]:
+    """Split at the last line break that fits, else hard at n."""
+    out = []
+    rest = text
+    while len(rest) > n:
+        cut = rest.rfind("\n", 0, n)
+        if cut <= 0:
+            cut = n
+        out.append(rest[:cut])
+        rest = rest[cut:].lstrip("\n")
+    if rest.strip():
+        out.append(rest)
+    return out
+
+
+def new_http() -> httpx.Client:
+    return httpx.Client(timeout=20.0, follow_redirects=False)
+
+
+def telegram_send(chat_id: int, text: str, *, client: Optional[httpx.Client] = None) -> bool:
+    """Bot API sendMessage with link previews OFF, plain text, confirmed by a
+    message_id receipt. The bot token is never logged."""
+    links.install_log_filter()
+    token = os.environ.get("TELEGRAM_BOT_TOKEN", "").strip()
+    if not token:
+        return False
+    base = os.environ.get("HYPERCLAW_BRIEF_TELEGRAM_API", "").strip()
+    if not base or (httpx.URL(base).host not in ("127.0.0.1", "localhost", "::1")):
+        base = TELEGRAM_API
+    c = client or new_http()
+    try:
+        from hyperclaw.tools.receipts import telegram_receipt
+        for part in _chunks(text):
+            resp = c.post(f"{base}/bot{token}/sendMessage", json={
+                "chat_id": chat_id, "text": part,
+                "link_preview_options": {"is_disabled": True},
+                "disable_web_page_preview": True,
+            })
+            mid, _why = telegram_receipt(resp)
+            if not mid:
+                log.error("brief: Telegram did not confirm delivery")
+                return False
+        return True
+    except httpx.HTTPError as e:
+        log.error("brief: Telegram delivery failed (%s)", type(e).__name__)
+        return False
+    finally:
+        if client is None:
+            c.close()
+
+
+async def deliver(outcome: Outcome, send: Optional[Callable] = None) -> List[int]:
+    """Send to the owner's Telegram chat(s) only (never a paired or guest chat)."""
+    sent: List[int] = []
+    text = (outcome.text or "").strip()
+    if not text:
+        return sent
+    for chat_id in sorted(owner_ids("telegram")):
+        try:
+            if send is not None:
+                ok = await send(int(chat_id), text)
+            else:
+                ok = await asyncio.to_thread(telegram_send, int(chat_id), text)
+            if ok:
+                sent.append(int(chat_id))
+        except Exception as e:
+            log.error("brief: Telegram delivery failed (%s)", type(e).__name__)
+    outcome.sent = sent
+    return sent
+
+
+# ── schedule: one brief a day, caught up once on wake ─────────────────────
+
+@dataclass
+class Due:
+    run: bool
+    late: bool = False
+    cause: str = ""                 # "asleep" | "not_running" | ""
+    missed: List[date] = field(default_factory=list)
+    slot: Optional[datetime] = None
+
+
+def _fmt_hm(dt) -> str:
+    return f"{dt.hour}:{dt.minute:02d}"
+
+
+def _fmt_day(d: date) -> str:
+    return d.strftime("%a %d %b").replace(" 0", " ")
+
+
+def first_day(scheduled_at: Optional[datetime], hh: int, mm: int) -> Optional[date]:
+    """The first day whose slot came after the schedule was set."""
+    if scheduled_at is None:
+        return None
+    slot = scheduled_at.replace(hour=hh, minute=mm, second=0, microsecond=0)
+    return scheduled_at.date() if scheduled_at <= slot else scheduled_at.date() + timedelta(days=1)
+
+
+def decide(now: datetime, hh: int, mm: int, *, last_run: Optional[date],
+           prev_tick: Optional[datetime], scheduled_at: Optional[datetime] = None) -> Due:
+    """Pure decision for one scheduler tick (now is local, tz-aware).
+
+    - before today's slot: nothing;
+    - today's brief already run (on time or caught up): nothing;
+    - otherwise run once. Late if more than LATE_GRACE after the slot: cause
+      "asleep" when this process ticked before the slot and then not for a
+      while (the Mac slept), "not_running" when this process wasn't up.
+    - days between the last brief and today whose slot passed with no brief
+      are "missed": today's brief says so; they are never run late."""
+    slot = now.replace(hour=hh, minute=mm, second=0, microsecond=0)
+    today = now.date()
+    if now < slot or last_run == today:
+        return Due(False, slot=slot)
+    late = now - slot > LATE_GRACE
+    cause = ""
+    if late:
+        if prev_tick is not None and prev_tick < slot and now - prev_tick > SLEEP_GAP:
+            cause = "asleep"
+        elif prev_tick is None:
+            cause = "not_running"
+    start = last_run + timedelta(days=1) if last_run else today
+    first = first_day(scheduled_at, hh, mm)
+    if first and first > start:
+        start = first
+    missed = [start + timedelta(days=i) for i in range((today - start).days)] \
+        if start < today else []
+    return Due(True, late=late, cause=cause, missed=missed, slot=slot)
+
+
+def opening_lines(due: Due, now: datetime) -> List[str]:
+    lines = []
+    if due.late and due.slot is not None:
+        at, ran = _fmt_hm(due.slot), _fmt_hm(now)
+        if due.cause == "asleep":
+            lines.append(f"This brief is late: your Mac was asleep at {at}, so it ran when you "
+                         f"opened it at {ran}.")
+        elif due.cause == "not_running":
+            lines.append(f"This brief is late: HyperAgents wasn't running at {at} (the Mac was "
+                         f"off or asleep, or HyperAgents was stopped), so it ran when it started "
+                         f"at {ran}.")
+        else:
+            lines.append(f"This brief is late: it was due at {at} and ran at {ran}.")
+    if due.missed:
+        days = ", ".join(_fmt_day(d) for d in due.missed)
+        n = len(due.missed)
+        lines.append(f"{'A day was' if n == 1 else f'{n} days were'} missed: there was no brief "
+                     f"on {days}. This is today's brief only.")
+    return lines
+
+
+class Ticker:
+    """The daily_brief job body: called every minute by the scheduler.
+    ``prev_tick`` lives in memory so a restart is told apart from a sleep."""
+
+    def __init__(self, *, clock: Optional[Callable[[], datetime]] = None,
+                 send: Optional[Callable] = None, run_kw: Optional[dict] = None):
+        self.clock = clock
+        self.send = send
+        self.run_kw = run_kw or {}
+        self.prev_tick: Optional[datetime] = None
+        self._lock = asyncio.Lock()
+
+    def _now(self) -> datetime:
+        return self.clock() if self.clock else datetime.now(tz())
+
+    async def tick(self) -> Optional[Outcome]:
+        async with self._lock:
+            now = self._now()
+            prev, self.prev_tick = self.prev_tick, now
+            st = store.load_state()
+            hh, mm = store.run_time()
+            last_run = _parse_date(st.get("last_run_date"))
+            sched_at = _parse_dt(store.config().get("scheduled_at"))
+            due = decide(now, hh, mm, last_run=last_run, prev_tick=prev, scheduled_at=sched_at)
+            if not due.run:
+                return None
+            # claim the day first: at most one brief (or catch-up) per day
+            store.update_state(last_run_date=now.date().isoformat())
+            for d in due.missed:
+                activity("missed", f"no brief on {d.isoformat()}: the slot passed with "
+                                   f"no run; replaced by today's brief")
+            opening = opening_lines(due, now)
+            try:
+                outcome = await asyncio.to_thread(
+                    lambda: run_brief_with_day(now=now, opening=opening, **self.run_kw))
+            except Exception as e:
+                log.error("brief: job failed (%s)", type(e).__name__, exc_info=True)
+                outcome = Outcome(False, "\n".join(opening + [failure_notice(Reason.INTERNAL)]),
+                                  Reason.INTERNAL.value)
+            if due.late:
+                activity("caught_up" if outcome.ok else "failed",
+                         f"{_fmt_hm(due.slot)} brief ran late at {_fmt_hm(now)} "
+                         f"({due.cause or 'late'})" + ("" if outcome.ok else
+                                                        f"; not written: {outcome.reason}"))
+            else:
+                activity("ok" if outcome.ok else "failed",
+                         f"{_fmt_hm(due.slot)} brief" + ("" if outcome.ok else
+                                                         f"; not written: {outcome.reason}"))
+            await deliver(outcome, self.send)
+            return outcome
+
+
+def _parse_date(v) -> Optional[date]:
+    try:
+        return date.fromisoformat(str(v)) if v else None
+    except ValueError:
+        return None
+
+
+def _parse_dt(v) -> Optional[datetime]:
+    try:
+        return datetime.fromisoformat(str(v)) if v else None
+    except ValueError:
+        return None
+
+
+# ── schedule gate / status ────────────────────────────────────────────────
+
+def named_in_env() -> bool:
+    raw = os.environ.get("HYPERCLAW_SCHEDULER_JOBS", "")
+    return store.JOB_ID in {n.strip().lower() for n in raw.split(",")}
+
+
+def opted_in() -> bool:
+    return named_in_env() or store.opted_in_by_config()
+
+
+def status() -> dict:
+    from hyperclaw import unattended
+    st = store.load_state()
+    srcs = store.sources()
+    hh, mm = store.run_time()
+    return {
+        "doc": bool((srcs.get("doc") or {}).get("id")),
+        "sheet": bool((srcs.get("sheet") or {}).get("id")),
+        "doc_title": (srcs.get("doc") or {}).get("title", ""),
+        "sheet_title": (srcs.get("sheet") or {}).get("title", ""),
+        "google": google_auth.connected(),
+        "unattended": unattended.enabled(),
+        "opted_in": opted_in(),
+        "time": f"{hh:02d}:{mm:02d}",
+        "tz": store.tz_name(),
+        "last_run_date": st.get("last_run_date", ""),
+        "last_result": st.get("last_result") or {},
+        "latest_path": str(store.latest_path()),
+    }

hyperclaw/brief/store.py

@@ -0,0 +1,205 @@
+"""Owner-only local files for the brief, all under $HYPERCLAW_ROOT/brief
+(default ~/.hyperclaw/brief, directory 0700, every file 0600):
+
+- ``sources.json``  the master Doc and to-do Sheet (file ids only, never the
+  link) and the titles last read from Google;
+- ``google-token.json``  the Google refresh/access token (read-only scopes);
+- ``snapshot.json``  yesterday's comparison copy: ONE file, replaced by the
+  first brief of each day, never uploaded, never logged;
+- ``state.json``  schedule bookkeeping (last scheduled run, last tick);
+- ``latest.txt``  the last brief, for the terminal.
+
+The schedule itself (time, timezone, opted in) is non-secret and lives in
+config.json under ``"brief"`` so the scheduler can read it.
+"""
+from __future__ import annotations
+
+import json
+import os
+import stat
+from pathlib import Path
+from typing import Optional
+
+from hyperclaw.userconfig import load_config, root, update_config
+
+JOB_ID = "daily_brief"
+DEFAULT_TIME = "06:00"
+
+
+def brief_dir() -> Path:
+    return root() / "brief"
+
+
+def sources_path() -> Path:
+    return brief_dir() / "sources.json"
+
+
+def token_path() -> Path:
+    return brief_dir() / "google-token.json"
+
+
+def snapshot_path() -> Path:
+    return brief_dir() / "snapshot.json"
+
+
+def state_path() -> Path:
+    return brief_dir() / "state.json"
+
+
+def latest_path() -> Path:
+    return brief_dir() / "latest.txt"
+
+
+def _ensure_dir() -> Path:
+    d = brief_dir()
+    d.mkdir(parents=True, exist_ok=True)
+    try:
+        os.chmod(d, 0o700)
+    except OSError:
+        pass
+    return d
+
+
+def write_private(p: Path, text: str) -> None:
+    """Atomic write, owner-only (0600) from the first byte."""
+    _ensure_dir()
+    p.parent.mkdir(parents=True, exist_ok=True)
+    tmp = p.with_name(p.name + ".tmp")
+    fd = os.open(str(tmp), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w", encoding="utf-8") as f:
+        f.write(text)
+    os.chmod(tmp, 0o600)
+    os.replace(tmp, p)
+
+
+def too_open(p: Path) -> bool:
+    try:
+        return bool(p.stat().st_mode & (stat.S_IRWXG | stat.S_IRWXO))
+    except FileNotFoundError:
+        return False
+
+
+def read_json(p: Path) -> dict:
+    try:
+        data = json.loads(p.read_text(encoding="utf-8"))
+        return data if isinstance(data, dict) else {}
+    except Exception:
+        return {}
+
+
+def write_json(p: Path, data: dict) -> None:
+    write_private(p, json.dumps(data, indent=2, ensure_ascii=False))
+
+
+# ── sources ───────────────────────────────────────────────────────────────
+
+def sources() -> dict:
+    """{"doc": {"id", "title"}, "sheet": {"id", "title"}} (either may be absent)."""
+    return read_json(sources_path())
+
+
+def set_source(kind: str, file_id: str, title: str = "") -> None:
+    data = sources()
+    data[kind] = {"id": file_id, "title": title}
+    write_json(sources_path(), data)
+
+
+def set_title(kind: str, title: str) -> None:
+    data = sources()
+    if kind in data:
+        data[kind]["title"] = title
+        write_json(sources_path(), data)
+
+
+def source_id(kind: str) -> str:
+    return str((sources().get(kind) or {}).get("id") or "")
+
+
+def clear_sources() -> bool:
+    try:
+        sources_path().unlink()
+        return True
+    except FileNotFoundError:
+        return False
+
+
+# ── snapshot (yesterday's comparison copy) ────────────────────────────────
+
+def load_snapshot() -> Optional[dict]:
+    p = snapshot_path()
+    if not p.exists():
+        return None
+    data = read_json(p)
+    return data or None
+
+
+def save_snapshot(data: dict) -> None:
+    """Replace the one snapshot. Never a history: the same path every day."""
+    write_json(snapshot_path(), data)
+
+
+# ── run state ─────────────────────────────────────────────────────────────
+
+def load_state() -> dict:
+    return read_json(state_path())
+
+
+def save_state(data: dict) -> None:
+    write_json(state_path(), data)
+
+
+def update_state(**kw) -> dict:
+    data = load_state()
+    for k, v in kw.items():
+        if v is None:
+            data.pop(k, None)
+        else:
+            data[k] = v
+    save_state(data)
+    return data
+
+
+def save_latest(text: str) -> None:
+    write_private(latest_path(), text)
+
+
+# ── schedule config (config.json "brief") ─────────────────────────────────
+
+def config() -> dict:
+    d = load_config().get("brief")
+    return d if isinstance(d, dict) else {}
+
+
+def set_config(**kw) -> dict:
+    d = config()
+    for k, v in kw.items():
+        if v is None:
+            d.pop(k, None)
+        else:
+            d[k] = v
+    update_config(brief=d)
+    return d
+
+
+def opted_in_by_config() -> bool:
+    return config().get("scheduled") is True
+
+
+def run_time() -> tuple:
+    """(hour, minute) of the daily brief; config brief.time "HH:MM"."""
+    parsed = parse_hhmm(str(config().get("time") or DEFAULT_TIME))
+    return parsed or parse_hhmm(DEFAULT_TIME)
+
+
+def parse_hhmm(raw: str) -> Optional[tuple]:
+    try:
+        h, m = (int(x) for x in raw.strip().split(":", 1))
+    except (ValueError, AttributeError):
+        return None
+    if 0 <= h < 24 and 0 <= m < 60:
+        return h, m
+    return None
+
+
+def tz_name() -> str:
+    return str(config().get("tz") or "")