hyperagents 1.2.3rc5.post3__py3-none-any.whl

hyperclaw/telegram_bot.py

@@ -0,0 +1,1106 @@
+"""
+HyperClaw Telegram Bot
+Routes messages to SOLOMON, maintains per-chat conversation history.
+"""
+
+import os
+import json as _json
+import logging
+from collections import defaultdict
+from pathlib import Path as _Path
+from typing import Optional
+
+import httpx
+from dotenv import load_dotenv
+from telegram import InlineKeyboardButton, InlineKeyboardMarkup, LinkPreviewOptions, Update
+from telegram.constants import ChatAction
+from telegram.error import RetryAfter, TelegramError
+from telegram.ext import (
+    Application,
+    ApplicationHandlerStop,
+    CallbackQueryHandler,
+    CommandHandler,
+    ContextTypes,
+    Defaults,
+    MessageHandler,
+    TypeHandler,
+    filters,
+)
+
+from .branding import POWERED_BY
+from .chat_scope import OWNER, owner_ids, scope_for
+from .notices import failure_notice
+from .solomon import get_solomon
+from . import taint
+from .truth_guard import (CHAT_CUTOFF_NOTICE, CHAT_ERROR_NOTICE, FABRICATION_NOTICE,
+                          detect_fabricated_tool_use, is_internal_error_chunk,
+                          redact_secrets, strip_internal_errors)
+
+from pathlib import Path
+
+HYPERCLAW_ROOT = Path(os.environ.get("HYPERCLAW_ROOT", Path.home() / ".hyperclaw"))
+# ~/.hyperclaw/.env is where onboarding saves credentials; CWD .env as fallback
+load_dotenv(HYPERCLAW_ROOT / ".env")
+load_dotenv()
+from hyperclaw.teamsetup.secrets import export_env as _export_secrets  # noqa: E402
+_export_secrets()   # team installs keep the bot token in the OS secret store
+
+logger = logging.getLogger("hyperclaw.telegram")
+
+TENANT_ID = os.environ.get("OWNER_ID", "local")
+
+# Every Telegram message from this bot goes out with link previews off.
+NO_PREVIEW = LinkPreviewOptions(is_disabled=True)
+
+
+# ── conversation history: local only ───────────────────────────────────
+# Telegram history lives in one SQLite file under HYPERCLAW_ROOT/data (dir
+# 0700, file 0600), OWNER chat only (guest chats stay in memory), secrets
+# redacted on write. There is deliberately no database path: history never
+# goes to Postgres, and never to a shared Hyper database, even when a secrets
+# mount or POSTGRES_* variables exist (HC-027).
+
+def _local_history_path() -> _Path:
+    root = _Path(os.environ.get("HYPERCLAW_ROOT", _Path.home() / ".hyperclaw"))
+    return root / "data" / "telegram_history.sqlite"
+
+
+def _local_db():
+    import sqlite3
+    path = _local_history_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        os.chmod(path.parent, 0o700)
+    except OSError:
+        pass
+    new = not path.exists()
+    if new:
+        os.close(os.open(path, os.O_CREAT | os.O_WRONLY, 0o600))
+    conn = sqlite3.connect(str(path))
+    conn.execute("CREATE TABLE IF NOT EXISTS sessions (tenant_id TEXT NOT NULL, chat_id INTEGER "
+                 "NOT NULL, messages TEXT NOT NULL, updated_at REAL NOT NULL, "
+                 "PRIMARY KEY (tenant_id, chat_id))")
+    return conn
+
+
+def _local_load(tenant_id: str, chat_id: int) -> list:
+    if not _local_history_path().exists():
+        return []
+    conn = _local_db()
+    try:
+        row = conn.execute("SELECT messages FROM sessions WHERE tenant_id=? AND chat_id=?",
+                           (tenant_id, chat_id)).fetchone()
+        return _json.loads(row[0]) if row else []
+    finally:
+        conn.close()
+
+
+def _local_save(tenant_id: str, chat_id: int, messages: list) -> None:
+    import time
+    conn = _local_db()
+    try:
+        with conn:
+            conn.execute("INSERT INTO sessions (tenant_id, chat_id, messages, updated_at) "
+                         "VALUES (?, ?, ?, ?) ON CONFLICT (tenant_id, chat_id) DO UPDATE SET "
+                         "messages=excluded.messages, updated_at=excluded.updated_at",
+                         (tenant_id, chat_id, _json.dumps(redact_secrets(messages)), time.time()))
+    finally:
+        conn.close()
+
+
+def _is_owner_chat(chat_id: int) -> bool:
+    return scope_for("telegram", chat_id) == OWNER
+
+
+def taint_session(chat_id) -> str:
+    """The conversation id the taint guard (hyperclaw.taint) keys this chat on."""
+    return f"telegram:{chat_id}"
+
+
+def _forwarded(message) -> bool:
+    """A forwarded message is someone else's words, even in the owner's chat."""
+    origin = getattr(message, "forward_origin", None)
+    return origin is not None and type(origin).__module__.startswith("telegram")
+
+
+async def _load_history(tenant_id: str, chat_id: int) -> list:
+    if not _is_owner_chat(chat_id):
+        return []
+    try:
+        import asyncio as _asyncio
+        return await _asyncio.to_thread(_local_load, tenant_id, chat_id)
+    except Exception as e:
+        logger.warning(f"[{chat_id}] local history load failed: {type(e).__name__}")
+        return []
+
+
+async def _save_history(tenant_id: str, chat_id: int, messages: list) -> None:
+    if not _is_owner_chat(chat_id):
+        return   # guest chats are never written to disk
+    try:
+        import asyncio as _asyncio
+        await _asyncio.to_thread(_local_save, tenant_id, chat_id, messages)
+    except Exception as e:
+        logger.warning(f"[{chat_id}] local history save failed: {type(e).__name__}")
+
+
+def _allowed_chat_ids() -> set:
+    """Union of TELEGRAM_ALLOWED_CHAT_IDS (comma list) and TELEGRAM_CHAT_ID
+    (single ID written by onboarding). Also reads from CSI-mounted secret file.
+    Deny-by-default when all sources are empty."""
+    ids = set()
+    for var in ("TELEGRAM_ALLOWED_CHAT_IDS", "TELEGRAM_CHAT_ID", "TELEGRAM_OWNER_CHAT_ID"):
+        for cid in os.environ.get(var, "").split(","):
+            cid = cid.strip()
+            if cid.lstrip("-").isdigit():
+                ids.add(int(cid))
+    mount = _Path(os.environ.get("SECRETS_MOUNT", "/mnt/secrets")) / "telegram"
+    if mount.exists():
+        try:
+            raw = _json.loads(mount.read_text())
+            for key in ("TELEGRAM_CHAT_ID", "ALLOWED_CHAT_IDS"):
+                for cid in str(raw.get(key, "")).split(","):
+                    cid = cid.strip()
+                    if cid.lstrip("-").isdigit():
+                        ids.add(int(cid))
+        except Exception:
+            pass
+    return ids
+
+
+# Config
+BOT_TOKEN = os.environ.get("TELEGRAM_BOT_TOKEN", "")
+ALLOWED_CHAT_IDS = _allowed_chat_ids()
+MAX_HISTORY = 20
+# Live italic preview of the model's raw reasoning: OFF by default, forced off
+# on Hyper-deployed installs; a standard-install owner may opt in with
+# TELEGRAM_SHOW_THINKING=1 (hyperclaw.reasoning_display, Vaughn P1 2026-10-07).
+def _show_thinking() -> bool:
+    from .reasoning_display import show_reasoning
+    return show_reasoning("telegram")
+
+
+# Sent instead of an empty model answer; never saved to history.
+EMPTY_REPLY_FALLBACK = failure_notice("get_answer")
+
+
+# Every message the pairing flow sends is ALSO marked previews-off per call
+# (build() also sets previews-off Defaults for every send): a preview makes
+# Telegram's servers fetch the URL, which is data leaving the machine.
+NO_PREVIEW_KW = {"link_preview_options": NO_PREVIEW}
+
+
+def _pairing_store():
+    from .telegram_pairing import PairingStore
+    return PairingStore()
+
+
+class JournaledApplication(Application):
+    """Application whose updates pass through the durable intake journal.
+
+    python-telegram-bot fetches and confirms updates itself; this only
+    claims each update before the handlers run and records the outcome, so
+    an update Telegram delivers again after a restart is never run twice and
+    nothing is acknowledged a second time (hyperclaw.telegram_intake)."""
+
+    hc_journal = None
+
+    async def process_update(self, update: object) -> None:
+        journal = self.hc_journal
+        if journal is None or not isinstance(update, Update):
+            return await super().process_update(update)
+        try:
+            claimed = journal.claim(update.to_dict())
+        except Exception as e:
+            logger.warning(f"intake journal refused update: {type(e).__name__}")
+            return
+        if not claimed:
+            logger.info(f"update {update.update_id} already handled or pre-cutover; not run again")
+            return
+        outcome = "uncertain"
+        try:
+            await super().process_update(update)
+            outcome = "processed"
+        finally:
+            try:
+                journal.finish(update.update_id, outcome)
+            except Exception as e:
+                logger.warning(f"intake journal finish failed: {type(e).__name__}")
+
+
+def _served_by() -> str:
+    try:
+        from .providers import get_served_by
+        return get_served_by()
+    except Exception:
+        return ""
+
+
+def start_greeting(name: str) -> str:
+    """The /start greeting: led by the agent's name, the command list, then
+    the product line."""
+    lead = f"Hi, I'm {name}. Good to see you!" if name else "Hi, good to see you!"
+    return (
+        f"{lead} What can I help you with today?\n\n"
+        "/status - System status\n"
+        "/clear - Clear history\n"
+        "/name - Keep or change my name\n"
+        "/persona - See or change what shapes my style\n"
+        "/model - See or switch the model (owner)\n\n"
+        f"{POWERED_BY}"
+    )
+
+
+# Bot display name (Bot API setMyName). Runs ONLY when the owner first names
+# the agent or confirms/changes the name with /name: never at startup and
+# never on upgrade. A refusal is reported once and never retried in a loop.
+RENAMED = "My Telegram display name is now {name}."
+RENAME_REFUSED = ("Telegram refused to change my display name to {name} just now, so this "
+                  "bot keeps working under its old display name. My name is still saved as "
+                  "{name}; you can try again later with /name.")
+
+
+class TelegramBot:
+    """HyperClaw Telegram bot — routes to SOLOMON."""
+
+    def __init__(self):
+        self.application: Optional[Application] = None
+        self.conversation_history: dict[int, list[dict]] = defaultdict(list)
+        self.pending_attachments: dict[int, list] = defaultdict(list)
+        self._db_loaded: set[int] = set()
+        self.solomon = get_solomon()
+        self._naming: dict = {}        # chat_id -> naming.NamingFlow (owner first run)
+        self._consent_wait: dict = {}  # chat_id -> pending persona item id
+        # Approval layer: Send / Edit / Cancel buttons for queued actions.
+        from .approval_telegram import TelegramApprovals
+        self.approvals = TelegramApprovals()
+        self._approval_task = None
+
+    def _is_allowed(self, chat_id: int) -> bool:
+        """Allowlist: configured chats, the owner chat, and guest chats the
+        owner approved with /pair (those stay GUESTS: chat_scope decides
+        owner vs guest, never the allowlist)."""
+        if chat_id in ALLOWED_CHAT_IDS or str(chat_id) in owner_ids("telegram"):
+            return True
+        try:
+            return _pairing_store().is_approved(chat_id)
+        except Exception:
+            return False
+
+    # ── pairing: unknown chats ask, the owner approves (guests only) ──────
+    PAIR_PRIVATE = ("This assistant is private, so your message was not read. "
+                    "Pairing code: {code}. Ask the owner to approve it; the code "
+                    "expires in 10 minutes.")
+
+    async def handle_gate(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+        """Runs first for every update. Allowed chats continue to the normal
+        handlers; anything else stops here, and its content is never read.
+        An unknown direct chat gets a one-time code and the owner is asked."""
+        chat = update.effective_chat
+        if chat is None or self._is_allowed(chat.id):
+            return
+        if chat.type == "private" and update.message is not None:
+            await self._request_pairing(update, context)
+        raise ApplicationHandlerStop
+
+    async def _request_pairing(self, update: Update, context) -> None:
+        from .telegram_pairing import describe_sender
+        chat_id = update.effective_chat.id
+        owners = sorted(owner_ids("telegram"))
+        if not owners:
+            logger.warning(f"[{chat_id}] unknown chat; no owner chat configured to approve it")
+            return
+        who = describe_sender(update.effective_user)
+        try:
+            code, is_new = _pairing_store().request(chat_id, who)
+        except Exception as e:
+            logger.error(f"[{chat_id}] pairing store unavailable: {type(e).__name__}")
+            return
+        if not is_new:
+            logger.info(f"[{chat_id}] unknown chat; pairing code already pending (or cap reached)")
+            return
+        logger.warning(f"[{chat_id}] unknown chat issued a pairing code")
+        try:
+            await update.message.reply_text(self.PAIR_PRIVATE.format(code=code), **NO_PREVIEW_KW)
+        except Exception:
+            pass
+        for owner in owners:
+            try:
+                await context.bot.send_message(
+                    chat_id=int(owner),
+                    text=(f"Pairing request from {who} (chat {chat_id}). It would join as a "
+                          f"guest: no access to your memory, files or accounts. Approve with "
+                          f"/pair {code} within 10 minutes, or ignore it."),
+                    **NO_PREVIEW_KW)
+            except Exception:
+                logger.warning("could not notify the owner chat of a pairing request")
+
+    async def pair_command(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+        """/pair <code> - owner chat only: approve a waiting chat as a guest."""
+        if not update.effective_chat or not self._is_allowed(update.effective_chat.id):
+            return
+        if scope_for("telegram", update.effective_chat.id) != OWNER:
+            await update.message.reply_text("Only the owner can approve pairing requests.",
+                                            **NO_PREVIEW_KW)
+            return
+        args = list(getattr(context, "args", None) or [])
+        if not args:
+            await update.message.reply_text("Usage: /pair <code>", **NO_PREVIEW_KW)
+            return
+        info = _pairing_store().approve(args[0])
+        if not info:
+            await update.message.reply_text(
+                "No waiting request has that code (it may have expired). Nothing was paired.",
+                **NO_PREVIEW_KW)
+            return
+        await update.message.reply_text(
+            f"Paired {info.get('who') or 'that chat'} (chat {info['chat_id']}) as a guest. "
+            f"/unpair {info['chat_id']} removes it.", **NO_PREVIEW_KW)
+        try:
+            await context.bot.send_message(
+                chat_id=int(info["chat_id"]),
+                text="The owner approved this chat. You can talk to me now as a guest.",
+                **NO_PREVIEW_KW)
+        except Exception:
+            pass
+
+    async def unpair_command(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+        """/unpair <chat id> - owner chat only: remove an approved guest chat."""
+        if not update.effective_chat or not self._is_allowed(update.effective_chat.id):
+            return
+        if scope_for("telegram", update.effective_chat.id) != OWNER:
+            await update.message.reply_text("Only the owner can remove paired chats.",
+                                            **NO_PREVIEW_KW)
+            return
+        args = list(getattr(context, "args", None) or [])
+        if not args or not args[0].lstrip("-").isdigit():
+            await update.message.reply_text("Usage: /unpair <chat id>", **NO_PREVIEW_KW)
+            return
+        gone = _pairing_store().revoke(int(args[0]))
+        await update.message.reply_text(
+            f"Removed chat {args[0]}." if gone else f"Chat {args[0]} was not a paired guest.",
+            **NO_PREVIEW_KW)
+
+    async def start_command(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+        """Handle /start command."""
+        if not update.effective_chat or not self._is_allowed(update.effective_chat.id):
+            return
+
+        chat_id = update.effective_chat.id
+        from . import naming
+        if scope_for("telegram", chat_id) == OWNER:
+            if not naming.is_named():
+                await update.message.reply_text(await self._start_naming(chat_id))
+                return
+        await update.message.reply_text(start_greeting(naming.current_name()))
+
+    # ── identity and persona (spec §14), owner only ─────────────────────
+    NOT_OWNER = "Only the owner of this assistant can change its name or persona."
+
+    async def _start_naming(self, chat_id: int) -> str:
+        import asyncio as _asyncio
+        from . import naming
+        call = await _asyncio.to_thread(naming.default_model_call)
+        flow = naming.NamingFlow(model_call=call)
+        self._naming[chat_id] = flow
+        return "Hi! Before we get going: " + flow.start()
+
+    async def _sync_display_name(self, bot, name: str) -> str:
+        """Set the bot's Telegram display name to the agent's name (setMyName),
+        only if it differs from the current one (getMyName). Called only when
+        the owner names the agent or confirms/changes the name via /name.
+        Returns a note for the owner ("" when nothing changed). One attempt:
+        a refusal is logged and reported, never retried."""
+        if not name or bot is None:
+            return ""
+        try:
+            current = await bot.get_my_name()
+            if (getattr(current, "name", "") or "") == name:
+                return ""
+        except Exception as e:  # can't tell: try the rename once
+            logger.info(f"getMyName failed ({type(e).__name__}); trying setMyName once")
+        try:
+            ok = await bot.set_my_name(name=name)
+        except RetryAfter:
+            logger.warning("Telegram refused setMyName (rate limited); not retrying")
+            return RENAME_REFUSED.format(name=name)
+        except TelegramError as e:
+            logger.warning(f"Telegram refused setMyName ({type(e).__name__}: {e}); not retrying")
+            return RENAME_REFUSED.format(name=name)
+        except Exception as e:
+            logger.warning(f"setMyName failed ({type(e).__name__}); not retrying")
+            return RENAME_REFUSED.format(name=name)
+        if ok is False:
+            logger.warning("Telegram refused setMyName (returned false); not retrying")
+            return RENAME_REFUSED.format(name=name)
+        return RENAMED.format(name=name)
+
+    async def _identity_preflight(self, chat_id: int, text: str, bot=None):
+        """Owner-only steps that run before a model turn: the first-run
+        naming flow and a yes/no answer to a persona consent question.
+        Returns a reply to send instead of a model turn, or None."""
+        import asyncio as _asyncio
+        from . import naming, persona
+        flow = self._naming.get(chat_id)
+        if flow is not None:
+            reply = await _asyncio.to_thread(flow.handle, text)
+            if flow.done:
+                self._naming.pop(chat_id, None)
+                self.solomon.reload_context()
+                note = await self._sync_display_name(bot, flow.name)
+                if note:
+                    reply = f"{reply}\n\n{note}"
+            return reply
+        if not naming.is_named():
+            return await self._start_naming(chat_id)
+        pid = self._consent_wait.pop(chat_id, None)
+        if pid is not None:
+            kind = persona.answer_kind(text)
+            store = persona.PersonaStore()
+            if kind == "yes":
+                item = store.accept(pid)
+                return (f"Saved: {persona.describe(item)}. /persona shows or changes it."
+                        if item else None)
+            if kind == "no":
+                item = store.decline(pid)
+                return "OK, I won't keep that." if item else None
+        return None
+
+    async def _persona_followup(self, update: Update, chat_id: int, text: str) -> None:
+        """After an owner turn: ask before keeping any inferred preference."""
+        from . import persona
+        try:
+            item = persona.observe(text)
+        except Exception:
+            item = None
+        if item:
+            self._consent_wait[chat_id] = item["id"]
+            await update.message.reply_text(persona.consent_question(item))
+
+    NAME_KEEP, NAME_NEW = "name:keep", "name:new"
+
+    async def name_command(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+        """/name (Keep / Choose new), /name <new name>, /name suggest — owner only."""
+        if not update.effective_chat or not self._is_allowed(update.effective_chat.id):
+            return
+        chat_id = update.effective_chat.id
+        if scope_for("telegram", chat_id) != OWNER:
+            await update.message.reply_text(self.NOT_OWNER)
+            return
+        import asyncio as _asyncio
+        from . import naming
+        args = list(getattr(context, "args", None) or [])
+        if not args:
+            cur = naming.current_name()
+            if not cur:
+                await update.message.reply_text(await self._new_naming_flow(chat_id))
+                return
+            buttons = InlineKeyboardMarkup([[
+                InlineKeyboardButton("Keep", callback_data=self.NAME_KEEP),
+                InlineKeyboardButton("Choose new", callback_data=self.NAME_NEW),
+            ]])
+            await update.message.reply_text(naming.KEEP_OR_NEW.format(name=cur),
+                                            reply_markup=buttons)
+            return
+        call = (await _asyncio.to_thread(naming.default_model_call)
+                if args[0].lower() == "suggest" else None)
+        reply = await _asyncio.to_thread(naming.run_command, args, call)
+        self._naming.pop(chat_id, None)
+        self.solomon.reload_context()
+        if args[0].lower() not in ("suggest", "show"):
+            new = naming.current_name()
+            if new and reply == naming.CONFIRMED.format(name=new):
+                note = await self._sync_display_name(getattr(context, "bot", None), new)
+                if note:
+                    reply = f"{reply}\n\n{note}"
+        await update.message.reply_text(reply)
+
+    async def _new_naming_flow(self, chat_id: int) -> str:
+        """Start the normal naming flow (no "before we get going" lead-in)."""
+        import asyncio as _asyncio
+        from . import naming
+        call = await _asyncio.to_thread(naming.default_model_call)
+        flow = naming.NamingFlow(model_call=call)
+        self._naming[chat_id] = flow
+        return flow.start()
+
+    async def handle_name_choice(self, update: Update,
+                                   context: ContextTypes.DEFAULT_TYPE) -> None:
+        """The Keep / Choose new buttons under /name — owner only."""
+        query = getattr(update, "callback_query", None)
+        if query is None:
+            return
+        try:
+            await query.answer()
+        except Exception:
+            pass
+        chat = update.effective_chat
+        if not chat or not self._is_allowed(chat.id):
+            return
+        chat_id = chat.id
+        if scope_for("telegram", chat_id) != OWNER:
+            await query.message.reply_text(self.NOT_OWNER)
+            return
+        try:  # the question is answered: take the buttons away
+            await query.edit_message_reply_markup(reply_markup=None)
+        except Exception:
+            pass
+        from . import naming
+        cur = naming.current_name()
+        if query.data == self.NAME_KEEP and cur:
+            self._naming.pop(chat_id, None)
+            reply = naming.KEPT.format(name=cur)
+            note = await self._sync_display_name(getattr(context, "bot", None), cur)
+            if note:
+                reply = f"{reply}\n\n{note}"
+        elif query.data in (self.NAME_KEEP, self.NAME_NEW):
+            reply = await self._new_naming_flow(chat_id)
+        else:
+            return
+        await query.message.reply_text(reply)
+
+    async def persona_command(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+        """/persona [show|set|unset|pending|accept|decline|reset] — owner only."""
+        if not update.effective_chat or not self._is_allowed(update.effective_chat.id):
+            return
+        chat_id = update.effective_chat.id
+        if scope_for("telegram", chat_id) != OWNER:
+            await update.message.reply_text(self.NOT_OWNER)
+            return
+        from . import persona
+        self._consent_wait.pop(chat_id, None)
+        await update.message.reply_text(
+            persona.run_command(list(getattr(context, "args", None) or [])))
+
+    NOT_OWNER_MODEL = "Only the owner of this assistant can see or change its model."
+
+    async def model_command(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+        """/model [next|default|<number|id>] — owner only (docs/MODEL-SWITCHING.md).
+        History is kept; each turn rebuilds the prompt (truth rules first) and
+        thinking parameters for the serving model; replies stay text only."""
+        if not update.effective_chat or not self._is_allowed(update.effective_chat.id):
+            return
+        chat_id = update.effective_chat.id
+        if scope_for("telegram", chat_id) != OWNER:
+            await update.message.reply_text(self.NOT_OWNER_MODEL)
+            return
+        import asyncio as _asyncio
+        from . import model_catalog as mc
+        from .providers import registry
+        reg = registry()
+        cands = mc.prefer_selected(reg, mc.TELEGRAM, reg.resolve("primary", {"chat", "streaming"}),
+                                   {"chat", "streaming"})
+        old_key = f"{cands[0][0].name}/{cands[0][1]}" if cands else ""
+        args = list(getattr(context, "args", None) or [])
+        res = await _asyncio.to_thread(mc.run_command, args, mc.TELEGRAM, old_key, reg)
+        if res.switched or res.cleared:
+            new = mc.prefer_selected(reg, mc.TELEGRAM,
+                                     reg.resolve("primary", {"chat", "streaming"}),
+                                     {"chat", "streaming"})
+            new_key = f"{new[0][0].name}/{new[0][1]}" if new else ""
+            mc.record_switch(mc.TELEGRAM, old_key, new_key, "chat_only",
+                             len(self.conversation_history.get(chat_id, [])))
+        await update.message.reply_text(res.text)
+
+    async def status_command(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+        """Handle /status command — show system status."""
+        if not update.effective_chat or not self._is_allowed(update.effective_chat.id):
+            return
+
+        chat_id = update.effective_chat.id
+        history_count = len(self.conversation_history.get(chat_id, []))
+
+        # Try to get ATLAS_TRADING status
+        trading_status = "offline"
+        try:
+            async with httpx.AsyncClient(timeout=2.0) as client:
+                resp = await client.get("http://localhost:5001/status")
+                if resp.status_code == 200:
+                    data = resp.json()
+                    trading_status = data.get("status", "unknown")
+        except Exception:
+            trading_status = "unreachable"
+
+        # Get system uptime
+        try:
+            import subprocess
+            result = subprocess.run(["uptime"], capture_output=True, text=True, timeout=5)
+            uptime_line = result.stdout.strip()
+        except Exception:
+            uptime_line = "unknown"
+
+        # Memory stats
+        try:
+            import psutil
+            mem = psutil.virtual_memory()
+            mem_stats = f"{mem.percent}% used ({mem.used // (1024**3)}GB / {mem.total // (1024**3)}GB)"
+        except Exception:
+            mem_stats = "unavailable"
+
+        status_text = (
+            f"⚡ **Status**\n"
+            f"Agent: online\n"
+            f"ATLAS_TRADING: {trading_status}\n"
+            f"Uptime: {uptime_line}\n"
+            f"Memory: {mem_stats}\n"
+            f"History: {history_count} messages"
+        )
+        await update.message.reply_text(status_text, parse_mode="Markdown")
+
+    NOT_OWNER_TEAM = "Only the owner of this assistant can see or change its team."
+
+    async def team_command(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+        """/team [stop|pause|resume|on|off|rename|proposals] — owner only.
+        Short status lines: who's doing what and today's spend."""
+        if not update.effective_chat or not self._is_allowed(update.effective_chat.id):
+            return
+        if scope_for("telegram", update.effective_chat.id) != OWNER:
+            await update.message.reply_text(self.NOT_OWNER_TEAM)
+            return
+        import asyncio as _asyncio
+        from hyperclaw.team import status as team_status
+        arg = " ".join(list(getattr(context, "args", None) or []))
+        text = await _asyncio.to_thread(team_status.command, arg, short=True)
+        await update.message.reply_text(text, link_preview_options=NO_PREVIEW)
+
+    async def clear_command(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+        """Handle /clear command — clear conversation history."""
+        if not update.effective_chat or not self._is_allowed(update.effective_chat.id):
+            return
+
+        chat_id = update.effective_chat.id
+        self.conversation_history[chat_id] = []
+        self._db_loaded.discard(chat_id)
+        taint.clear(taint_session(chat_id))   # the history (and its connector content) is gone
+        await _save_history(TENANT_ID, chat_id, [])
+        await update.message.reply_text("Conversation history cleared.")
+
+    MAX_FILE_BYTES = 20 * 1024 * 1024  # Telegram bot API download cap
+
+    async def handle_file(self, update, context) -> None:
+        """Receive a document or photo and stage it for the next model turn.
+
+        hyperclaw.attachments decides how it reaches the model: native
+        document/image blocks only when a live provider reads them; else
+        PDFs are extracted to text locally and text files are inlined, all
+        framed as data (never instructions). A photo on a text-only model is
+        answered honestly here and never sent to the model."""
+        chat_id = update.effective_chat.id
+        if not self._is_allowed(chat_id):
+            return
+        from .attachments import intake
+
+        msg = update.message
+        try:
+            with taint.conversation(taint_session(chat_id)):
+                if msg.photo:
+                    tg_file = await msg.photo[-1].get_file()
+                    raw = bytes(await tg_file.download_as_bytearray())
+                    got = intake(raw, photo=True)
+                else:
+                    doc = msg.document
+                    if doc.file_size and doc.file_size > self.MAX_FILE_BYTES:
+                        await msg.reply_text(f"That file is too large for me to pull down "
+                                             f"({doc.file_size // (1024*1024)} MB - limit 20 MB).")
+                        return
+                    tg_file = await doc.get_file()
+                    raw = bytes(await tg_file.download_as_bytearray())
+                    got = intake(raw, name=doc.file_name or "file", mime=doc.mime_type or "")
+        except Exception as e:
+            logger.error(f"[{chat_id}] file intake failed: {type(e).__name__}", exc_info=True)
+            await msg.reply_text(failure_notice("read_file", detail="Please try sending it again.", retry=False))
+            return
+
+        if got.reply:
+            # e.g. a photo with no image-capable model: answer honestly, stage
+            # nothing, call no model (no invented description).
+            logger.info(f"[{chat_id}] attachment not sent to a model: {got.label}")
+            await msg.reply_text(got.reply, **NO_PREVIEW_KW)
+            return
+        self.pending_attachments[chat_id].extend(got.blocks)
+        logger.info(f"[{chat_id}] staged attachment: {got.label}")
+
+        caption = (msg.caption or "").strip()
+        if caption:
+            # A caption is a question about the file - answer it immediately.
+            # PTB Message objects are frozen; bypass to inject the caption as text.
+            object.__setattr__(update.message, "text", caption)
+            await self.handle_message(update, context)
+        else:
+            ack = f"Got it - {got.label} received."
+            if got.note:
+                ack += f" Heads-up: {got.note}"
+            await msg.reply_text(ack + " Ask me anything about it.")
+
+    async def _finalize_markdown(self, placeholder, text: str) -> None:
+        """Re-render the finished answer with Markdown; keep the plain-text
+        version if Telegram rejects the entities (unbalanced markers)."""
+        try:
+            await placeholder.edit_text(text, parse_mode="Markdown")
+        except Exception:
+            pass
+
+    async def handle_message(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+        """Handle incoming text messages — stream response from SOLOMON."""
+        if not update.effective_chat or not self._is_allowed(update.effective_chat.id):
+            logger.warning(f"Blocked message from unauthorized chat: {update.effective_chat.id}")
+            return
+
+        if not update.message or not update.message.text:
+            return
+
+        chat_id = update.effective_chat.id
+        user_message = update.message.text.strip()
+
+        if not user_message:
+            return
+
+        logger.info(f"[{chat_id}] User: {user_message[:50]}...")
+
+        # Owner-only identity steps (naming first run, persona consent answers)
+        is_owner = scope_for("telegram", chat_id) == OWNER
+        if not is_owner or _forwarded(update.message):
+            # Someone else's words (a guest chat, or a forward): connector
+            # content for the taint guard, never memory or training data.
+            user_message = taint.mark(user_message, "telegram", "telegram",
+                                      session=taint_session(chat_id))
+        if is_owner and await self.approvals.on_owner_text(update, context):
+            return  # the owner's new content after pressing Edit on an approval
+        if is_owner:
+            pre = await self._identity_preflight(chat_id, user_message,
+                                                 bot=getattr(context, "bot", None))
+            if pre is not None:
+                await update.message.reply_text(pre)
+                return
+
+        # Lazy-load history from DB on first message this session
+        if chat_id not in self._db_loaded:
+            db_history = await _load_history(TENANT_ID, chat_id)
+            if db_history:
+                self.conversation_history[chat_id] = db_history
+            self._db_loaded.add(chat_id)
+
+        history = self.conversation_history[chat_id]
+
+        # Telegram expires the typing indicator after ~5s — keep it alive for
+        # the whole turn so the user always sees the bot working.
+        import asyncio as _asyncio
+
+        typing_alive = True
+
+        # First indicator immediately — the refresh task only keeps it alive.
+        try:
+            await context.bot.send_chat_action(chat_id=chat_id, action=ChatAction.TYPING)
+        except Exception:
+            pass
+
+        async def _keep_typing():
+            while typing_alive:
+                await _asyncio.sleep(4)
+                if not typing_alive:
+                    break
+                try:
+                    await context.bot.send_chat_action(chat_id=chat_id, action=ChatAction.TYPING)
+                except Exception:
+                    pass
+
+        typing_task = _asyncio.create_task(_keep_typing())
+
+        try:
+            # Placeholder — the user sees activity from the first moment
+            placeholder = await update.message.reply_text("💭 thinking…")
+
+            buffer = ""
+            last_edit = ""
+            full_response = []
+            thinking_buf = []
+            answer_started = False
+            EDIT_THRESHOLD = 60   # chars accumulated before pushing an edit
+            edit_count = 0
+            MAX_EDITS = 60        # stay well under Telegram rate limits (~20 edits/msg practical limit)
+
+            provider_error = False
+            attachments = self.pending_attachments.pop(chat_id, [])
+            show_thinking = _show_thinking()
+            # Guest fence (spec §6): only the configured owner chat gets owner
+            # memory/persona; every other paired chat is a guest. Unknown
+            # owner -> guest (fail closed).
+            scope = scope_for("telegram", chat_id)
+            async for kind, chunk in self.solomon.stream_events(
+                    user_message, history, attachments=attachments, scope=scope):
+                if kind == "notice":
+                    # Automatic fallback: one line naming the model now
+                    # answering and why (model_policy). Never saved as the answer.
+                    try:
+                        await update.message.reply_text(chunk)
+                    except Exception:
+                        logger.warning(f"[{chat_id}] fallback notice not delivered")
+                    continue
+                if kind == "thinking":
+                    if not show_thinking or answer_started:
+                        continue
+                    thinking_buf.append(chunk)
+                    buffer += chunk
+                    # Update the italic thinking preview at the same cadence
+                    if len(buffer) >= EDIT_THRESHOLD and edit_count < MAX_EDITS:
+                        preview = "".join(thinking_buf)[-800:]
+                        text = f"💭 _{preview}_"
+                        if text != last_edit:
+                            try:
+                                await placeholder.edit_text(text, parse_mode="Markdown")
+                                last_edit = text
+                                edit_count += 1
+                                buffer = ""
+                            except Exception:
+                                pass
+                    continue
+
+                # kind == "text" — the answer itself
+                if is_internal_error_chunk(chunk):
+                    # Provider failure text: log it, never show it in the chat.
+                    logger.error(f"[{chat_id}] provider error during reply: {chunk.strip()[:300]}")
+                    provider_error = True
+                    continue
+                if not answer_started:
+                    answer_started = True
+                    buffer = ""
+                buffer += chunk
+                full_response.append(chunk)
+
+                # Push update when buffer is large enough or chunk ends a sentence
+                should_update = (
+                    len(buffer) >= EDIT_THRESHOLD
+                    or (len(buffer) >= 20 and chunk.endswith((".", "!", "?", "\n")))
+                )
+
+                if should_update and edit_count < MAX_EDITS:
+                    current_text = "".join(full_response)
+                    if current_text != last_edit and len(current_text) <= 4096:
+                        try:
+                            await placeholder.edit_text(current_text)
+                            last_edit = current_text
+                            edit_count += 1
+                            buffer = ""
+                        except Exception:
+                            pass  # rate limit or no-change — keep accumulating
+
+            # Final edit with complete response
+            response, stripped = strip_internal_errors("".join(full_response))
+            provider_error = provider_error or stripped
+            if not response and provider_error:
+                try:
+                    await placeholder.edit_text(CHAT_ERROR_NOTICE)
+                except Exception:
+                    await update.message.reply_text(CHAT_ERROR_NOTICE)
+                return
+            if provider_error:
+                # Partial answer, then the stream died: say so honestly.
+                response = f"{response}\n\n{CHAT_CUTOFF_NOTICE}"
+            if not response:
+                # Never send or save an empty reply (2026-10-07 V2 live test).
+                logger.warning(f"[{chat_id}] model returned no answer text "
+                               f"(served by {_served_by() or 'unknown'}); sent fallback")
+                try:
+                    await placeholder.edit_text(EMPTY_REPLY_FALLBACK)
+                except Exception:
+                    await update.message.reply_text(EMPTY_REPLY_FALLBACK)
+                if is_owner:
+                    await self._persona_followup(update, chat_id, user_message)
+                return
+            # This path has no tools — any described action did not happen
+            fabricated = detect_fabricated_tool_use(response, set(), tools_ran=False)
+
+            if len(response) <= 4096:
+                # Push the complete text, then re-render with Markdown so
+                # **bold** and lists display properly instead of raw markers.
+                if response != last_edit:
+                    try:
+                        await placeholder.edit_text(response)
+                    except Exception:
+                        pass
+                await self._finalize_markdown(placeholder, response)
+            else:
+                # Response too long — delete placeholder, send in chunks
+                try:
+                    await placeholder.delete()
+                except Exception:
+                    pass
+                for i in range(0, len(response), 4096):
+                    await update.message.reply_text(response[i:i + 4096])
+
+            if fabricated:
+                logger.warning(f"[{chat_id}] fabricated action flagged: {fabricated}")
+                await update.message.reply_text(FABRICATION_NOTICE)
+                response += ("\n\n[HyperClaw system note: no tool executed during this "
+                             "reply; the actions described above did not happen.]")
+
+            # Update history (secrets never persist)
+            history.append({"role": "user", "content": redact_secrets(user_message)})
+            history.append({"role": "assistant", "content": redact_secrets(response)})
+
+            # Trim to max history
+            if len(history) > MAX_HISTORY * 2:
+                self.conversation_history[chat_id] = history[-(MAX_HISTORY * 2):]
+
+            await _save_history(TENANT_ID, chat_id, self.conversation_history[chat_id])
+            # One line, secrets redacted (the answer's first chars, repr-quoted).
+            logger.info(f"[{chat_id}] SOLOMON streamed {len(response)} chars: "
+                        f"{redact_secrets(response[:50])!r}")
+            if is_owner:
+                await self._persona_followup(update, chat_id, user_message)
+
+        except Exception as e:
+            # Internal error text is logged, never sent to the chat.
+            logger.error(f"[{chat_id}] Error: {e}", exc_info=True)
+            try:
+                await update.message.reply_text(CHAT_ERROR_NOTICE)
+            except Exception:
+                logger.error(f"[{chat_id}] could not send the failure notice (reply not delivered)", exc_info=True)
+        finally:
+            typing_alive = False
+            typing_task.cancel()
+
+    async def send_message(self, chat_id: int, text: str) -> bool:
+        """Send a message to a specific chat (for scheduler alerts)."""
+        if not self.application:
+            logger.error("Application not initialized")
+            return False
+
+        try:
+            # Handle Telegram's 4096 char limit
+            if len(text) <= 4096:
+                await self.application.bot.send_message(chat_id=chat_id, text=text,
+                                                        link_preview_options=NO_PREVIEW)
+            else:
+                for i in range(0, len(text), 4096):
+                    await self.application.bot.send_message(chat_id=chat_id, text=text[i:i + 4096],
+                                                            link_preview_options=NO_PREVIEW)
+            return True
+        except Exception as e:
+            logger.error(f"Failed to send message to {chat_id}: {e}")
+            return False
+
+    async def _post_init(self, application: Application) -> None:
+        """Approval layer: an action interrupted mid-run is marked uncertain
+        (never re-run); queued cards from any surface reach the owner chat."""
+        import asyncio as _asyncio
+        from .approval_telegram import pending_loop
+        from .tools.approval import get_queue
+        try:
+            interrupted = get_queue().recover_interrupted()
+            if interrupted:
+                logger.warning(f"{len(interrupted)} approved action(s) were interrupted while "
+                               f"running; marked uncertain, not re-run")
+        except Exception:
+            logger.warning("approval queue unavailable at startup", exc_info=True)
+        self._approval_task = _asyncio.get_running_loop().create_task(
+            pending_loop(application.bot))
+
+    def build(self, token: str = "", journal=None) -> Application:
+        """Build and return the Telegram application. `journal`: a
+        telegram_intake.TelegramIntake that every update passes through."""
+        # Link previews off for EVERY message this bot sends or edits (a
+        # preview fetch is an outbound request to whatever URL is in the text).
+        self.application = (Application.builder().token(token or BOT_TOKEN)
+                            .application_class(JournaledApplication)
+                            .defaults(Defaults(link_preview_options=NO_PREVIEW))
+                            .post_init(self._post_init).build())
+        self.application.hc_journal = journal
+        self.application.add_handler(CallbackQueryHandler(self.approvals.on_callback,
+                                                          pattern=r"^ap:"))
+
+        # Unknown chats stop here (pairing request), before any other handler.
+        self.application.add_handler(TypeHandler(Update, self.handle_gate), group=-1)
+        # Register handlers
+        self.application.add_handler(CommandHandler("pair", self.pair_command))
+        self.application.add_handler(CommandHandler("unpair", self.unpair_command))
+        self.application.add_handler(CommandHandler("start", self.start_command))
+        self.application.add_handler(CommandHandler("status", self.status_command))
+        self.application.add_handler(CommandHandler("clear", self.clear_command))
+        self.application.add_handler(CommandHandler("name", self.name_command))
+        self.application.add_handler(CommandHandler("persona", self.persona_command))
+        self.application.add_handler(CommandHandler("model", self.model_command))
+        self.application.add_handler(CommandHandler("team", self.team_command))
+        self.application.add_handler(
+            CallbackQueryHandler(self.handle_name_choice, pattern=r"^name:(keep|new)$"))
+        self.application.add_handler(
+            MessageHandler(filters.TEXT & ~filters.COMMAND, self.handle_message)
+        )
+        self.application.add_handler(
+            MessageHandler(filters.Document.ALL | filters.PHOTO, self.handle_file)
+        )
+
+        return self.application
+
+
+# Singleton instance
+_bot: Optional[TelegramBot] = None
+
+
+def get_telegram_bot() -> TelegramBot:
+    """Get or create the Telegram bot singleton."""
+    global _bot
+    if _bot is None:
+        _bot = TelegramBot()
+    return _bot
+
+
+def main() -> None:
+    """Run the HyperClaw Telegram bot (entry point: hyperclaw-telegram)."""
+    logging.basicConfig(level=logging.INFO,
+                        format="%(asctime)s %(name)s %(levelname)s %(message)s")
+    for noisy in ("httpx", "httpcore", "telegram.ext"):
+        logging.getLogger(noisy).setLevel(logging.WARNING)
+
+    # Telegram polling is unattended work: HYPERCLAW_UNATTENDED=1 only.
+    # Off -> one log line and exit 0 (launchd KeepAlive SuccessfulExit=false
+    # does not restart a clean exit).
+    from hyperclaw import unattended
+    unattended.exit_if_off(logger, "hyperclaw-telegram")
+    from hyperclaw.updates import on_startup
+    on_startup("telegram")
+
+    # One Telegram connection per bot: the team service holds the same lock.
+    from hyperclaw.teamsetup.service import ANOTHER_POLLER, TelegramLock
+    _lock = TelegramLock()
+    if not _lock.acquire():
+        logger.warning(ANOTHER_POLLER)
+        raise SystemExit(0)
+
+    if not BOT_TOKEN:
+        raise SystemExit("TELEGRAM_BOT_TOKEN is not set. Add it to ~/.hyperclaw/.env "
+                         "(get a token from @BotFather with /newbot).")
+    if not ALLOWED_CHAT_IDS:
+        raise SystemExit("No owner chat is paired yet. Run `hyperclaw telegram pair` and send "
+                         "your bot the code it shows (or set TELEGRAM_ALLOWED_CHAT_IDS in "
+                         "~/.hyperclaw/.env) - the bot denies all messages otherwise.")
+
+    # Drain any stale getUpdates connection before starting the polling loop.
+    # Without this, Telegram returns a Conflict error when a previous process
+    # didn't shut down cleanly (the long-poll stays open on Telegram's side for ~30s).
+    async def _drain():
+        import asyncio as _asyncio
+        from telegram import Bot
+        async with Bot(token=BOT_TOKEN) as _bot:
+            await _bot.get_updates(offset=-1, timeout=0)
+    import asyncio as _asyncio
+    _asyncio.run(_drain())
+
+    bot = get_telegram_bot()
+    app = bot.build()
+    if isinstance(app, JournaledApplication):
+        # Durable intake journal (HYPERCLAW_ROOT/data, 0600): no update runs twice.
+        from .telegram_intake import TelegramIntake
+        app.hc_journal = TelegramIntake()
+    from hyperclaw.providers import registry
+    logger.info(registry().startup_line())
+    if not owner_ids("telegram"):
+        logger.warning("No owner chat configured (TELEGRAM_OWNER_CHAT_ID / TELEGRAM_CHAT_ID): "
+                       "every paired chat is treated as a GUEST and gets no owner memory.")
+    logger.info(f"HyperClaw Telegram bot starting — {len(ALLOWED_CHAT_IDS)} allowed chat(s), "
+                f"reasoning preview {'on (owner opt-in)' if _show_thinking() else 'off'}")
+    app.run_polling(drop_pending_updates=False)
+
+
+if __name__ == "__main__":
+    main()