hyperagents 1.2.3rc5.post3__py3-none-any.whl

hyperclaw/telegram_intake.py

@@ -0,0 +1,126 @@
+"""Durable Telegram intake journal: each update is claimed once, then finished.
+
+Why: python-telegram-bot confirms an update to Telegram (by asking for the
+next offset) before our handlers finish with it. If the bot stops mid-turn
+and Telegram delivers the same update again after a restart, the journal
+already holds that update_id, so it is not run a second time. The journal
+never calls getUpdates itself (python-telegram-bot owns the offset), so
+nothing is acknowledged twice.
+
+Rules:
+- claim(update) -> True only the first time an update_id is seen AND the
+  update is newer than the journal's cutover (the moment the journal was
+  first created). Older updates are recorded as ``held_cutover`` and never
+  run: the bot cannot know what a previous, journal-less process already did.
+- finish(update_id, "processed" | "uncertain"). A row left in
+  ``processing`` after a crash stays there; it is never replayed.
+- Only routing metadata is stored (update id, kind, chat id, date, status),
+  never message text: guest chats are not written to disk.
+- The file lives under HYPERCLAW_ROOT/data (dir 0700, file 0600).
+
+Adapted from an earlier HyperClaw reference implementation; the stored
+payload, the self-managed polling offset and the unbounded growth were
+removed (see the MR's lifted-vs-stripped table).
+"""
+from __future__ import annotations
+
+import os
+import sqlite3
+import time
+from pathlib import Path
+from typing import Optional
+
+STATUSES = ("processing", "processed", "uncertain", "held_cutover")
+KEEP_DAYS = 30
+_KINDS = ("message", "edited_message", "callback_query", "channel_post",
+          "edited_channel_post", "my_chat_member", "chat_member")
+
+
+def default_path() -> Path:
+    from hyperclaw.userconfig import root
+    return root() / "data" / "telegram_intake.sqlite"
+
+
+def _kind(update: dict) -> str:
+    return next((k for k in _KINDS if k in update), "other")
+
+
+def _chat_and_date(update: dict):
+    for key in ("message", "edited_message", "channel_post", "edited_channel_post"):
+        msg = update.get(key)
+        if isinstance(msg, dict):
+            chat = (msg.get("chat") or {}).get("id")
+            date = msg.get("edit_date") if key.startswith("edited") else None
+            return chat, date or msg.get("date")
+    cq = update.get("callback_query")
+    if isinstance(cq, dict):
+        return ((cq.get("message") or {}).get("chat") or {}).get("id"), None
+    return None, None
+
+
+class TelegramIntake:
+    def __init__(self, path=None, clock=time.time):
+        self.path = Path(path) if path else default_path()
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            os.chmod(self.path.parent, 0o700)
+        except OSError:
+            pass
+        if not self.path.exists():
+            os.close(os.open(str(self.path), os.O_CREAT | os.O_WRONLY, 0o600))
+        os.chmod(self.path, 0o600)
+        self.clock = clock
+        self.db = sqlite3.connect(str(self.path), timeout=10, check_same_thread=False)
+        with self.db:
+            self.db.execute("CREATE TABLE IF NOT EXISTS metadata "
+                            "(key TEXT PRIMARY KEY, value REAL NOT NULL)")
+            self.db.execute("CREATE TABLE IF NOT EXISTS updates (id INTEGER PRIMARY KEY, "
+                            "status TEXT NOT NULL, updated REAL NOT NULL, kind TEXT NOT NULL, "
+                            "chat_id INTEGER, date REAL)")
+            self.db.execute("INSERT OR IGNORE INTO metadata VALUES ('cutover', ?)", (clock(),))
+        self.cutover = self.db.execute(
+            "SELECT value FROM metadata WHERE key = 'cutover'").fetchone()[0]
+        self.prune()
+
+    def claim(self, update: dict) -> bool:
+        """True: run the handlers for this update now. False: it was seen
+        before (or predates the cutover) and must not run again."""
+        update_id = update.get("update_id")
+        if not isinstance(update_id, int) or isinstance(update_id, bool) or update_id < 0:
+            raise ValueError("invalid Telegram update id; not run")
+        chat_id, date = _chat_and_date(update)
+        # An update with no timestamp (e.g. a button press) cannot predate the
+        # cutover in a way we can check; the update_id claim still dedupes it.
+        recent = date is None or (isinstance(date, (int, float)) and date >= int(self.cutover))
+        status = "processing" if recent else "held_cutover"
+        with self.db:
+            cur = self.db.execute("INSERT OR IGNORE INTO updates VALUES (?, ?, ?, ?, ?, ?)",
+                                  (update_id, status, self.clock(), _kind(update),
+                                   chat_id if isinstance(chat_id, int) else None,
+                                   date if isinstance(date, (int, float)) else None))
+        return cur.rowcount == 1 and recent
+
+    def finish(self, update_id: int, status: str) -> None:
+        if status not in ("processed", "uncertain"):
+            raise ValueError("invalid intake outcome")
+        with self.db:
+            self.db.execute("UPDATE updates SET status = ?, updated = ? "
+                            "WHERE id = ? AND status = 'processing'",
+                            (status, self.clock(), update_id))
+
+    def status(self, update_id: int) -> Optional[str]:
+        row = self.db.execute("SELECT status FROM updates WHERE id = ?", (update_id,)).fetchone()
+        return row[0] if row else None
+
+    def counts(self) -> dict:
+        return dict(self.db.execute("SELECT status, COUNT(*) FROM updates GROUP BY status"))
+
+    def prune(self, keep_days: int = KEEP_DAYS) -> None:
+        """Drop finished rows older than keep_days. Telegram never redelivers
+        an update that old, so its claim is no longer needed."""
+        with self.db:
+            self.db.execute("DELETE FROM updates WHERE status != 'processing' AND updated < ?",
+                            (self.clock() - keep_days * 86400,))
+
+    def close(self) -> None:
+        self.db.close()

