hyperagents 1.2.3rc5.post3__py3-none-any.whl

hyperclaw/teamsetup/service.py

@@ -0,0 +1,495 @@
+"""The one background service of a team install (8.2a design, Vaughn 12 Oct).
+
+ONE process hosts the Telegram bot AND the scheduler (the morning brief, and
+the GitLab digest when connected), so the bot has exactly one Telegram
+connection. It starts at login, keeps running across restarts and sleep, and
+is restarted by the OS if it stops with an error.
+
+- macOS: a LaunchAgent ``com.hyperclaw.agent`` (``RunAtLoad``, ``KeepAlive``
+  on failure) in ``~/Library/LaunchAgents``.
+- Linux: a systemd user unit ``hyperclaw-agent.service``
+  (``Restart=on-failure``, ``WantedBy=default.target``).
+
+Its environment sets ``HYPERCLAW_UNATTENDED=1`` and names its jobs in
+``HYPERCLAW_SCHEDULER_JOBS`` (``daily_brief``, plus ``connected_digest`` when
+GitLab is connected): nothing else runs on its own. No secret is in the
+service definition; secrets come from the OS secret store at start.
+
+- **One Telegram connection.** A lock file (``$HYPERCLAW_ROOT/run/telegram.lock``)
+  is held by whichever process polls the bot (this service or
+  ``hyperclaw-telegram``); a second one exits. ``install`` refuses while an
+  older HyperAgents service (``com.hyperclaw`` / ``com.hyperclaw.telegram``)
+  is loaded, and never stops it.
+- **Sleep.** After a wake (the wall clock jumped ahead of the monotonic clock)
+  the service exits with status 75 and the OS starts it fresh, so the
+  Telegram connection is new; the brief catches up once (hyperclaw.brief).
+- **Housekeeping** (hourly): Slack sign-in refresh before its expiry, with a
+  Telegram notice in plain words three days before Slack's 30 days run out
+  and when Slack needs a new sign-in; and a
+  Telegram notice once per newer signed release ("run hyperclaw upgrade").
+- **No remote shell over chat, ever.** The service registers no handler of
+  its own; the bot's commands are fixed (tests/unit/teamsetup/test_service.py).
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+import plistlib
+import shutil
+import subprocess
+import sys
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable, Optional
+
+log = logging.getLogger("hyperclaw.service")
+
+LABEL = "com.hyperclaw.agent"
+UNIT = "hyperclaw-agent.service"
+OLD_LABELS = ("com.hyperclaw", "com.hyperclaw.telegram")
+WAKE_EXIT = 75
+WAKE_JUMP = 120.0          # seconds the wall clock may run ahead before we call it a wake
+HOUSEKEEPING_EVERY = 3600.0
+Runner = Callable[..., subprocess.CompletedProcess]
+
+
+def _root() -> Path:
+    from hyperclaw.userconfig import root
+    return root()
+
+
+def platform() -> str:
+    if sys.platform == "darwin":
+        return "launchd"
+    if sys.platform.startswith("linux") and shutil.which("systemctl"):
+        return "systemd"
+    return ""
+
+
+def plist_path() -> Path:
+    return Path.home() / "Library" / "LaunchAgents" / f"{LABEL}.plist"
+
+
+def unit_path() -> Path:
+    return Path.home() / ".config" / "systemd" / "user" / UNIT
+
+
+def log_path() -> Path:
+    return _root() / "logs" / "service.log"
+
+
+def program_args() -> list:
+    """The interpreter of this install (the pipx venv), so an upgrade in place
+    keeps the service pointing at the right code."""
+    return [sys.executable, "-m", "hyperclaw.teamsetup.service", "run"]
+
+
+def jobs() -> list:
+    out = ["daily_brief"]
+    try:
+        from hyperclaw.digest import state
+        if state.connections().get("gitlab"):
+            out.append("connected_digest")
+    except Exception:
+        pass
+    return out
+
+
+def service_env() -> dict:
+    from hyperclaw.deployment import is_hyper
+    env = {
+        "HYPERCLAW_UNATTENDED": "1",
+        "HYPERCLAW_SCHEDULER_JOBS": ",".join(jobs()),
+        "HYPERCLAW_ROOT": str(_root()),
+        "PATH": f"{Path(sys.executable).parent}:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin",
+        "PYTHONUNBUFFERED": "1",
+    }
+    if is_hyper():
+        env["HYPERCLAW_DEPLOYMENT"] = "hyper"
+    return env
+
+
+def plist_bytes() -> bytes:
+    logs = str(log_path())
+    return plistlib.dumps({
+        "Label": LABEL,
+        "ProgramArguments": program_args(),
+        "EnvironmentVariables": service_env(),
+        "WorkingDirectory": str(_root()),
+        "RunAtLoad": True,
+        "KeepAlive": {"SuccessfulExit": False},     # restart after a crash or a wake exit
+        "ThrottleInterval": 10,
+        "ProcessType": "Standard",
+        "StandardOutPath": logs,
+        "StandardErrorPath": logs,
+    })
+
+
+def unit_text() -> str:
+    env = "\n".join(f'Environment="{k}={v}"' for k, v in service_env().items())
+    args = " ".join(program_args())
+    return (f"[Unit]\nDescription=HyperAgents (Telegram + scheduler)\n"
+            f"After=network-online.target\n\n[Service]\nExecStart={args}\n{env}\n"
+            f"Restart=on-failure\nRestartSec=10\nStandardOutput=append:{log_path()}\n"
+            f"StandardError=append:{log_path()}\n\n[Install]\nWantedBy=default.target\n")
+
+
+@dataclass
+class Result:
+    ok: bool
+    line: str
+
+
+def _gui() -> str:
+    return f"gui/{os.getuid()}"
+
+
+def _loaded(label: str, run: Runner) -> bool:
+    r = run(["launchctl", "print", f"{_gui()}/{label}"], capture_output=True, text=True)
+    return r.returncode == 0
+
+
+def install(*, run: Runner = subprocess.run) -> Result:
+    """Write the service definition and start it. Idempotent."""
+    kind = platform()
+    log_path().parent.mkdir(parents=True, exist_ok=True)
+    if kind == "launchd":
+        busy = [lb for lb in OLD_LABELS if _loaded(lb, run)]
+        if busy:
+            return Result(False, "✗ Background service: another HyperAgents service is already "
+                                 f"running on this Mac ({', '.join(busy)}), and two would mean "
+                                 "two Telegram connections. Fix: tell Vaughn; nothing was "
+                                 "changed.")
+        p = plist_path()
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_bytes(plist_bytes())
+        os.chmod(p, 0o644)
+        if _loaded(LABEL, run):
+            run(["launchctl", "bootout", f"{_gui()}/{LABEL}"], capture_output=True, text=True)
+        r = run(["launchctl", "bootstrap", _gui(), str(p)], capture_output=True, text=True)
+        if r.returncode != 0:
+            return Result(False, "✗ Background service: macOS didn't start it. Fix: run "
+                                 "hyperclaw service install again, then hyperclaw self-check.")
+        run(["launchctl", "enable", f"{_gui()}/{LABEL}"], capture_output=True, text=True)
+        return Result(True, "✓ Connected: background service (starts at login)")
+    if kind == "systemd":
+        p = unit_path()
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(unit_text(), encoding="utf-8")
+        run(["systemctl", "--user", "daemon-reload"], capture_output=True, text=True)
+        r = run(["systemctl", "--user", "enable", "--now", UNIT], capture_output=True, text=True)
+        if r.returncode != 0:
+            return Result(False, "✗ Background service: systemd didn't start it. Fix: run "
+                                 "hyperclaw service install again, then hyperclaw self-check.")
+        run(["systemctl", "--user", "restart", UNIT], capture_output=True, text=True)
+        return Result(True, "✓ Connected: background service (starts at login)")
+    return Result(False, "✗ Background service: this computer has no supported service "
+                         "manager (macOS or Linux with systemd). Fix: tell Vaughn.")
+
+
+def uninstall(*, run: Runner = subprocess.run) -> Result:
+    kind = platform()
+    if kind == "launchd":
+        if _loaded(LABEL, run):
+            run(["launchctl", "bootout", f"{_gui()}/{LABEL}"], capture_output=True, text=True)
+        plist_path().unlink(missing_ok=True)
+    elif kind == "systemd":
+        run(["systemctl", "--user", "disable", "--now", UNIT], capture_output=True, text=True)
+        unit_path().unlink(missing_ok=True)
+    return Result(True, "Background service removed.")
+
+
+def status(*, run: Runner = subprocess.run) -> dict:
+    """{"installed", "running", "pid"} (no secrets)."""
+    kind = platform()
+    if kind == "launchd":
+        installed = plist_path().exists()
+        r = run(["launchctl", "print", f"{_gui()}/{LABEL}"], capture_output=True, text=True)
+        out = r.stdout or "" if r.returncode == 0 else ""
+        pid = ""
+        for line in out.splitlines():
+            s = line.strip()
+            if s.startswith("pid = "):
+                pid = s.split("=", 1)[1].strip()
+        running = "state = running" in out
+        return {"installed": installed, "running": running, "pid": pid, "manager": kind}
+    if kind == "systemd":
+        r = run(["systemctl", "--user", "is-active", UNIT], capture_output=True, text=True)
+        return {"installed": unit_path().exists(),
+                "running": (r.stdout or "").strip() == "active", "pid": "", "manager": kind}
+    return {"installed": False, "running": False, "pid": "", "manager": ""}
+
+
+def check(*, run: Runner = subprocess.run) -> Result:
+    st = status(run=run)
+    if not st["installed"]:
+        return Result(False, "✗ Background service: not installed. Fix: hyperclaw onboard "
+                             "--team --step service")
+    if not st["running"]:
+        return Result(False, "✗ Background service: installed but not running. Fix: hyperclaw "
+                             "service restart, then hyperclaw self-check")
+    return Result(True, "✓ Connected: background service (running, starts at login)")
+
+
+def restart(*, run: Runner = subprocess.run) -> Result:
+    kind = platform()
+    if kind == "launchd":
+        r = run(["launchctl", "kickstart", "-k", f"{_gui()}/{LABEL}"], capture_output=True,
+                text=True)
+    elif kind == "systemd":
+        r = run(["systemctl", "--user", "restart", UNIT], capture_output=True, text=True)
+    else:
+        return Result(False, "No supported service manager on this computer.")
+    return Result(r.returncode == 0, "Background service restarted." if r.returncode == 0
+                  else "The background service couldn't be restarted; run hyperclaw service "
+                       "install.")
+
+
+class paused:
+    """Stop this install's own service for a moment (Telegram pairing needs
+    the bot's updates to itself), then start it again. Only our own label."""
+
+    def __init__(self, run: Runner = subprocess.run):
+        self.run = run
+        self.was = False
+
+    def __enter__(self):
+        kind = platform()
+        if kind == "launchd" and _loaded(LABEL, self.run):
+            self.was = True
+            self.run(["launchctl", "bootout", f"{_gui()}/{LABEL}"], capture_output=True,
+                     text=True)
+        elif kind == "systemd" and status(run=self.run)["running"]:
+            self.was = True
+            self.run(["systemctl", "--user", "stop", UNIT], capture_output=True, text=True)
+        return self
+
+    def __exit__(self, *exc):
+        if self.was:
+            install(run=self.run)
+        return False
+
+
+# ── single Telegram connection ────────────────────────────────────────────
+
+class TelegramLock:
+    """An exclusive, non-blocking lock held while a process polls the bot."""
+
+    def __init__(self, path: Optional[Path] = None):
+        self.path = path or (_root() / "run" / "telegram.lock")
+        self.fd = None
+
+    def acquire(self) -> bool:
+        import fcntl
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        fd = os.open(str(self.path), os.O_RDWR | os.O_CREAT, 0o600)
+        try:
+            fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except OSError:
+            os.close(fd)
+            return False
+        os.ftruncate(fd, 0)
+        os.write(fd, str(os.getpid()).encode())
+        self.fd = fd
+        return True
+
+    def release(self) -> None:
+        if self.fd is not None:
+            import fcntl
+            try:
+                fcntl.flock(self.fd, fcntl.LOCK_UN)
+            finally:
+                os.close(self.fd)
+                self.fd = None
+
+
+ANOTHER_POLLER = ("Another HyperAgents process is already connected to this Telegram bot "
+                  "(only one may be); this one is not starting Telegram.")
+
+
+# ── housekeeping (pure parts are tested offline) ──────────────────────────
+
+class WakeWatch:
+    """Detects a sleep/wake: the wall clock moved further than the monotonic
+    clock (which stops while the computer sleeps)."""
+
+    def __init__(self, wall: Callable[[], float] = time.time,
+                 mono: Callable[[], float] = time.monotonic, jump: float = WAKE_JUMP):
+        self.wall, self.mono, self.jump = wall, mono, jump
+        self.w0, self.m0 = wall(), mono()
+
+    def woke(self) -> bool:
+        w, m = self.wall(), self.mono()
+        gap = (w - self.w0) - (m - self.m0)
+        self.w0, self.m0 = w, m
+        return gap > self.jump
+
+
+def _state_path() -> Path:
+    return _root() / "run" / "service-state.json"
+
+
+def _state() -> dict:
+    try:
+        d = json.loads(_state_path().read_text(encoding="utf-8"))
+        return d if isinstance(d, dict) else {}
+    except Exception:
+        return {}
+
+
+def _save_state(d: dict) -> None:
+    p = _state_path()
+    p.parent.mkdir(parents=True, exist_ok=True)
+    fd = os.open(str(p), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w", encoding="utf-8") as f:
+        json.dump(d, f)
+
+
+def slack_tick(send: Callable[[str], object], *, http=None,
+               now: Callable[[], float] = time.time) -> str:
+    """Refresh the Slack sign-in when due. A refusal is told to the owner
+    once (plain words), until they sign in again."""
+    from hyperclaw.teamsetup import profile, slack_oauth
+    cfg = (profile.load().get("slack") or {})
+    if not cfg.get("client_id") or not slack_oauth.connected():
+        return "skip"
+    r = slack_oauth.refresh(cfg, http=http, now=now)
+    st = _state()
+    # Tell each message once (per sign-in: a new sign-in or a new refresh
+    # token gives a new date, so a later reminder is sent again).
+    key = f"{r.status}:{slack_oauth.sign_in_by(slack_oauth.load_bundle())}:{r.message[:24]}"
+    if r.message and st.get("slack_told") != key:
+        send(r.message)
+        st["slack_told"] = key
+        _save_state(st)
+    return r.status
+
+
+def update_tick(send: Callable[[str], object]) -> str:
+    """Tell the owner once per newer signed release."""
+    from hyperclaw.updates import check
+    from hyperclaw.updates.paths import opted_out
+    if opted_out():
+        return "opted-out"
+    check.maybe_refresh_in_background()
+    latest = check.load_cache().get("latest_signed")
+    text = check.notice_text()
+    if not text or not latest:
+        return "none"
+    st = _state()
+    if st.get("update_told") == latest:
+        return "told"
+    send(text.replace("HyperClaw", "HyperAgents", 1) +
+         " (in your terminal; it installs signed releases only)")
+    st["update_told"] = latest
+    _save_state(st)
+    return "sent"
+
+
+def owner_send(text: str) -> bool:
+    """Plain Telegram message to the owner chat (previews off)."""
+    from hyperclaw.updates.notices import telegram_send
+    return telegram_send(text)
+
+
+def with_service_start(original, send, extra):
+    """The bot's own start-up hook (the approval layer), then the scheduler
+    and the housekeeping task, in the bot's event loop."""
+    import asyncio
+
+    async def post_init(application):
+        if original is not None:
+            await original(application)
+        from hyperclaw.scheduler import get_scheduler
+        get_scheduler(send).start()
+        asyncio.get_running_loop().create_task(extra(application))
+    return post_init
+
+
+# ── run ───────────────────────────────────────────────────────────────────
+
+def _setup_logging() -> None:
+    log_path().parent.mkdir(parents=True, exist_ok=True)
+    logging.basicConfig(level=logging.INFO,
+                        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+                        handlers=[logging.StreamHandler(sys.stdout)])
+    for noisy in ("httpx", "httpcore", "telegram.ext", "apscheduler"):
+        logging.getLogger(noisy).setLevel(logging.WARNING)
+
+
+def run() -> int:
+    """The service process. Returns the exit status."""
+    import asyncio
+    _setup_logging()
+    from hyperclaw.userconfig import load_env_into_process
+    load_env_into_process()
+    from hyperclaw import unattended
+    unattended.exit_if_off(log, "hyperclaw service")
+    from hyperclaw.updates import on_startup
+    on_startup("service")
+
+    lock = TelegramLock()
+    have_lock = lock.acquire()
+    token = os.environ.get("TELEGRAM_BOT_TOKEN", "").strip()
+    if token and not have_lock:
+        log.warning(ANOTHER_POLLER)
+    state = {"exit": 0}
+    wake = WakeWatch()
+
+    async def housekeeping(stop: Callable[[], None]):
+        last = 0.0
+        while True:
+            await asyncio.sleep(30)
+            if wake.woke():
+                log.warning("woke from sleep: restarting for a fresh Telegram connection")
+                state["exit"] = WAKE_EXIT
+                stop()
+                return
+            if time.monotonic() - last >= HOUSEKEEPING_EVERY or last == 0.0:
+                last = time.monotonic()
+                for tick in (slack_tick, update_tick):
+                    try:
+                        await asyncio.to_thread(tick, owner_send)
+                    except Exception as e:  # noqa: BLE001
+                        log.warning("housekeeping %s failed (%s)", tick.__name__,
+                                    type(e).__name__)
+
+    from hyperclaw.scheduler import get_scheduler
+    try:
+        if token and have_lock:
+            from hyperclaw import telegram_bot as tb
+            bot = tb.get_telegram_bot()
+            app = bot.build(token)
+            if isinstance(app, tb.JournaledApplication):
+                from hyperclaw.telegram_intake import TelegramIntake
+                app.hc_journal = TelegramIntake()
+
+            app.post_init = with_service_start(app.post_init, bot.send_message,
+                                               lambda a: housekeeping(a.stop_running))
+            log.info("HyperAgents service: Telegram + scheduler in one process")
+            app.run_polling(drop_pending_updates=False)
+        else:
+            async def scheduler_only():
+                ev = asyncio.Event()
+                sched = get_scheduler(None)
+                sched.start()
+                await housekeeping(ev.set)
+            log.info("HyperAgents service: scheduler only (no Telegram here)")
+            asyncio.run(scheduler_only())
+    finally:
+        lock.release()
+    return state["exit"]
+
+
+def main(argv=None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if argv[:1] == ["run"]:
+        return run()
+    print("usage: python -m hyperclaw.teamsetup.service run", file=sys.stderr)
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())