mcp-telegram-bridge 0.1.0__tar.gz

mcp_telegram_bridge-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Antonio Castellon / Castellon.CH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_telegram_bridge-0.1.0/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: mcp-telegram-bridge
+Version: 0.1.0
+Summary: Stdio MCP server: controlled Telegram Bot API bridge for any MCP host.
+Author-email: Antonio Castellon <hello@castellon.ch>
+License: MIT
+Project-URL: Homepage, https://github.com/antonio-castellon/mcp-telegram-bridge
+Project-URL: Issues, https://github.com/antonio-castellon/mcp-telegram-bridge/issues
+Keywords: mcp,telegram,bot,stdio,bridge
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Chat
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp<2,>=1.9.0
+Requires-Dist: httpx<1,>=0.27.0
+Requires-Dist: pydantic<3,>=2.7.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+Requires-Dist: respx>=0.21; extra == "dev"
+Dynamic: license-file
+
+# mcp-telegram-bridge
+
+**Controlled Telegram channel bridge for any MCP host.**
+
+A small stdio [Model Context Protocol](https://modelcontextprotocol.io/) server that sits between your local agent (Cursor, Claude Desktop, Windsurf, Grok/Cursor agents, and others) and the Telegram Bot API. The agent owns conversation logic; this process handles I/O, always-on outbound scrubbing, and chat allowlist enforcement. Optional strict inbound classification is disabled by default.
+
+Built for client-owned deployments — the bridge runs on **your machine**, not on a hosted Grok VM. Games and game-master flows are one demo use case, not the product.
+
+Owner context: [Antonio Castellon](https://castellon.ch) / Castellon.CH — Swiss freelance architect. The same bridge shape is useful for SME lab patterns (notify channels, specialist handoff, moderated drafts) alongside email or ERP connectors.
+
+## What / why
+
+Agents are good at reasoning and poor at holding a raw Bot API session by themselves. Telegram is a convenient human surface (groups, buttons, mobile). This project gives you a **narrow, reviewable bridge**:
+
+- **Client-owned** — stdio MCP on the workstation or CI runner that already hosts your agent.
+- **Host-agnostic** — any MCP client that can launch a local command.
+- **Controlled** — outbound scrubbing and optional `ALLOWED_CHAT_IDS`; optional strict inbound classification for untrusted groups.
+- **Minimal tools** — send, edit markup, answer callbacks, get updates, getMe / getChat. No game engine, no inbox file, no wake-RPC.
+
+Pitch pattern for SMEs: start with a Telegram notify or triage channel using the same architecture you would later apply to email or ERP.
+
+## Architecture
+
+```
+  ┌─────────────────────────┐
+  │  MCP host / agents      │  Cursor · Claude Desktop · Windsurf · …
+  │  (conversation logic)   │
+  └───────────┬─────────────┘
+              │  MCP (stdio)
+              â–¼
+  ┌─────────────────────────┐
+  │  mcp-telegram-bridge    │  tools + safety scrub/classify
+  │  (this process)         │
+  └───────────┬─────────────┘
+              │  HTTPS Bot API
+              â–¼
+  ┌─────────────────────────┐
+  │  api.telegram.org       │
+  └───────────┬─────────────┘
+              â–¼
+         Telegram chats / groups
+```
+
+The **agent** owns polling offsets, handoffs between specialists, and product policy. This server enforces destination controls and sends scrubbed text; inbound classification is opt-in.
+
+## Install
+
+Requirements: Python 3.11+, a Telegram bot token from [@BotFather](https://t.me/BotFather).
+
+```bash
+git clone https://github.com/antonio-castellon/mcp-telegram-bridge.git
+cd mcp-telegram-bridge
+python -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+cp .env.example .env        # set TELEGRAM_BOT_TOKEN (never commit .env)
+```
+
+Or without cloning, once published:
+
+```bash
+uvx --from mcp-telegram-bridge mcp-telegram-bridge
+# or: pipx run mcp-telegram-bridge
+```
+
+### Cursor / Claude Desktop (`mcp.json`)
+
+Example for Cursor (User MCP settings) or Claude Desktop (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "telegram-bridge": {
+      "command": "uvx",`r`n      "args": ["--from", "mcp-telegram-bridge", "mcp-telegram-bridge"],
+      "env": {
+        "TELEGRAM_BOT_TOKEN": "YOUR_BOT_TOKEN_HERE",
+        "ALLOWED_CHAT_IDS": "-1001234567890"
+      }
+    }
+  }
+}
+```
+
+On Windows, point `command` at your venv Python if needed, for example:
+
+`C:\\DEV.Personal\\mcp-telegram-bridge\\.venv\\Scripts\\python.exe`
+
+Leave `ALLOWED_CHAT_IDS` empty only if you intentionally accept traffic from every chat the bot can see — document that risk for your deployment.
+
+Smoke without a host:
+
+```bash
+python -m mcp_telegram_bridge
+# process waits on stdio for MCP JSON-RPC (Ctrl+C to stop)
+```
+
+## MCP tools
+
+| Tool | Purpose |
+|---|---|
+| `telegram_get_me` | Bot identity / connectivity check |
+| `telegram_send_message` | `chat_id`, `text`, optional `parse_mode`, optional `buttons=[{id,label}]` |
+| `telegram_edit_reply_markup` | Strip or replace inline buttons |
+| `telegram_answer_callback` | Ack a `callback_query_id` (optional toast) |
+| `telegram_get_updates` | `offset`, `limit`, `timeout` — returns messages + callback_queries; **agent owns the loop** |
+| `telegram_get_chat` | Chat metadata |
+
+Outbound text is always scrubbed. `ALLOWED_CHAT_IDS` restricts destinations when configured. `telegram_get_updates` runs the heuristic secret/NSFW classifier only when `SAFETY_STRICT=1` (or `true`/`yes`/`on`); strict mode is optional and recommended for public or untrusted groups.
+
+## Usage guide
+
+### Collaborative agents in a Telegram group
+
+Run one bridge process per bot (or one bot with clear agent roles). Use the group for standup notes, triage queues, and handoff between specialist agents (“ops acknowledges; billing drafts the reply”). Keep humans in the loop for irreversible actions.
+
+### Game master / tabletop facilitator (demo)
+
+Send scene text with `buttons=[{id,label}, …]` for player choices; on `callback_query`, answer the callback, optionally `claim`-style first-tap handling in the agent, then edit markup to clear spent choices. This is a **demo** of buttons + agent loop — not a bundled RPG engine.
+
+### Support / ops notify channel
+
+Push alerts with ack buttons (`ack`, `snooze`, `escalate`). The agent records who tapped what; Telegram is the pager surface, not the source of truth.
+
+### Community moderation assistant
+
+Draft replies and suggest actions. **Humans still own ban / restrict / delete** in Telegram Admin — say so in your agent prompt. The bridge must not be treated as a moderation authority.
+
+### Lab / SME pattern
+
+Same shape as an email or ERP connector: narrow tools, allow-listed destinations, scrubbed egress, explicit inbound warnings. Telegram is the demo channel; swap the transport later without rewriting agent policy.
+
+## What this is NOT
+
+- Not a hosted bot SaaS or multi-tenant cloud bridge
+- Not Grok-only (works with any stdio MCP host)
+- Not a full RPG / game engine (no dice ruleset, no campaign DB in this repo)
+- Not an unattended admin bot (no ban tools shipped here)
+
+## Relation to sibling demos
+
+Optional context only — this project does **not** require them:
+
+- [grokgame](https://github.com/antonio-castellon/grokgame) — tabletop / game demo surface
+- [grok2telegram](https://github.com/antonio-castellon/grok2telegram) — earlier bridge experiment whose safety doctrine informed `SAFETY.md` and `safety.py`
+
+`mcp-telegram-bridge` is the reusable, host-agnostic extraction: I/O + safety, no game loop and no Grok VM wake logic.
+
+## Safety
+
+See **[SAFETY.md](SAFETY.md)** for the threat model, always-on scrubbing and allowlist controls, token handling, and optional strict mode. Do not put secrets in the repository; prefer `ALLOWED_CHAT_IDS` in production-like setups.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+Tests mock Telegram HTTP with `respx` / `httpx`; no live token required.
+
+## MCP Registry
+
+Canonical name: `io.github.antonio-castellon/mcp-telegram-bridge`
+
+<!-- mcp-name: io.github.antonio-castellon/mcp-telegram-bridge -->
+
+## License
+
+MIT © Antonio Castellon / Castellon.CH
+

mcp_telegram_bridge-0.1.0/README.md

@@ -0,0 +1,170 @@
+# mcp-telegram-bridge
+
+**Controlled Telegram channel bridge for any MCP host.**
+
+A small stdio [Model Context Protocol](https://modelcontextprotocol.io/) server that sits between your local agent (Cursor, Claude Desktop, Windsurf, Grok/Cursor agents, and others) and the Telegram Bot API. The agent owns conversation logic; this process handles I/O, always-on outbound scrubbing, and chat allowlist enforcement. Optional strict inbound classification is disabled by default.
+
+Built for client-owned deployments — the bridge runs on **your machine**, not on a hosted Grok VM. Games and game-master flows are one demo use case, not the product.
+
+Owner context: [Antonio Castellon](https://castellon.ch) / Castellon.CH — Swiss freelance architect. The same bridge shape is useful for SME lab patterns (notify channels, specialist handoff, moderated drafts) alongside email or ERP connectors.
+
+## What / why
+
+Agents are good at reasoning and poor at holding a raw Bot API session by themselves. Telegram is a convenient human surface (groups, buttons, mobile). This project gives you a **narrow, reviewable bridge**:
+
+- **Client-owned** — stdio MCP on the workstation or CI runner that already hosts your agent.
+- **Host-agnostic** — any MCP client that can launch a local command.
+- **Controlled** — outbound scrubbing and optional `ALLOWED_CHAT_IDS`; optional strict inbound classification for untrusted groups.
+- **Minimal tools** — send, edit markup, answer callbacks, get updates, getMe / getChat. No game engine, no inbox file, no wake-RPC.
+
+Pitch pattern for SMEs: start with a Telegram notify or triage channel using the same architecture you would later apply to email or ERP.
+
+## Architecture
+
+```
+  ┌─────────────────────────┐
+  │  MCP host / agents      │  Cursor · Claude Desktop · Windsurf · …
+  │  (conversation logic)   │
+  └───────────┬─────────────┘
+              │  MCP (stdio)
+              â–¼
+  ┌─────────────────────────┐
+  │  mcp-telegram-bridge    │  tools + safety scrub/classify
+  │  (this process)         │
+  └───────────┬─────────────┘
+              │  HTTPS Bot API
+              â–¼
+  ┌─────────────────────────┐
+  │  api.telegram.org       │
+  └───────────┬─────────────┘
+              â–¼
+         Telegram chats / groups
+```
+
+The **agent** owns polling offsets, handoffs between specialists, and product policy. This server enforces destination controls and sends scrubbed text; inbound classification is opt-in.
+
+## Install
+
+Requirements: Python 3.11+, a Telegram bot token from [@BotFather](https://t.me/BotFather).
+
+```bash
+git clone https://github.com/antonio-castellon/mcp-telegram-bridge.git
+cd mcp-telegram-bridge
+python -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+cp .env.example .env        # set TELEGRAM_BOT_TOKEN (never commit .env)
+```
+
+Or without cloning, once published:
+
+```bash
+uvx --from mcp-telegram-bridge mcp-telegram-bridge
+# or: pipx run mcp-telegram-bridge
+```
+
+### Cursor / Claude Desktop (`mcp.json`)
+
+Example for Cursor (User MCP settings) or Claude Desktop (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "telegram-bridge": {
+      "command": "uvx",`r`n      "args": ["--from", "mcp-telegram-bridge", "mcp-telegram-bridge"],
+      "env": {
+        "TELEGRAM_BOT_TOKEN": "YOUR_BOT_TOKEN_HERE",
+        "ALLOWED_CHAT_IDS": "-1001234567890"
+      }
+    }
+  }
+}
+```
+
+On Windows, point `command` at your venv Python if needed, for example:
+
+`C:\\DEV.Personal\\mcp-telegram-bridge\\.venv\\Scripts\\python.exe`
+
+Leave `ALLOWED_CHAT_IDS` empty only if you intentionally accept traffic from every chat the bot can see — document that risk for your deployment.
+
+Smoke without a host:
+
+```bash
+python -m mcp_telegram_bridge
+# process waits on stdio for MCP JSON-RPC (Ctrl+C to stop)
+```
+
+## MCP tools
+
+| Tool | Purpose |
+|---|---|
+| `telegram_get_me` | Bot identity / connectivity check |
+| `telegram_send_message` | `chat_id`, `text`, optional `parse_mode`, optional `buttons=[{id,label}]` |
+| `telegram_edit_reply_markup` | Strip or replace inline buttons |
+| `telegram_answer_callback` | Ack a `callback_query_id` (optional toast) |
+| `telegram_get_updates` | `offset`, `limit`, `timeout` — returns messages + callback_queries; **agent owns the loop** |
+| `telegram_get_chat` | Chat metadata |
+
+Outbound text is always scrubbed. `ALLOWED_CHAT_IDS` restricts destinations when configured. `telegram_get_updates` runs the heuristic secret/NSFW classifier only when `SAFETY_STRICT=1` (or `true`/`yes`/`on`); strict mode is optional and recommended for public or untrusted groups.
+
+## Usage guide
+
+### Collaborative agents in a Telegram group
+
+Run one bridge process per bot (or one bot with clear agent roles). Use the group for standup notes, triage queues, and handoff between specialist agents (“ops acknowledges; billing drafts the reply”). Keep humans in the loop for irreversible actions.
+
+### Game master / tabletop facilitator (demo)
+
+Send scene text with `buttons=[{id,label}, …]` for player choices; on `callback_query`, answer the callback, optionally `claim`-style first-tap handling in the agent, then edit markup to clear spent choices. This is a **demo** of buttons + agent loop — not a bundled RPG engine.
+
+### Support / ops notify channel
+
+Push alerts with ack buttons (`ack`, `snooze`, `escalate`). The agent records who tapped what; Telegram is the pager surface, not the source of truth.
+
+### Community moderation assistant
+
+Draft replies and suggest actions. **Humans still own ban / restrict / delete** in Telegram Admin — say so in your agent prompt. The bridge must not be treated as a moderation authority.
+
+### Lab / SME pattern
+
+Same shape as an email or ERP connector: narrow tools, allow-listed destinations, scrubbed egress, explicit inbound warnings. Telegram is the demo channel; swap the transport later without rewriting agent policy.
+
+## What this is NOT
+
+- Not a hosted bot SaaS or multi-tenant cloud bridge
+- Not Grok-only (works with any stdio MCP host)
+- Not a full RPG / game engine (no dice ruleset, no campaign DB in this repo)
+- Not an unattended admin bot (no ban tools shipped here)
+
+## Relation to sibling demos
+
+Optional context only — this project does **not** require them:
+
+- [grokgame](https://github.com/antonio-castellon/grokgame) — tabletop / game demo surface
+- [grok2telegram](https://github.com/antonio-castellon/grok2telegram) — earlier bridge experiment whose safety doctrine informed `SAFETY.md` and `safety.py`
+
+`mcp-telegram-bridge` is the reusable, host-agnostic extraction: I/O + safety, no game loop and no Grok VM wake logic.
+
+## Safety
+
+See **[SAFETY.md](SAFETY.md)** for the threat model, always-on scrubbing and allowlist controls, token handling, and optional strict mode. Do not put secrets in the repository; prefer `ALLOWED_CHAT_IDS` in production-like setups.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+Tests mock Telegram HTTP with `respx` / `httpx`; no live token required.
+
+## MCP Registry
+
+Canonical name: `io.github.antonio-castellon/mcp-telegram-bridge`
+
+<!-- mcp-name: io.github.antonio-castellon/mcp-telegram-bridge -->
+
+## License
+
+MIT © Antonio Castellon / Castellon.CH
+

mcp_telegram_bridge-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mcp-telegram-bridge"
+version = "0.1.0"
+description = "Stdio MCP server: controlled Telegram Bot API bridge for any MCP host."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+authors = [
+  { name = "Antonio Castellon", email = "hello@castellon.ch" },
+]
+keywords = ["mcp", "telegram", "bot", "stdio", "bridge"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Communications :: Chat",
+]
+dependencies = [
+  "mcp>=1.9.0,<2",
+  "httpx>=0.27.0,<1",
+  "pydantic>=2.7.0,<3",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "pytest-asyncio>=0.24",
+  "respx>=0.21",
+]
+
+[project.scripts]
+mcp-telegram-bridge = "mcp_telegram_bridge.__main__:main"
+
+[project.urls]
+Homepage = "https://github.com/antonio-castellon/mcp-telegram-bridge"
+Issues = "https://github.com/antonio-castellon/mcp-telegram-bridge/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+pythonpath = ["src"]

mcp_telegram_bridge-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mcp_telegram_bridge-0.1.0/src/mcp_telegram_bridge/__init__.py

@@ -0,0 +1,5 @@
+"""mcp-telegram-bridge — stdio MCP server for Telegram Bot API I/O + safety."""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

mcp_telegram_bridge-0.1.0/src/mcp_telegram_bridge/__main__.py

@@ -0,0 +1,13 @@
+"""python -m mcp_telegram_bridge — start the stdio MCP server."""
+
+from __future__ import annotations
+
+
+def main() -> None:
+    from .server import main as run
+
+    run()
+
+
+if __name__ == "__main__":
+    main()

mcp_telegram_bridge-0.1.0/src/mcp_telegram_bridge/buttons.py

@@ -0,0 +1,192 @@
+"""Inline keyboard helpers and claim_message_tap (first tap wins)."""
+
+from __future__ import annotations
+
+import json
+import secrets
+import time
+from pathlib import Path
+from typing import Any
+
+# Telegram Bot API: callback_data max 1–64 bytes.
+CALLBACK_DATA_MAX = 64
+_MAP_NAME = "callback_map.json"
+_MAP_MAX_ENTRIES = 2000
+_CLAIM_NAME = "callback_claimed.json"
+_CLAIM_MAX = 500
+
+
+def normalize_buttons(buttons: list[dict[str, Any]] | None) -> list[dict[str, str]]:
+    """Normalize [{id, label}] (label may also be ``text``)."""
+    if not buttons:
+        return []
+    out: list[dict[str, str]] = []
+    for i, row in enumerate(buttons):
+        if not isinstance(row, dict):
+            raise ValueError(f"buttons[{i}] must be an object")
+        bid = str(row.get("id") or "").strip()
+        label = str(row.get("label") or row.get("text") or "").strip()
+        if not bid or not label:
+            raise ValueError(f"buttons[{i}] needs id and label")
+        out.append({"id": bid, "label": label})
+    return out
+
+
+def parse_buttons_arg(raw: str) -> list[dict[str, str]]:
+    """Parse ``id:Label|id:Label`` into ``[{id, label}, ...]``."""
+    text = (raw or "").strip()
+    if not text:
+        return []
+    out: list[dict[str, str]] = []
+    for part in text.split("|"):
+        part = part.strip()
+        if not part:
+            continue
+        if ":" not in part:
+            raise ValueError(f"button needs id:Label, got {part!r}")
+        bid, label = part.split(":", 1)
+        bid = bid.strip()
+        label = label.strip()
+        if not bid or not label:
+            raise ValueError(f"empty id or label in {part!r}")
+        out.append({"id": bid, "label": label})
+    return out
+
+
+def _map_path(data_dir: Path) -> Path:
+    data_dir.mkdir(parents=True, exist_ok=True)
+    return data_dir / _MAP_NAME
+
+
+def _load_map(data_dir: Path) -> dict[str, Any]:
+    p = _map_path(data_dir)
+    if not p.exists():
+        return {}
+    try:
+        data = json.loads(p.read_text(encoding="utf-8"))
+        return data if isinstance(data, dict) else {}
+    except Exception:
+        return {}
+
+
+def _save_map(data_dir: Path, mapping: dict[str, Any]) -> None:
+    if len(mapping) > _MAP_MAX_ENTRIES:
+        items = sorted(
+            mapping.items(),
+            key=lambda kv: float((kv[1] or {}).get("ts") or 0),
+        )
+        mapping = dict(items[-_MAP_MAX_ENTRIES:])
+    _map_path(data_dir).write_text(
+        json.dumps(mapping, ensure_ascii=False, indent=2),
+        encoding="utf-8",
+    )
+
+
+def _callback_data_for(button_id: str, chat_id: int, data_dir: Path | None) -> str:
+    """Return callback_data ≤64 bytes; map long ids via short token."""
+    raw = (button_id or "").strip()
+    encoded = raw.encode("utf-8")
+    if 1 <= len(encoded) <= CALLBACK_DATA_MAX and "\n" not in raw:
+        return raw
+    if data_dir is None:
+        raise ValueError(
+            f"button id exceeds {CALLBACK_DATA_MAX} bytes; configure data_dir for mapping"
+        )
+    token = secrets.token_hex(4)
+    key = f"{chat_id}:{token}"
+    mapping = _load_map(data_dir)
+    mapping[key] = {"id": raw, "ts": time.time()}
+    _save_map(data_dir, mapping)
+    cb = f"t:{token}"
+    assert len(cb.encode("utf-8")) <= CALLBACK_DATA_MAX
+    return cb
+
+
+def resolve_callback_data(data_dir: Path, chat_id: int, callback_data: str) -> str:
+    """Map callback_data back to the agent-facing button id."""
+    raw = (callback_data or "").strip()
+    if raw.startswith("t:") and len(raw) > 2:
+        token = raw[2:]
+        key = f"{chat_id}:{token}"
+        mapping = _load_map(data_dir)
+        row = mapping.get(key)
+        if isinstance(row, dict) and row.get("id"):
+            return str(row["id"])
+    return raw
+
+
+def build_inline_keyboard(
+    buttons: list[dict[str, str]],
+    *,
+    chat_id: int,
+    data_dir: Path | None = None,
+    row_width: int = 2,
+) -> dict[str, Any]:
+    """Build Telegram InlineKeyboardMarkup from [{id, label}, ...]."""
+    if not buttons:
+        raise ValueError("buttons list is empty")
+    rows: list[list[dict[str, str]]] = []
+    row: list[dict[str, str]] = []
+    for btn in buttons:
+        bid = str(btn.get("id") or "").strip()
+        label = str(btn.get("label") or btn.get("text") or "").strip()
+        if not bid or not label:
+            raise ValueError(f"invalid button: {btn!r}")
+        text = label[:64]
+        cb = _callback_data_for(bid, chat_id, data_dir)
+        row.append({"text": text, "callback_data": cb})
+        if len(row) >= max(1, row_width):
+            rows.append(row)
+            row = []
+    if row:
+        rows.append(row)
+    return {"inline_keyboard": rows}
+
+
+def _claim_path(data_dir: Path) -> Path:
+    data_dir.mkdir(parents=True, exist_ok=True)
+    return data_dir / _CLAIM_NAME
+
+
+def claim_message_tap(
+    data_dir: Path,
+    chat_id: int,
+    message_id: int,
+    *,
+    verb: str,
+    uid: int,
+) -> bool:
+    """First tap on a message wins. Return True if claimed; False if duplicate."""
+    path = _claim_path(data_dir)
+    try:
+        data = json.loads(path.read_text(encoding="utf-8")) if path.exists() else {}
+    except Exception:
+        data = {}
+    if not isinstance(data, dict):
+        data = {}
+    key = f"{int(chat_id)}:{int(message_id)}"
+    if key in data:
+        return False
+    data[key] = {"verb": verb, "uid": int(uid), "ts": time.time()}
+    if len(data) > _CLAIM_MAX:
+        items = sorted(data.items(), key=lambda kv: float((kv[1] or {}).get("ts") or 0))
+        data = dict(items[-_CLAIM_MAX:])
+    path.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
+    return True
+
+
+def label_from_callback_message(msg: dict[str, Any], callback_data: str) -> str | None:
+    """Best-effort label from the tapped message's inline keyboard."""
+    raw = (callback_data or "").strip()
+    markup = (msg or {}).get("reply_markup") or {}
+    rows = markup.get("inline_keyboard") or []
+    for row in rows:
+        if not isinstance(row, list):
+            continue
+        for btn in row:
+            if not isinstance(btn, dict):
+                continue
+            if str(btn.get("callback_data") or "") == raw:
+                text = str(btn.get("text") or "").strip()
+                return text or None
+    return None