hyperclaw/telegram_pairing.py

@@ -0,0 +1,360 @@
+"""Telegram pairing: who may talk to the bot, and who is the owner.
+
+Two flows:
+
+1. Owner auto-detect (onboarding, before the bot runs). After the owner
+   enters their bot token, onboarding shows a one-time code and asks them to
+   send it to their bot. The first direct chat that sends exactly that code
+   within 10 minutes becomes TELEGRAM_OWNER_CHAT_ID (written with
+   userconfig.env_update, file 0600). A wrong or expired code pairs nothing.
+   No lookup bot or manual chat-id step.
+
+2. Guest pairing (while the bot runs). A message from an unknown direct chat
+   is never read: the chat gets a one-time code that expires in 10 minutes,
+   and the owner chat is asked to approve it with ``/pair <code>``. An
+   approved chat is a GUEST (hyperclaw.chat_scope): pairing never grants owner
+   access, owner memory or owner tools. The pairing file is 0600.
+
+The bot token is never printed, logged or put in an error message.
+
+Adapted from an earlier HyperClaw reference implementation; codes now
+expire, the file is 0600, paired chats are guests, and only the owner chat
+can approve (see the MR's lifted-vs-stripped table).
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+import secrets
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable, Optional
+
+log = logging.getLogger("hyperclaw.telegram.pairing")
+
+CODE_TTL = 600            # seconds a pairing code stays valid (10 minutes)
+MAX_PENDING = 20          # cap on open guest requests (spam guard)
+_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789"   # no O/0, I/1
+API = "https://api.telegram.org"
+
+
+def new_code() -> str:
+    """A one-time code like 'K7QM-3XRA' (40 bits, unambiguous characters)."""
+    raw = "".join(secrets.choice(_ALPHABET) for _ in range(8))
+    return f"{raw[:4]}-{raw[4:]}"
+
+
+def code_matches(text, code: str) -> bool:
+    """Exact match only (surrounding whitespace ignored)."""
+    return isinstance(text, str) and secrets.compare_digest(text.strip().encode("utf-8"),
+                                                            code.encode("utf-8"))
+
+
+# ───────────────────────── 1. owner auto-detect ─────────────────────────
+
+@dataclass
+class OwnerPairing:
+    chat_id: Optional[int]
+    reason: str                     # "paired" | "expired" | "rejected_token" | "conflict" | "network"
+
+
+class _TokenSafeError(Exception):
+    """An error whose text never contains the token."""
+
+
+def _call(client, token: str, method: str, params: dict, timeout: float) -> dict:
+    try:
+        resp = client.post(f"{API}/bot{token}/{method}", json=params, timeout=timeout)
+    except Exception as e:  # httpx errors carry the URL (and so the token): drop the text
+        raise _TokenSafeError(f"network error ({type(e).__name__})") from None
+    try:
+        data = resp.json()
+    except Exception:
+        data = {}
+    if resp.status_code == 401 or resp.status_code == 404:
+        raise _TokenSafeError("rejected_token")
+    if resp.status_code == 409:
+        raise _TokenSafeError("conflict")
+    if not data.get("ok"):
+        raise _TokenSafeError(f"telegram error ({resp.status_code})")
+    return data
+
+
+def bot_username(token: str, client=None) -> Optional[str]:
+    """getMe -> the bot's @username, or None if Telegram rejects the token."""
+    client = client or _client()
+    try:
+        data = _call(client, token, "getMe", {}, timeout=15)
+    except _TokenSafeError:
+        return None
+    return (data.get("result") or {}).get("username") or None
+
+
+def _client():
+    import httpx
+    # httpx logs request URLs at INFO, and the URL contains the bot token.
+    logging.getLogger("httpx").setLevel(logging.WARNING)
+    return httpx.Client()
+
+
+def wait_for_owner_code(token: str, code: str, *, issued_at: Optional[float] = None,
+                        ttl: float = CODE_TTL, client=None, clock: Callable[[], float] = time.time,
+                        poll_seconds: int = 20) -> OwnerPairing:
+    """Long-poll getUpdates until a direct chat sends exactly `code`.
+
+    Only messages sent after the code was issued count; anything already
+    waiting on the bot is skipped. Returns OwnerPairing(chat_id, "paired") or
+    OwnerPairing(None, reason). Must run while the bot itself is not polling
+    (Telegram allows one getUpdates consumer per bot)."""
+    client = client or _client()
+    issued_at = clock() if issued_at is None else issued_at
+    deadline = issued_at + ttl
+    try:
+        # Skip whatever is already queued: start after the newest update.
+        first = _call(client, token, "getUpdates", {"offset": -1, "timeout": 0}, timeout=15)
+        pending = first.get("result") or []
+        offset = (pending[-1]["update_id"] + 1) if pending else None
+        while clock() < deadline:
+            wait = max(0, min(poll_seconds, int(deadline - clock())))
+            params = {"timeout": wait, "allowed_updates": ["message"]}
+            if offset is not None:
+                params["offset"] = offset
+            data = _call(client, token, "getUpdates", params, timeout=wait + 10)
+            for upd in data.get("result") or []:
+                offset = upd["update_id"] + 1
+                msg = upd.get("message") or {}
+                chat = msg.get("chat") or {}
+                if chat.get("type") != "private":
+                    continue          # the owner chat is a direct chat with the bot
+                if (msg.get("date") or 0) < int(issued_at):
+                    continue          # sent before this code existed
+                if clock() >= deadline:
+                    break
+                if code_matches(msg.get("text"), code) and isinstance(chat.get("id"), int):
+                    # Confirm the updates read so far so the bot never sees the code.
+                    _call(client, token, "getUpdates", {"offset": offset, "timeout": 0}, timeout=15)
+                    return OwnerPairing(chat["id"], "paired")
+            if wait == 0:
+                break
+    except _TokenSafeError as e:
+        reason = str(e)
+        if reason not in ("rejected_token", "conflict"):
+            reason = "network"
+        return OwnerPairing(None, reason)
+    return OwnerPairing(None, "expired")
+
+
+def save_owner_chat(chat_id: int) -> None:
+    """Persist the owner chat (0600 .env, applied to this process too).
+    TELEGRAM_CHAT_ID is kept equal so tools that send to the owner use it."""
+    from hyperclaw.userconfig import env_update
+    env_update({"TELEGRAM_OWNER_CHAT_ID": str(int(chat_id)),
+                "TELEGRAM_CHAT_ID": str(int(chat_id))})
+
+
+PAIRED_OWNER_TEXT = ("Paired. This chat is now the owner chat for your HyperAgents assistant. "
+                     "Other chats that message the bot need your approval here first, and "
+                     "they never get access to your memory, files or accounts.")
+
+
+def confirm_owner_chat(token: str, chat_id: int, client=None) -> bool:
+    client = client or _client()
+    try:
+        _call(client, token, "sendMessage",
+              {"chat_id": chat_id, "text": PAIRED_OWNER_TEXT,
+               "link_preview_options": {"is_disabled": True}}, timeout=15)
+        return True
+    except _TokenSafeError:
+        return False
+
+
+REASON_TEXT = {
+    "expired": "No chat sent the code within 10 minutes, so nothing was paired.",
+    "rejected_token": "Telegram rejected the bot token, so nothing was paired.",
+    "conflict": ("Another program is already reading this bot's messages (for example a "
+                 "running HyperAgents Telegram service). Pair while it is stopped."),
+    "network": "Couldn't reach Telegram, so nothing was paired.",
+}
+
+
+def run_owner_pairing(token: str, say: Callable[[str], None], *, client=None,
+                      clock: Callable[[], float] = time.time, ttl: float = CODE_TTL) -> Optional[int]:
+    """The whole owner step: check the token, show a code, wait, save.
+    `say` prints one line to the owner (never the token)."""
+    client = client or _client()
+    username = bot_username(token, client=client)
+    if not username:
+        say(REASON_TEXT["rejected_token"])
+        return None
+    code = new_code()
+    issued = clock()
+    say(f"Open Telegram, start a chat with @{username} and send it this code: {code}")
+    say(f"The code works once and expires in {int(ttl // 60)} minutes. Waiting...")
+    got = wait_for_owner_code(token, code, issued_at=issued, ttl=ttl, client=client, clock=clock)
+    if got.chat_id is None:
+        say(REASON_TEXT.get(got.reason, REASON_TEXT["network"]))
+        return None
+    save_owner_chat(got.chat_id)
+    confirm_owner_chat(token, got.chat_id, client=client)
+    say(f"Paired: chat {got.chat_id} is now your owner chat.")
+    return got.chat_id
+
+
+# ───────────────────────── 2. guest pairing ─────────────────────────
+
+def default_store_path() -> Path:
+    from hyperclaw.userconfig import root
+    return root() / "data" / "telegram_pairing.json"
+
+
+class PairingStore:
+    """Approved guest chats and open pairing requests, in one 0600 JSON file.
+
+    {"approved": {"<chat_id>": {"who": str, "ts": float}},
+     "pending": {"<CODE>": {"chat_id": int, "who": str, "ts": float}}}
+    """
+
+    def __init__(self, path=None, clock: Optional[Callable[[], float]] = None,
+                 ttl: float = CODE_TTL):
+        self.path = Path(path) if path else default_store_path()
+        self.clock = clock or (lambda: time.time())
+        self.ttl = ttl
+
+    def _load(self) -> dict:
+        try:
+            data = json.loads(self.path.read_text(encoding="utf-8"))
+        except Exception:
+            data = {}
+        approved = data.get("approved") if isinstance(data.get("approved"), dict) else {}
+        pending = data.get("pending") if isinstance(data.get("pending"), dict) else {}
+        return {"approved": approved, "pending": pending}
+
+    def _save(self, data: dict) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            os.chmod(self.path.parent, 0o700)
+        except OSError:
+            pass
+        tmp = self.path.with_suffix(".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:
+            json.dump(data, f, indent=2)
+        os.chmod(tmp, 0o600)
+        os.replace(tmp, self.path)
+
+    def _purge(self, data: dict) -> bool:
+        now = self.clock()
+        stale = [c for c, info in data["pending"].items()
+                 if now - float(info.get("ts", 0)) >= self.ttl]
+        for c in stale:
+            data["pending"].pop(c, None)
+        return bool(stale)
+
+    def approved_ids(self) -> set:
+        return {int(c) for c in self._load()["approved"] if str(c).lstrip("-").isdigit()}
+
+    def is_approved(self, chat_id) -> bool:
+        return chat_id is not None and int(chat_id) in self.approved_ids()
+
+    def request(self, chat_id: int, who: str = ""):
+        """(code, is_new). One live code per chat; None when the pending cap
+        is reached. An expired code is replaced by a new one."""
+        data = self._load()
+        changed = self._purge(data)
+        for code, info in data["pending"].items():
+            if info.get("chat_id") == chat_id:
+                if changed:
+                    self._save(data)
+                return code, False
+        if len(data["pending"]) >= MAX_PENDING:
+            if changed:
+                self._save(data)
+            return None, False
+        code = new_code()
+        data["pending"][code] = {"chat_id": int(chat_id), "who": str(who)[:80], "ts": self.clock()}
+        self._save(data)
+        return code, True
+
+    def approve(self, code: str) -> Optional[dict]:
+        """Approve an open, unexpired request. Returns its info, or None."""
+        data = self._load()
+        changed = self._purge(data)
+        key = (code or "").strip().upper()
+        info = data["pending"].pop(key, None)
+        if info is None:
+            if changed:
+                self._save(data)
+            return None
+        data["approved"][str(info["chat_id"])] = {"who": info.get("who", ""), "ts": self.clock()}
+        self._save(data)
+        return info
+
+    def revoke(self, chat_id) -> bool:
+        data = self._load()
+        gone = data["approved"].pop(str(int(chat_id)), None) is not None
+        if gone:
+            self._save(data)
+        return gone
+
+
+def describe_sender(user) -> str:
+    """'First @username' for the owner's approval prompt (no other profile data)."""
+    if user is None:
+        return "unknown sender"
+    get = user.get if isinstance(user, dict) else (lambda k, d=None: getattr(user, k, d))
+    name = (get("first_name") or "").strip()
+    handle = get("username")
+    return (f"{name} @{handle}" if handle else name or "unknown sender")[:80]
+
+
+# ───────────────────────── onboarding step ─────────────────────────
+# The user-facing text of the onboarding offer lives here, not in
+# cli/onboarding.py: onboarding names no integration itself (truth rule,
+# tests/unit/test_onboarding_live_state.py). The offer is made only where the
+# install profile says Telegram can run (managed config ``"telegram": true``).
+
+OFFER_QUESTION = "[cyan]Connect a Telegram bot now? (optional)[/cyan]"
+OFFER_LATER = "[dim]You can connect it later with [bold]hyperclaw telegram pair[/bold].[/dim]"
+OFFER_HOWTO = ("[white]Create a bot with Telegram's @BotFather (/newbot) and paste its "
+               "token.[/white]")
+TOKEN_PROMPT = "[cyan]Bot token (hidden; Enter to skip)[/cyan]"
+TOKEN_BAD = "[yellow]That doesn't look like a Telegram bot token, so it wasn't saved.[/yellow]"
+TOKEN_SAVED = "[green]Bot token saved to ~/.hyperclaw/.env (readable only by you).[/green]"
+_TOKEN_SHAPE = r"\d{5,}:[A-Za-z0-9_-]{30,}"
+
+
+def offer_allowed() -> bool:
+    """True when this install's profile lets Telegram run (team and client)."""
+    from hyperclaw.managed_config import telegram_allowed
+    return telegram_allowed()
+
+
+def onboarding_offer(*, say: Callable[[str], None], confirm: Callable[..., bool],
+                     prompt: Callable[..., str], line: Callable[[str], None]) -> bool:
+    """Optional onboarding step: connect a bot and pair the owner's chat by
+    code. Does nothing (and names nothing) unless ``offer_allowed()``.
+
+    The token is asked hidden and never printed. Pairing writes
+    TELEGRAM_OWNER_CHAT_ID to ~/.hyperclaw/.env (0600); no chat-id lookup."""
+    import re
+
+    from hyperclaw.userconfig import env_update
+
+    if not offer_allowed():
+        return False
+    say("")
+    if not confirm(OFFER_QUESTION, default=False):
+        say(OFFER_LATER)
+        return False
+    say(OFFER_HOWTO)
+    token = (prompt(TOKEN_PROMPT, password=True, default="", show_default=False) or "").strip()
+    if not token:
+        return False
+    if not re.fullmatch(_TOKEN_SHAPE, token):
+        say(TOKEN_BAD)
+        return False
+    env_update({"TELEGRAM_BOT_TOKEN": token})
+    say(TOKEN_SAVED)
+    return run_owner_pairing(token, line) is not None