tgcaptcha-solver 0.1.0__py3-none-any.whl

tgcaptcha/adapters/tdlib.py

@@ -0,0 +1,684 @@
+"""
+The TDLib adapter (the `aiotdlib` package): turn an aiotdlib Client into
+Hands + a message feed, and let the shared Runner (`tgcaptcha.runner`)
+own the loop. Semantics mirror `TelethonHands` / `PyrogramHands` one for
+one.
+
+    from aiotdlib import Client
+    brain = Brain("http://solver:8090", token=...)     # or Brain() = local
+    handle = mount(Client(api_id=..., api_hash=...), brain=brain)
+    ...
+    handle.stop()
+
+`mount` is the 3-line UX (detect challenges, run sessions, serialize per
+chat); `TDLibHands` and `to_message` are for hosts that drive the Runner
+themselves.
+
+Install burden: aiotdlib's wheels bundle libtdjson on Linux and macOS
+arm64, so `pip install tgcaptcha[tdlib]` just works there. Everywhere
+else (other BSDs, macOS x86_64, exotic archs) TDLib must be compiled by
+hand and pointed at through aiotdlib's `library_path` setting — budget
+an hour and a big compiler before the first run.
+
+Upstream caveat: aiotdlib is a thin asyncio skin over TDLib's generated
+JSON API and follows TDLib's rename-happy release cadence — this adapter
+was verified against 0.27.6, where message edits arrive as TWO update
+kinds (`updateMessageEdited` and `updateMessageContent`). A future
+rename surfaces here as one RPC raising inside a session (clean
+failure, recorded by the Runner), never as silently wrong behavior.
+
+This module never imports aiotdlib at import time — `to_message` and
+`TDLibHands` are pure getattr code over whatever objects they are
+handed (that is also what the offline tests exercise), and the few
+aiotdlib types that must be CONSTRUCTED (the callback payload, the
+error class) are imported lazily inside the methods that need them.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import re
+import uuid
+from typing import Any, Awaitable, Callable, Dict, Optional
+
+from tgcaptcha import text as T
+from tgcaptcha.client import Brain
+from tgcaptcha.hands import PartialHands
+from tgcaptcha.model import (Account, Button, Click, Message, SendSticker,
+                             SendText, Session)
+from tgcaptcha.policy import PolicyConfig
+from tgcaptcha.runner import InboxItem, Runner
+
+log = logging.getLogger("tgcaptcha.adapters.tdlib")
+
+DelayFn = Callable[[str], float]
+
+
+def _api_of(client):
+    """aiotdlib splits its surface in two: the ergonomic helpers
+    (`send_text`, `send_sticker`, `get_user`, ...) live on the Client,
+    the raw TDLib wrappers (`get_message`, `get_callback_query_answer`,
+    `set_bio`, ...) on `client.api`. Hands and the mount call through
+    this resolver so a fake in the offline tests can simply implement
+    everything flat on one object."""
+    return getattr(client, "api", None) or client
+
+
+def _first_username(user) -> Optional[str]:
+    """TDLib `User` has NO `.username` field — usernames moved into
+    `usernames.active_usernames` (Optional; a user may have none, and
+    the first active one is what every other framework calls "the"
+    username)."""
+    active = getattr(getattr(user, "usernames", None), "active_usernames", None)
+    return active[0] if active else None
+
+
+def _utf16_slice(text: str, offset, length) -> str:
+    """Slice `text` by a TDLib entity window. Entity offsets/lengths
+    count UTF-16 code units, not Python characters — slicing the str
+    directly lands in the middle of an emoji-prefixed challenge and
+    reads the wrong segment."""
+    if offset is None or length is None:
+        return ""
+    try:
+        return text.encode("utf-16-le")[offset * 2:(offset + length) * 2] \
+                   .decode("utf-16-le")
+    except Exception:
+        return ""
+
+
+def to_message(tdmsg, *, where: str = "group", sender=None) -> Message:
+    """An aiotdlib/TDLib message as the wire model sees it. No RPC.
+
+    `sender` may hand in the TDLib `User` the feed already fetched:
+    TDLib messages carry only a `sender_id` UNION (never a username),
+    so the username — when one is needed — is read off that User via
+    `_first_username`. Everything is read through getattr, so a message
+    missing a field degrades, not crashes."""
+    rows = []
+    markup = getattr(tdmsg, "reply_markup", None)
+    for row in (getattr(markup, "rows", None) or []):
+        out = []
+        for b in row:
+            btype = getattr(b, "type_", None) or getattr(b, "type", None)
+            data = getattr(btype, "data", None)      # callback payload
+            url = getattr(btype, "url", None)        # url target
+            kind = "callback" if data is not None else ("url" if url else "other")
+            out.append(Button(text=getattr(b, "text", "") or "", kind=kind,
+                              url=(url or None) and str(url)[:300]))
+        rows.append(out)
+    content = getattr(tdmsg, "content", None)
+    body = getattr(content, "text", None) or getattr(content, "caption", None)
+    date = getattr(tdmsg, "date", None)
+    if isinstance(date, (int, float)):
+        wire_date = float(date) if date else None    # TDLib dates are Int32
+    else:
+        wire_date = date.timestamp() if hasattr(date, "timestamp") else None
+    return Message(
+        msg_id=getattr(tdmsg, "id", None),
+        text=getattr(body, "text", None) or "",
+        buttons=rows,
+        where=where,
+        sender_id=getattr(getattr(tdmsg, "sender_id", None), "user_id", None),
+        sender_username=_first_username(sender) if sender is not None else None,
+        from_me=bool(getattr(tdmsg, "is_outgoing", False)),
+        edited=bool(getattr(tdmsg, "edit_date", 0)),   # Int32: 0 = never
+        has_photo=bool(getattr(content, "photo", None)),
+        date=wire_date,
+    )
+
+
+def _addressed(tdmsg, plain_text: str):
+    """Who the challenge names, TDLib edition: `T.addressed` over the
+    plain text PLUS its entities. TDLib keeps mentions OUT of the text
+    (a user mention renders as the display name, its id lives on a
+    `textEntityTypeMentionName` entity; an @name is a `...Mention`
+    entity), so the text alone would find nothing and every session
+    would start with names_account=False — which the policy then
+    refuses. Returns `(ids, names)` exactly like `T.addressed`."""
+    ids, names = T.addressed(plain_text)
+    body = getattr(getattr(tdmsg, "content", None), "text", None)
+    for ent in (getattr(body, "entities", None) or []):
+        etype = getattr(ent, "type_", None) or getattr(ent, "type", None)
+        uid = getattr(etype, "user_id", None)          # mentionName entity
+        if uid is not None:
+            ids.add(uid)
+        elif getattr(etype, "ID", "") == "textEntityTypeMention":
+            seg = _utf16_slice(plain_text, getattr(ent, "offset", None),
+                               getattr(ent, "length", None))
+            if seg.startswith("@"):
+                names.add(seg[1:].lower())
+    return ids, names
+
+
+def _td_error():
+    """aiotdlib's AioTDLibError (attributes `.code` / `.message`),
+    imported lazily so this module imports without aiotdlib installed —
+    the offline tests hand in a stub package through sys.modules."""
+    from aiotdlib.api.errors.error import AioTDLibError
+    return AioTDLibError
+
+
+def _callback_payload(data):
+    """CallbackQueryPayloadData(data=...) — the one TDLib object
+    `click` must construct. Lazy import for the same reason as
+    `_td_error`."""
+    from aiotdlib.api.types.all import CallbackQueryPayloadData
+    return CallbackQueryPayloadData(data=data)
+
+
+class TDLibHands(PartialHands):
+    """The Hands protocol over an aiotdlib Client. Constructed by
+    `mount`; usable directly by hosts that drive the Runner
+    themselves."""
+
+    def __init__(self, client, *, label: str = "?",
+                 join_fn: Optional[Callable[[str], Awaitable[bool]]] = None,
+                 set_last_name_fn: Optional[Callable[[str], Awaitable[bool]]] = None,
+                 delete_sent_after_s: float = 60.0,
+                 default_sticker: str = "",
+                 inbox: Optional["asyncio.Queue[InboxItem]"] = None,
+                 dm_mount: Optional[Callable[[Any, Callable], None]] = None):
+        self.client = client
+        self.label = label
+        self.join_fn = join_fn
+        self.set_last_name_fn = set_last_name_fn
+        self.delete_sent_after_s = delete_sent_after_s
+        # No default ("") → send_sticker returns None, exactly like a
+        # TelethonHands built without one: the send-a-sticker gates
+        # never name a sticker, so the executor's own default is the
+        # only way that lane can ever fire.
+        self.default_sticker = default_sticker
+        self.inbox = inbox
+        self.dm_mount = dm_mount
+        self._dm_peer: Dict[str, Any] = {}
+        self._seen: Dict[tuple, Any] = {}   # (where, msg_id) -> tdmsg
+        self._bg: set = set()
+
+    def remember(self, where: str, tdmsg) -> None:
+        self._seen[(where, tdmsg.id)] = tdmsg
+
+    def _find(self, action: Click):
+        where = getattr(action, "where", None)
+        return (self._seen.get((where, action.msg_id)) if where else
+                self._seen.get(("group", action.msg_id)) or
+                self._seen.get(("dm", action.msg_id)))
+
+    async def click(self, action, session, on_alert=None) -> bool:
+        tdmsg = self._find(action)
+        if tdmsg is None:
+            return False
+        api = _api_of(self.client)
+        chat_id = getattr(tdmsg, "chat_id", None)
+        # Click by LABEL on a FRESH copy of the message: gate bots
+        # re-render keyboards (Rose's text2 badges reshuffle rows), and
+        # a TDLib edit update never carries the whole message anyway.
+        try:
+            fresh = await api.get_message(chat_id, tdmsg.id)
+            if fresh is not None:
+                self._seen[(getattr(action, "where", None) or "group", tdmsg.id)] = fresh
+                tdmsg = fresh
+        except Exception:
+            pass
+        rows = getattr(getattr(tdmsg, "reply_markup", None), "rows", None) or []
+        if action.label:
+            btn = next((b for row in rows for b in row
+                        if (getattr(b, "text", "") or "") == action.label), None)
+            if btn is None:      # label vanished on a re-render: row/col
+                btn = self._at(rows, action.row, action.col)
+        else:
+            btn = self._at(rows, action.row, action.col)
+        data = getattr(getattr(btn, "type_", None), "data", None) \
+            if btn is not None else None
+        if data is None:
+            # A URL button (or no such button at all). URL buttons in
+            # TDLib are client-side navigation: there is NO server-side
+            # press to send, so the action simply fails — never faked.
+            return False
+        try:
+            answer = await api.get_callback_query_answer(
+                chat_id, tdmsg.id, payload=_callback_payload(data))
+        except Exception as e:
+            # TDLib error 502 = the press WAS delivered but the bot did
+            # not answer its callback query in time. That is success
+            # for us (and there is no alert text to report).
+            try:
+                err_cls = _td_error()
+            except ImportError:
+                err_cls = None
+            if err_cls is not None and isinstance(e, err_cls) and \
+                    getattr(e, "code", None) == 502:
+                return True
+            raise
+        if on_alert is not None:
+            a = getattr(answer, "text", None)
+            if a:
+                on_alert(a)
+        return True
+
+    async def send_text(self, action: SendText, session: Session) -> Optional[Message]:
+        if action.where == "dm":
+            peer = self._dm_peer.get("chat_id")
+            if peer is None:
+                return None
+            sent = await self.client.send_text(peer, action.text)
+            where = "dm"
+        else:
+            chat = getattr(self, "_chat", None)
+            if chat is None:
+                chat = session.chat_id
+            sent = await self.client.send_text(
+                chat, action.text, reply_to_message_id=session.challenge.msg_id)
+            where = "group"
+            self._delete_later(chat, getattr(sent, "id", None))
+        m = to_message(sent, where=where)
+        m.from_me = True
+        return m
+
+    async def send_sticker(self, action: SendSticker,
+                           session: Session) -> Optional[Message]:
+        """One sticker — a reply to the challenge in the group, or into
+        the gate bot's DM. The action may carry the sticker (`file_id`:
+        a TDLib file id or a local path — aiotdlib's send_sticker takes
+        both); empty falls back to this hands' `default_sticker` (the
+        send-a-sticker gates never name one). No default configured →
+        not supported, same as PartialHands."""
+        target = action.file_id or self.default_sticker
+        if not target:
+            return None
+        if action.where == "dm":
+            peer = self._dm_peer.get("chat_id")
+            if peer is None:
+                return None
+            sent = await self.client.send_sticker(peer, target)
+            where = "dm"
+        else:
+            chat = getattr(self, "_chat", None) or session.chat_id
+            sent = await self.client.send_sticker(
+                chat, target, reply_to_message_id=session.challenge.msg_id)
+            where = "group"
+            self._delete_later(chat, getattr(sent, "id", None))
+        m = to_message(sent, where=where)
+        m.from_me = True
+        return m
+
+    async def fetch_image(self, msg: Message, session: Session) -> Optional[bytes]:
+        tdmsg = self._seen.get((msg.where or "group", msg.msg_id)) or \
+            self._seen.get(("group", msg.msg_id)) or self._seen.get(("dm", msg.msg_id))
+        if tdmsg is None:
+            return None
+        sizes = getattr(getattr(getattr(tdmsg, "content", None),
+                                "photo", None), "sizes", None) or []
+        if not sizes:
+            return None
+        fid = getattr(getattr(sizes[-1], "photo", None), "id", None)
+        if fid is None:
+            return None
+        # synchronous=True blocks until the file is on disk (priority
+        # 32 = near the front of TDLib's download queue); the returned
+        # File only carries a LOCAL path, so the bytes are read from it.
+        f = await _api_of(self.client).download_file(
+            fid, priority=32, offset=0, limit=0, synchronous=True)
+        path = getattr(getattr(f, "local", None), "path", None)
+        if not path:
+            return None
+        with open(path, "rb") as fh:
+            return fh.read()
+
+    async def fetch_bio(self, session: Session) -> str:
+        me = await _api_of(self.client).get_me()
+        full = await self.client.get_user_full_info(me.id)
+        # CAREFUL: UserFullInfo.bio is Optional[FormattedText], NOT a
+        # plain str — None (no bio) must become "", never "None".
+        return getattr(getattr(full, "bio", None), "text", None) or ""
+
+    async def set_bio(self, text: str, session: Session) -> bool:
+        try:
+            await _api_of(self.client).set_bio(bio=text or "")
+        except Exception as e:
+            # Telegram allows only a few bio edits per hour. TDLib
+            # surfaces the limit as error 429 with "retry after N" in
+            # the message. Never wait-and-retry from inside a session:
+            # surface the wait and let the decision flow end it.
+            try:
+                err_cls = _td_error()
+            except ImportError:
+                err_cls = None
+            if err_cls is not None and isinstance(e, err_cls) and \
+                    getattr(e, "code", None) == 429:
+                m = re.search(r"retry after (\d+)",
+                              str(getattr(e, "message", "") or ""))
+                wait_s = m.group(1) if m else 0
+                log.warning(f"[{self.label}] bio edit rate-limited "
+                            f"(retry after {wait_s}s)")
+                return f"flood:{wait_s}"
+            raise
+        return True
+
+    async def open_dm(self, bot_username: str, start_param: str,
+                      session: Session) -> bool:
+        api = _api_of(self.client)
+        # The gate bot's own id arrived with its message, so the DM is
+        # opened straight by id — no searchPublicChat spent. A bot the
+        # gate merely links to costs one resolve, by username.
+        if bot_username.lower() == (session.gate_bot or "") and \
+                session.challenge.sender_id:
+            bot_id = session.challenge.sender_id
+        else:
+            bot_id = getattr(await api.search_public_chat(bot_username), "id", None)
+            if bot_id is None:
+                return False
+        dm_chat = getattr(await api.create_private_chat(bot_id), "id", None)
+        if not self._dm_peer and self.dm_mount is not None:
+            self.dm_mount(dm_chat, self._push_dm)
+        self._dm_peer["chat_id"] = dm_chat
+        # The official deep-link entry point: /start <param> as a bot
+        # start message (plain /start text also works, but this one is
+        # what the deep-link flows expect).
+        await api.send_bot_start_message(bot_id, dm_chat, start_param or "")
+        return True
+
+    async def join_channel(self, ref: str, session: Session) -> bool:
+        # Native joins — TDLib has them built in, so unlike the Telethon
+        # and Pyrogram adapters no host callback is required (a join_fn
+        # still wins when the host wants its own join path).
+        if self.join_fn is not None:
+            return bool(await self.join_fn(ref))
+        try:
+            api = _api_of(self.client)
+            if "://" in ref:
+                await api.join_chat_by_invite_link(ref)
+            else:
+                chat_id = getattr(await api.search_public_chat(ref.lstrip("@")),
+                                  "id", None)
+                if chat_id is None:
+                    return False
+                await api.join_chat(chat_id)
+        except Exception as e:
+            log.info(f"[{self.label}] join {ref!r} failed: "
+                     f"{type(e).__name__}: {str(e)[:100]}")
+            return False
+        return True
+
+    async def set_last_name(self, value: str, session: Session) -> bool:
+        # Native too: set_name always requires first_name, ours is
+        # passed through untouched. A host callback still wins.
+        if self.set_last_name_fn is not None:
+            return bool(await self.set_last_name_fn(value))
+        try:
+            me = await _api_of(self.client).get_me()
+            await _api_of(self.client).set_name(
+                first_name=getattr(me, "first_name", "") or "",
+                last_name=value or "")
+        except Exception:
+            return False
+        return True
+
+    # ── internals ─────────────────────────────────────────────────────────
+    def _push_dm(self, tdmsg, edited: bool = False) -> None:
+        """The DM feeder handed to dm_mount — the DM twin of _Mounted's
+        group feed (edits arrive flagged, the Runner dedups)."""
+        if self.inbox is None:
+            return
+        m = to_message(tdmsg, where="dm")
+        if edited:
+            m.edited = True
+        self.inbox.put_nowait(("dm", m))
+
+    def set_chat(self, chat) -> None:
+        self._chat = chat
+
+    @staticmethod
+    def _at(rows, row, col):
+        try:
+            return rows[row][col]
+        except IndexError:
+            return None
+
+    def _delete_later(self, chat, msg_id) -> None:
+        if not self.delete_sent_after_s or not msg_id:
+            return
+
+        async def _go():
+            try:
+                await asyncio.sleep(self.delete_sent_after_s)
+                await _api_of(self.client).delete_messages(chat, [msg_id])
+            except asyncio.CancelledError:
+                raise
+            except Exception:
+                pass
+        try:
+            t = asyncio.get_running_loop().create_task(_go())
+            self._bg.add(t)
+            t.add_done_callback(self._bg.discard)
+        except RuntimeError:
+            pass
+
+
+class _Mounted:
+    """What `mount` returns: the feed is live until `stop()`."""
+
+    def __init__(self, client, *, account, brain, runner, join_fn,
+                 set_last_name_fn, delete_sent_after_s, default_sticker, label):
+        self.client = client
+        self.account = account
+        self.brain = brain
+        self.runner = runner
+        self.label = label
+        self._join_fn = join_fn
+        self._set_last_name_fn = set_last_name_fn
+        self._delete_sent_after_s = delete_sent_after_s
+        self._default_sticker = default_sticker
+        self._running: Dict[Any, dict] = {}   # chat_id -> session record
+        self._handlers = []                   # (handler obj, update type)
+
+    # ── the feed ──────────────────────────────────────────────────────────
+    async def on_group(self, client, update) -> None:
+        tdmsg = getattr(update, "message", None)
+        chat_id = getattr(tdmsg, "chat_id", None)
+        # TDLib ids say what a chat is: private chats (a bot DM!) are
+        # positive, groups and supergroups negative. Only groups feed
+        # the challenge detector; DMs arrive through the per-session
+        # dm_mount below, so this early-out also stops a gate bot's DM
+        # from being double-fed.
+        if tdmsg is None or chat_id is None or chat_id >= 0:
+            return
+        rec = self._running.get(chat_id)
+        if rec is not None:
+            self._feed(rec, tdmsg, "group")
+            return
+        gate = await self._gate_user(client, tdmsg)
+        if gate is None:
+            return
+        await self._start(client, tdmsg, chat_id, gate)
+
+    async def on_edit(self, client, update) -> None:
+        # BOTH edit flavors land here: updateMessageEdited carries only
+        # metadata, updateMessageContent only the new content — neither
+        # is a whole message, so the full one is re-fetched (the cached
+        # copy is stale by definition) and pushed with edited=True. The
+        # Runner dedups by (where, msg_id).
+        chat_id = getattr(update, "chat_id", None)
+        msg_id = getattr(update, "message_id", None)
+        rec = self._running.get(chat_id)
+        if rec is None or msg_id is None:
+            return
+        try:
+            tdmsg = await _api_of(client).get_message(chat_id, msg_id)
+        except Exception:
+            return
+        if tdmsg is not None:
+            self._feed(rec, tdmsg, "group", edited=True)
+
+    def _feed(self, rec, tdmsg, where: str, *, edited: bool = False) -> None:
+        """One gate-bot message onto its session's inbox — the only
+        feeder. Anything the gate bot did not say is dropped here."""
+        uid = getattr(getattr(tdmsg, "sender_id", None), "user_id", None)
+        if uid is None or uid != rec["gate_id"]:
+            return
+        rec["hands"].remember(where, tdmsg)
+        m = to_message(tdmsg, where=where, sender=rec.get("gate_user"))
+        if edited:
+            m.edited = True
+        rec["inbox"].put_nowait((where, m))
+
+    @staticmethod
+    async def _gate_user(client, tdmsg):
+        """The demo heuristic from examples/telethon_executor.py, TDLib
+        edition: an incoming BOT message carrying an inline keyboard.
+        A TDLib message carries no bot flag (only a sender union), so
+        the keyboard is checked first — free — and only then is one
+        getUser spent. Returns the gate bot's `User` (the session wants
+        its username later), or None. Whether it NAMES this account is
+        a separate fact (`names_account`) — the policy refuses to act
+        on a challenge that does not."""
+        if getattr(tdmsg, "is_outgoing", False):
+            return None
+        if not getattr(getattr(tdmsg, "reply_markup", None), "rows", None):
+            return None
+        uid = getattr(getattr(tdmsg, "sender_id", None), "user_id", None)
+        if uid is None:
+            return None
+        try:
+            user = await client.get_user(uid)
+        except Exception:
+            return None
+        return user if getattr(getattr(user, "type_", None), "ID", "") \
+            == "userTypeBot" else None
+
+    async def _start(self, client, tdmsg, chat_id, gate_user) -> None:
+        if chat_id in self._running:      # one session per chat at a time
+            return
+        if self.account is None:
+            # Lazy: only a real challenge spends the get_me() RPC.
+            me = await _api_of(client).get_me()
+            self.account = Account(getattr(me, "id", None), _first_username(me))
+        m = to_message(tdmsg, where="group", sender=gate_user)
+        ids, names = _addressed(tdmsg, m.text)
+        named = (self.account.id in ids or
+                 (self.account.username or "").lower() in names)
+        inbox: "asyncio.Queue[InboxItem]" = asyncio.Queue()
+        hands = TDLibHands(client, label=self.label, join_fn=self._join_fn,
+                           set_last_name_fn=self._set_last_name_fn,
+                           delete_sent_after_s=self._delete_sent_after_s,
+                           default_sticker=self._default_sticker, inbox=inbox)
+        hands.set_chat(chat_id)
+        hands.remember("group", tdmsg)
+        chat_title = None
+        try:      # a TDLib message knows its chat only by id
+            chat_title = getattr(await client.get_chat(chat_id), "title", None)
+        except Exception:
+            pass
+        session = Session(
+            session_id=uuid.uuid4().hex,
+            account=self.account,
+            challenge=m,
+            chat_id=chat_id,
+            chat_title=chat_title,
+            names_account=named)
+        rec = {"inbox": inbox, "hands": hands, "gate_id": m.sender_id,
+               "gate_user": gate_user, "task": None, "dm_handlers": []}
+
+        def dm_mount(dm_chat_id, push):
+            # Same pattern as executor.py: the DM handlers are
+            # per-session and come off with the session. aiotdlib has
+            # no chat filters, so the dm chat id is checked inside each
+            # callback; edits are re-fetched, exactly like on_edit.
+            from aiotdlib.api import API    # lazy, same as mount()
+            t = API.Types
+
+            async def _on_new(_client, update):
+                dmsg = getattr(update, "message", None)
+                if getattr(dmsg, "chat_id", None) == dm_chat_id:
+                    push(dmsg)
+
+            async def _on_edit(_client, update):
+                if getattr(update, "chat_id", None) != dm_chat_id:
+                    return
+                try:
+                    dmsg = await _api_of(client).get_message(
+                        dm_chat_id, update.message_id)
+                except Exception:
+                    return
+                if dmsg is not None:
+                    push(dmsg, edited=True)
+
+            for ut, cb in ((t.UPDATE_NEW_MESSAGE, _on_new),
+                           (t.UPDATE_MESSAGE_EDITED, _on_edit),
+                           (t.UPDATE_MESSAGE_CONTENT, _on_edit)):
+                rec["dm_handlers"].append((client.add_event_handler(cb, ut), ut))
+
+        hands.dm_mount = dm_mount
+        self._running[chat_id] = rec
+        rec["task"] = asyncio.get_running_loop().create_task(self._run(session, hands,
+                                                                       inbox, chat_id, rec))
+
+    async def _run(self, session, hands, inbox, chat_id, rec) -> None:
+        try:
+            out = await self.runner.run(session, hands, inbox)
+            log.info(f"[{self.label}] chat {chat_id}: {out['result']} — {out['reason']}")
+            return out
+        finally:
+            for h, ut in rec["dm_handlers"]:
+                try:
+                    self.client.remove_event_handler(h, ut)
+                except Exception:
+                    pass
+            self._running.pop(chat_id, None)
+
+    # ── lifecycle ─────────────────────────────────────────────────────────
+    def stop(self) -> None:
+        """Remove every handler mount added. Running sessions finish on
+        their own (the Runner's deadline bounds them)."""
+        for h, ut in self._handlers:
+            try:
+                self.client.remove_event_handler(h, ut)
+            except Exception:
+                pass
+        self._handlers = []
+
+
+def mount(client, *, account: Optional[Account] = None,
+          brain: Optional[Brain] = None,
+          delay_fn: Optional[DelayFn] = None,
+          join_fn: Optional[Callable[[str], Awaitable[bool]]] = None,
+          set_last_name_fn: Optional[Callable[[str], Awaitable[bool]]] = None,
+          policy: Optional[PolicyConfig] = None,
+          observe_s: float = 8.0, quiet_s: float = 2.0,
+          session_deadline_s: float = 300.0, delete_sent_after_s: float = 60.0,
+          default_sticker: str = "", label: str = "?") -> _Mounted:
+    """The 3-line UX: watch the account's groups for captcha challenges
+    and run one session per chat through the shared Runner.
+
+    `account` may be left None — it is fetched via `api.get_me()`
+    lazily, when the first challenge actually appears. `delay_fn` None
+    means no human pause, exactly as in the Telethon executor. Unlike
+    the Telethon/Pyrogram adapters, join_channel and set_last_name are
+    NATIVE here (TDLib ships joinChatByInviteLink and setName) — the
+    host callbacks still win when given. `default_sticker` is the
+    executor's own sticker for the send-a-sticker gates, which never
+    name one.
+    """
+    from aiotdlib.api import API    # the one aiotdlib import: update names
+    t = API.Types
+
+    b = brain or Brain()      # one Brain: Brain() = the local Engine only
+    mounted = _Mounted(
+        client, account=account, brain=b,
+        runner=Runner(b, policy=policy or PolicyConfig(),
+                      delay_fn=delay_fn, observe_s=observe_s, quiet_s=quiet_s,
+                      session_deadline_s=session_deadline_s, label=label),
+        join_fn=join_fn, set_last_name_fn=set_last_name_fn,
+        delete_sent_after_s=delete_sent_after_s, default_sticker=default_sticker,
+        label=label)
+
+    # New group messages, plus BOTH edit flavors (TDLib splits edits
+    # into updateMessageEdited / updateMessageContent; both re-fetch in
+    # on_edit). add_event_handler returns the Handler object
+    # remove_event_handler wants, so it is kept.
+    for ut, cb in ((t.UPDATE_NEW_MESSAGE, mounted.on_group),
+                   (t.UPDATE_MESSAGE_EDITED, mounted.on_edit),
+                   (t.UPDATE_MESSAGE_CONTENT, mounted.on_edit)):
+        mounted._handlers.append((client.add_event_handler(cb, ut), ut))
+    return mounted