web_server_messaging.py 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302
  1. """Messaging-platform catalog and onboarding helpers: platform overrides/env discovery, WhatsApp
  2. and Telegram onboarding state.
  3. """
  4. import logging
  5. import os
  6. import subprocess
  7. import threading
  8. from dataclasses import dataclass
  9. from fastapi import HTTPException
  10. from pathlib import Path
  11. from typing import Any, Optional
  12. from hermes_cli.config import OPTIONAL_ENV_VARS, write_platform_config_field
  13. from hermes_cli.setup_hidden_env import is_setup_hidden_env as _is_setup_hidden_env
  14. from hermes_cli.version_info import hermes_user_agent
  15. # Same logger the code used before extraction (record parity).
  16. _log = logging.getLogger("hermes_cli.web_server")
  17. # Card metadata for core-only platforms (no plugin, so no PlatformEntry to declare it). Plugin
  18. # platforms declare theirs on their PlatformEntry (``dashboard_*`` / ``docs_url``, see
  19. # :func:`_plugin_card_fields`). Entries omit fields they don't need; the catalog builder fills in
  20. # env_vars from OPTIONAL_ENV_VARS via prefix matching when not specified.
  21. _PLATFORM_OVERRIDES: dict[str, dict[str, Any]] = {
  22. "api_server": {
  23. "name": "API server",
  24. "description": "Expose Hermes as an OpenAI-compatible HTTP API for tools like Open WebUI.",
  25. "docs_url": "https://hermes-agent.nousresearch.com/docs/user-guide/messaging/",
  26. "env_vars": (
  27. "API_SERVER_ENABLED", "API_SERVER_KEY", "API_SERVER_PORT", "API_SERVER_HOST",
  28. "API_SERVER_MODEL_NAME",
  29. ),
  30. "required_env": (),
  31. },
  32. "webhook": {
  33. "name": "Webhooks",
  34. "description": "Receive events from GitHub, GitLab, and other webhook sources.",
  35. "docs_url": "https://hermes-agent.nousresearch.com/docs/user-guide/messaging/webhooks/",
  36. "env_vars": ("WEBHOOK_ENABLED", "WEBHOOK_PORT", "WEBHOOK_SECRET"), "required_env": (),
  37. },
  38. "msgraph_webhook": {
  39. "name": "Microsoft Graph Webhook",
  40. "description": "Receive Microsoft Graph change notifications (Teams meetings, Outlook, …).",
  41. "docs_url": "https://hermes-agent.nousresearch.com/docs/user-guide/messaging/msgraph-webhook",
  42. "required_env": (),
  43. },
  44. "relay": {
  45. "name": "Relay (experimental)",
  46. "description": "Generic relay adapter fronted by the Hermes Relay connector.",
  47. "docs_url": "", "required_env": (),
  48. },
  49. }
  50. # Display order: well-known platforms surface first; unknown plugins fall to
  51. # the end alphabetically.
  52. _PLATFORM_ORDER: tuple[str, ...] = (
  53. "telegram", "discord", "slack", "mattermost", "matrix", "whatsapp", "signal", "bluebubbles",
  54. "email", "sms", "dingtalk", "feishu", "google_chat", "wecom", "wecom_callback",
  55. "weixin", "qqbot", "yuanbao", "api_server", "webhook",
  56. )
  57. def _messaging_platform_catalog() -> tuple[dict[str, Any], ...]:
  58. """Build the messaging catalog from the gateway's Platform enum + plugin registry.
  59. Built-ins come from ``gateway.config.Platform`` (LOCAL excluded); plugin platforms from
  60. ``platform_registry.plugin_entries()`` so new adapters appear without a code change here.
  61. UI metadata comes from each plugin's PlatformEntry, or :data:`_PLATFORM_OVERRIDES` for core-only
  62. platforms; the rest is derived from id/required_env.
  63. """
  64. from gateway.config import Platform
  65. # Resolve plugin entries FIRST: plugin platforms leak into ``Platform.__members__`` as
  66. # pseudo-members once anything calls ``Platform("<plugin id>")``, and iterating the enum
  67. # first would claim them with no plugin metadata (nameless "Irc"/"Ntfy" cards).
  68. plugin_map: dict[str, Any] = {}
  69. try:
  70. # Plugin discovery normally runs as a side effect of importing model_tools, which this
  71. # server process doesn't do — trigger it explicitly (idempotent).
  72. from hermes_cli.plugins import discover_plugins
  73. discover_plugins()
  74. from gateway.platform_registry import platform_registry
  75. for plugin_entry in platform_registry.plugin_entries():
  76. plugin_map[plugin_entry.name] = plugin_entry
  77. except Exception:
  78. _log.debug("plugin platform registry unavailable", exc_info=True)
  79. seen: set[str] = set()
  80. entries: list[dict[str, Any]] = []
  81. builtin = [m.value for m in Platform.__members__.values() if m.value != "local"]
  82. for pid in builtin + list(plugin_map):
  83. if pid in seen:
  84. continue
  85. seen.add(pid)
  86. entries.append(_build_catalog_entry(pid, plugin_map.get(pid)))
  87. order = {pid: idx for idx, pid in enumerate(_PLATFORM_ORDER)}
  88. entries.sort(key=lambda e: (order.get(e["id"], len(_PLATFORM_ORDER)), e["name"].lower()))
  89. return tuple(entries)
  90. def _channel_managed_env_keys() -> frozenset[str]:
  91. """Env-var keys owned by a Channels page platform card; the Keys/Env page hides them so the
  92. same fields aren't duplicated. Best-effort: if the catalog can't be built, nothing is hidden."""
  93. try:
  94. return frozenset(k for entry in _messaging_platform_catalog() for k in entry.get("env_vars", ()))
  95. except Exception:
  96. _log.debug("could not build channel-managed env key set", exc_info=True)
  97. return frozenset()
  98. # Cross-cutting gateway / relay knobs stay on the Keys → Settings tab even though
  99. # they use the ``messaging`` category in OPTIONAL_ENV_VARS. Platform-scoped vars
  100. # (``DISCORD_*``, ``MATRIX_*``, …) are owned by the Messaging UI instead.
  101. _MESSAGING_KEYS_PAGE_KEYS = frozenset({
  102. "GATEWAY_ALLOW_ALL_USERS", "GATEWAY_PROXY_KEY", "GATEWAY_PROXY_URL"})
  103. def _platform_env_prefixes(platform_id: str) -> tuple[str, ...]:
  104. """Env-var prefixes owned by a messaging platform card (shared with the profile-clone
  105. channel stripper so a card and a clone agree on which keys belong to a platform)."""
  106. from hermes_cli.profile_channels import platform_env_prefixes
  107. return platform_env_prefixes(platform_id)
  108. def _discover_platform_env_vars(platform_id: str) -> tuple[str, ...]:
  109. """All messaging-category env vars for a platform (override + plugin + prefix)."""
  110. prefixes = _platform_env_prefixes(platform_id)
  111. return tuple(sorted({
  112. name for name, info in OPTIONAL_ENV_VARS.items()
  113. if info.get("category") == "messaging"
  114. and name not in _MESSAGING_KEYS_PAGE_KEYS
  115. and not _is_setup_hidden_env(name)
  116. and any(name.startswith(prefix) for prefix in prefixes)}))
  117. def _merge_platform_env_vars(platform_id: str, override: dict[str, Any], plugin_entry: Any | None) -> tuple[str, ...]:
  118. """Canonical env-var list for a platform card. Required credentials always survive: hiding a
  119. required field would make the platform unconfigurable."""
  120. discovered = _discover_platform_env_vars(platform_id)
  121. if "env_vars" in override:
  122. explicit = tuple(key for key in override["env_vars"] if not _is_setup_hidden_env(key))
  123. return tuple(dict.fromkeys((*explicit, *discovered)))
  124. if plugin_entry is not None and plugin_entry.required_env:
  125. return tuple(dict.fromkeys((*tuple(plugin_entry.required_env), *discovered)))
  126. return discovered
  127. def _plugin_card_fields(plugin_entry: Any) -> dict[str, Any]:
  128. """A plugin's declared card metadata in override shape; undeclared fields are left out so
  129. the builder falls back exactly as for a platform with no metadata."""
  130. fields: dict[str, Any] = {
  131. "name": plugin_entry.dashboard_label, "description": plugin_entry.dashboard_description,
  132. "docs_url": plugin_entry.docs_url,
  133. }
  134. if plugin_entry.dashboard_env_vars:
  135. fields["env_vars"] = plugin_entry.dashboard_env_vars
  136. if plugin_entry.dashboard_required_env is not None:
  137. fields["required_env"] = plugin_entry.dashboard_required_env
  138. return fields
  139. def _build_catalog_entry(platform_id: str, plugin_entry: Any | None = None) -> dict[str, Any]:
  140. override = _PLATFORM_OVERRIDES.get(platform_id) or (
  141. _plugin_card_fields(plugin_entry) if plugin_entry is not None else {})
  142. if "required_env" in override:
  143. required_env = tuple(override["required_env"])
  144. else:
  145. required_env = tuple(plugin_entry.required_env or ()) if plugin_entry is not None else ()
  146. plugin_label = plugin_entry.label if plugin_entry is not None else None
  147. plugin_hint = (plugin_entry.install_hint or "") if plugin_entry is not None else None
  148. return {
  149. "id": platform_id,
  150. "name": override.get("name") or plugin_label or platform_id.replace("_", " ").title(),
  151. "description": override.get("description") or plugin_hint or "",
  152. "docs_url": override.get("docs_url", ""),
  153. "env_vars": _merge_platform_env_vars(platform_id, override, plugin_entry),
  154. "required_env": required_env,
  155. }
  156. def _write_platform_enabled(platform_id: str, enabled: bool) -> None:
  157. write_platform_config_field(platform_id, "enabled", enabled)
  158. @dataclass
  159. class _WhatsAppOnboardingSession:
  160. proc: subprocess.Popen | None
  161. mode: str
  162. allowed_users: str
  163. session_path: str
  164. expires_at: str
  165. expires_at_ts: float
  166. profile: str | None = None
  167. status: str = "starting"
  168. qr_payload: str | None = None
  169. account_id: str | None = None
  170. account_name: str | None = None
  171. account_phone: str | None = None
  172. error: str | None = None
  173. starting_process: bool = False
  174. session_reserved: bool = False
  175. expiry_timer: threading.Timer | None = None
  176. _whatsapp_onboarding_sessions: dict[str, _WhatsAppOnboardingSession] = {}
  177. def _whatsapp_session_path() -> Path:
  178. from hermes_constants import get_hermes_dir
  179. return get_hermes_dir("platforms/whatsapp/session", "whatsapp/session")
  180. _WHATSAPP_PAYLOAD_FIELDS = (
  181. "status", "qr_payload", "expires_at", "mode", "allowed_users", "account_id", "account_name",
  182. "account_phone", "error",
  183. )
  184. def _whatsapp_onboarding_payload(pairing_id: str, record: _WhatsAppOnboardingSession) -> dict[str, Any]:
  185. return {"pairing_id": pairing_id, **{f: getattr(record, f) for f in _WHATSAPP_PAYLOAD_FIELDS}}
  186. def _restart_gateway_after_whatsapp_onboarding(profile: Optional[str] = None) -> dict[str, Any]:
  187. from hermes_cli.web_server_gateway import _restart_gateway_after
  188. return _restart_gateway_after(profile, what="WhatsApp onboarding", label="WhatsApp onboarding")
  189. _TELEGRAM_ONBOARDING_DEFAULT_URL = "https://setup.hermes-agent.nousresearch.com"
  190. @dataclass
  191. class _TelegramOnboardingPairing:
  192. poll_token: str
  193. expires_at: str
  194. expires_at_ts: float
  195. bot_token: str | None = None
  196. bot_username: str | None = None
  197. owner_user_id: str | None = None
  198. _telegram_onboarding_pairings: dict[str, _TelegramOnboardingPairing] = {}
  199. _telegram_onboarding_lock = threading.RLock()
  200. def _telegram_onboarding_base_url() -> str:
  201. return os.getenv("TELEGRAM_ONBOARDING_URL", _TELEGRAM_ONBOARDING_DEFAULT_URL).strip().rstrip("/")
  202. def _telegram_onboarding_error_message(error: str, fallback: str) -> str:
  203. return {
  204. "not_found": "Telegram pairing was not found. Start a new setup.",
  205. "expired": "Telegram setup expired. Start a new setup.",
  206. "claimed": "Telegram setup was already claimed. Start a new setup.",
  207. "unauthorized": "Telegram setup service rejected this request.",
  208. "telegram_manager_bot_token_not_configured": "Telegram setup service is not configured.",
  209. "telegram_token_fetch_failed": "Telegram could not finish bot setup. Try again.",
  210. }.get(error, fallback)
  211. _TELEGRAM_UNAVAILABLE = "Telegram setup service is unavailable. Try again shortly."
  212. _TELEGRAM_INVALID = "Telegram setup service returned an invalid response."
  213. def _telegram_onboarding_request_sync(
  214. method: str, path: str, *, body: dict[str, Any] | None = None, bearer_token: str | None = None
  215. ) -> dict[str, Any]:
  216. import httpx
  217. headers = {"Accept": "application/json", "User-Agent": hermes_user_agent("HermesDashboard")}
  218. request_kwargs: dict[str, Any] = {}
  219. if body is not None:
  220. headers["Content-Type"] = "application/json"
  221. request_kwargs["json"] = body
  222. if bearer_token:
  223. headers["Authorization"] = f"Bearer {bearer_token}"
  224. try:
  225. with httpx.Client(timeout=httpx.Timeout(10.0)) as client:
  226. response = client.request(method, f"{_telegram_onboarding_base_url()}{path}", headers=headers, **request_kwargs)
  227. response.raise_for_status()
  228. except httpx.HTTPStatusError as exc:
  229. try:
  230. parsed = exc.response.json()
  231. except Exception:
  232. parsed = {}
  233. error = str(parsed.get("error") or parsed.get("status") or "")
  234. detail = _telegram_onboarding_error_message(error, "Telegram setup service returned an error.")
  235. if error in {"expired", "claimed"}:
  236. status_code = 410
  237. else:
  238. status_code = 404 if exc.response.status_code == 404 else 502
  239. raise HTTPException(status_code=status_code, detail=detail) from exc
  240. except Exception as exc:
  241. raise HTTPException(status_code=502, detail=_TELEGRAM_UNAVAILABLE) from exc
  242. try:
  243. parsed = response.json()
  244. except Exception as exc:
  245. raise HTTPException(status_code=502, detail=_TELEGRAM_INVALID) from exc
  246. if not isinstance(parsed, dict):
  247. raise HTTPException(status_code=502, detail=_TELEGRAM_INVALID)
  248. return parsed