| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404 |
- """WhatsApp platform adapter (Baileys bridge): a Node.js bridge process runs the WhatsApp Web
- client; messages are polled over a local HTTP API and responses are posted back through it."""
- import asyncio
- import logging
- import mimetypes
- import os
- import platform
- import re
- import signal
- import subprocess
- from contextlib import suppress
- from functools import wraps
- from pathlib import Path
- from typing import Dict, Optional, Any
- from gateway.platforms._shared import (
- apply_yaml_bridge as _apply_yaml_bridge, extra_or_secret as _extra_or_secret, get_scoped_secret, send_error
- )
- from gateway.platforms.send_targets import StandaloneSendPolicy, regex_stripped_parser
- from hermes_cli._subprocess_compat import windows_detach_flags
- from hermes_cli.process_identity import release_process_group_once_empty, spawn_owned
- from hermes_constants import (find_node_executable, get_hermes_dir, with_hermes_node_path)
- _IS_WINDOWS = platform.system() == "Windows"
- def _wenv(name: str, default: str = "") -> str:
- """WHATSAPP_* env via the profile secret scope (multiplexed profiles see their own .env, not the process-global value)."""
- return get_scoped_secret(name, default)
- logger = logging.getLogger(__name__)
- # Owner-typed inbound text is prefixed at MessageEvent construction so transcripts stay disambiguated before silent_ingest.
- _OWNER_REPLY_PREFIX = "[owner reply] "
- _RUN_TEXT = dict(capture_output=True, text=True, encoding='utf-8', errors='replace', stdin=subprocess.DEVNULL)
- def _listener_pids_on_port(port: int) -> list:
- """PIDs *listening* on ``port`` (POSIX), never clients — a bare ``lsof -i :PORT`` once killed the user's browser."""
- pids: list = []
- with suppress(FileNotFoundError): # lsof not installed — fall through to ss
- pids = _safe_ints(subprocess.run(["lsof", "-ti", f"tcp:{port}", "-sTCP:LISTEN"], timeout=5, **_RUN_TEXT, check=False).stdout.strip().splitlines())
- if pids:
- return pids
- with suppress(FileNotFoundError):
- pids.extend(int(m.group(1)) for m in re.finditer(r"pid=(\d+)", subprocess.run(["ss", "-ltnHp", f"sport = :{port}"], timeout=5, **_RUN_TEXT, check=False).stdout))
- if pids:
- return pids
- # Neither lsof nor ss is installed (the repo image ships neither) — a silent empty scan here
- # meant _kill_port_process found nothing and the port race survived. psutil is a hard dependency.
- with suppress(Exception): # psutil missing, or net_connections denied: no evidence, no kill
- import psutil
- pids = [c.pid for c in psutil.net_connections(kind="tcp")
- if c.status == psutil.CONN_LISTEN and c.laddr and c.laddr.port == port and c.pid]
- return pids
- def _safe_ints(tokens) -> list:
- out: list = []
- for tok in tokens:
- try:
- out.append(int(tok))
- except ValueError:
- pass
- return out
- def _session_dir(extra) -> Path:
- """Absolute session dir: --session, bridge.pid and every /health ``session`` comparison (gateway and standalone
- sends) share this one string, or a gateway restarted from another cwd would see its own bridge as foreign."""
- return Path(os.path.abspath(os.path.expanduser(str((extra or {}).get(
- "session_path", get_hermes_dir("platforms/whatsapp/session", "whatsapp/session"))))))
- def _windows_listener_pids(port: int) -> list:
- """PIDs in LISTENING state on ``port`` via netstat (Windows)."""
- from hermes_cli._subprocess_compat import windows_hide_flags
- result = subprocess.run(["netstat", "-ano", "-p", "TCP"], timeout=5, creationflags=windows_hide_flags(), **_RUN_TEXT, check=False)
- rows = (line.split() for line in result.stdout.splitlines())
- return _safe_ints(p[4] for p in rows if len(p) >= 5 and p[3] == "LISTENING" and p[1].endswith(f":{port}"))
- def _port_listener_pids(port: int) -> list:
- """Listening PIDs on ``port`` for this platform: netstat on Windows, lsof/ss elsewhere."""
- return _windows_listener_pids(port) if _IS_WINDOWS else _listener_pids_on_port(port)
- def _pid_looks_like_node_bridge(pid: int) -> bool:
- """Fail-closed: the live process must be a ``node`` executable (a scan-time PID can be a stranger by kill time).
- ``_kill_port_process`` discovers PIDs from a netstat/lsof scan of a TCP port — a bare number naming a
- *stranger* process (#89614 class: an unverified scan-time PID force-killed later can be anything,
- including a critical system process). Before any kill, require the live process to actually look like
- our Baileys bridge: a ``node`` executable. Any ambiguity (process gone, unreadable cmdline) refuses the
- kill.
- """
- try:
- import psutil
- proc = psutil.Process(pid)
- return "node" in (proc.name() or "").lower() or "node" in " ".join(proc.cmdline() or []).lower().split(" ", 1)[0]
- except Exception:
- return False
- # SIGTERM is a request: the old bridge may take seconds to exit (or ignore it), and the next
- # spawn used to die on EADDRINUSE while the port was still bound. Grace before SIGKILL, and
- # how long connect() waits for the port to actually come free after a kill.
- _SIGTERM_GRACE_S = 5.0
- _BRIDGE_PORT_FREE_TIMEOUT_S = 10.0
- _SIGKILL = getattr(signal, "SIGKILL", signal.SIGTERM) # escalation paths below are POSIX-only
- def _pids_alive(pids: list) -> list:
- """The subset of *pids* still running. ``_pid_exists`` reports zombies dead (an exited but
- unreaped bridge holds no socket), and never sends a real signal on Windows."""
- from gateway.status import _pid_exists
- return [pid for pid in pids if _pid_exists(pid)]
- def _wait_pids_exit(pids: list, timeout: Optional[float] = None) -> list:
- """Poll until every pid in *pids* is gone (SIGTERM handlers get grace); returns the survivors."""
- import time
- if timeout is None:
- timeout = _SIGTERM_GRACE_S
- deadline = time.monotonic() + timeout
- alive = _pids_alive(pids)
- while alive and time.monotonic() < deadline:
- time.sleep(0.1)
- alive = _pids_alive(pids)
- return alive
- def _kill_port_process(port: int) -> None:
- """Kill any node bridge *listening* on the given TCP port (never a client); SIGTERM on POSIX with a
- bounded wait and SIGKILL escalation, taskkill /F (already immediate) on Windows."""
- signalled: list = []
- with suppress(Exception):
- for pid in _port_listener_pids(port):
- # Killing a mistyped or recycled PID is unrecoverable — verify first.
- if pid <= 0 or not _pid_looks_like_node_bridge(pid):
- logger.warning("[whatsapp] Not killing PID %s on port %d: process is not a node bridge (or identity unverifiable)", pid, port)
- continue
- if _IS_WINDOWS:
- from hermes_cli._subprocess_compat import windows_hide_flags
- # Only SubprocessError is swallowed per-PID; an OSError (e.g. taskkill missing) aborts the scan.
- with suppress(subprocess.SubprocessError):
- subprocess.run(["taskkill", "/PID", str(pid), "/F"], capture_output=True, stdin=subprocess.DEVNULL, timeout=5, creationflags=windows_hide_flags(), check=False)
- else:
- with suppress(OSError): # ProcessLookupError/PermissionError are OSError subclasses
- os.kill(pid, signal.SIGTERM)
- signalled.append(pid)
- if not signalled:
- return
- # SIGTERM is a request, not a fence: a slow-exiting bridge kept the port bound and the next
- # spawn died on EADDRINUSE. Wait for exit, then SIGKILL survivors — re-checking identity
- # first, so a PID recycled inside the grace window is never killed.
- survivors = _wait_pids_exit(signalled)
- for pid in survivors:
- if not _pid_looks_like_node_bridge(pid):
- logger.warning("[whatsapp] Not SIGKILLing PID %s on port %d: identity no longer verifiable", pid, port)
- continue
- with suppress(OSError):
- os.kill(pid, _SIGKILL)
- logger.warning("[whatsapp] SIGKILLed node bridge PID %d on port %d after it ignored SIGTERM", pid, port)
- _wait_pids_exit(survivors, timeout=1.0) # let SIGKILL land and the OS release the socket
- def _bridge_pid_is_ours(pid: int, expected_start) -> bool:
- """``pid`` alive AND still our bridge: kernel start time (definitive); fail closed without it.
- Legacy pidfiles record only the PID. The old fallback accepted a ``node`` + session-path cmdline
- substring as kill evidence — but a log tail, editor, or grep that merely *mentions* the session
- path matches that same substring (#116883), so a legacy pidfile could signal a stranger. Without
- a start-time fingerprint the caller must reap via the bridge-port scan instead.
- """
- from gateway import status
- if not status._pid_exists(pid):
- return False
- if expected_start is None:
- return False
- return status.get_process_start_time(pid) == expected_start
- def _unlink_quietly(path: Path) -> None:
- with suppress(OSError):
- path.unlink()
- def _read_bridge_pidfile(session_path: Path) -> tuple:
- """``(pid, kernel_start_time, port)`` from ``bridge.pid``; all ``None`` when absent or unparseable.
- Line 1 = pid, optional line 2 = kernel start time, optional line 3 = the ``--port`` it was spawned
- with (legacy files: pid only, or pid + start time)."""
- pid_file = session_path / "bridge.pid"
- if not pid_file.exists():
- return None, None, None
- try:
- lines = [ln.strip() for ln in pid_file.read_text(encoding="utf-8-sig").split("\n")]
- pid = int(lines[0])
- recorded_start = int(lines[1]) if len(lines) > 1 and lines[1] else None
- recorded_port = int(lines[2]) if len(lines) > 2 and lines[2] else None
- except (ValueError, OSError, TypeError, IndexError):
- return None, None, None
- return pid, recorded_start, recorded_port
- def _kill_stale_bridge_by_pidfile(session_path: Path) -> None:
- """Kill an orphaned bridge recorded in ``bridge.pid``, after :func:`_bridge_pid_is_ours`."""
- from gateway.status import _pid_exists
- pid_file = session_path / "bridge.pid"
- if not pid_file.exists():
- return
- pid, recorded_start, _ = _read_bridge_pidfile(session_path)
- if pid is None:
- _unlink_quietly(pid_file)
- return
- if _bridge_pid_is_ours(pid, recorded_start):
- with suppress(OSError): # ProcessLookupError / PermissionError included
- os.kill(pid, signal.SIGTERM)
- logger.info("[whatsapp] Killed stale bridge PID %d from pidfile", pid)
- if not _IS_WINDOWS:
- # SIGTERM is a request: a slow-exiting bridge kept the port bound and the next spawn hit
- # EADDRINUSE. Wait, then SIGKILL — re-checking identity first, so a PID recycled inside the
- # grace window is never signalled (the same fail-closed rule as the scan above).
- if _wait_pids_exit([pid]) and _bridge_pid_is_ours(pid, recorded_start):
- with suppress(OSError):
- os.kill(pid, _SIGKILL)
- logger.warning("[whatsapp] SIGKILLed stale bridge PID %d after it ignored SIGTERM", pid)
- # It may hold this session's WhatsApp socket on another port: let it die before a respawn.
- _wait_pids_exit([pid], timeout=1.0)
- elif _pid_exists(pid):
- reason = ("legacy pidfile lacks a start-time fingerprint and cmdline substring evidence can name a stranger"
- if recorded_start is None else "it is no longer the bridge (recycled onto an unrelated process)")
- logger.warning("[whatsapp] Not killing pidfile PID %d: %s; "
- "skipping to avoid killing a stranger.", pid, reason)
- _unlink_quietly(pid_file)
- def _write_bridge_pidfile(session_path: Path, pid: int, port: Optional[int] = None) -> None:
- """Write the bridge PID plus its kernel start time (line 2) for identity-checked cleanup, and the
- port it listens on (line 3) so a secondary adopts only the endpoint that process actually serves."""
- with suppress(OSError):
- from gateway.status import get_process_start_time
- start = get_process_start_time(pid)
- text = str(pid) if start is None else f"{pid}\n{start}" + ("" if port is None else f"\n{port}")
- (session_path / "bridge.pid").write_text(text, encoding="utf-8")
- def _spawn_bridge_process(argv: list, log_fh, env: dict) -> subprocess.Popen:
- """Start the Node bridge as an owned child. It leads its own session (so a container stop
- reaches it directly, #127047) and dies with this process however this process dies: a SIGKILLed
- or OOM-killed gateway no longer leaves its bridge serving the port and the WhatsApp session."""
- return spawn_owned(argv, purpose="whatsapp-bridge", stdin=subprocess.DEVNULL, stdout=log_fh,
- stderr=log_fh, env=env, creationflags=windows_detach_flags())
- def _terminate_bridge_process(proc, *, force: bool = False) -> None:
- """Terminate the bridge process using process-tree semantics where possible."""
- action = "kill" if force else "terminate"
- if _IS_WINDOWS:
- try:
- result = subprocess.run(
- ["taskkill", "/PID", str(proc.pid), "/T"] + (["/F"] if force else []),
- stdin=subprocess.DEVNULL, capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=10,
- check=False,
- )
- except FileNotFoundError:
- return getattr(proc, action)()
- if result.returncode != 0:
- raise OSError((result.stderr or result.stdout or "").strip() or f"taskkill failed for PID {proc.pid}")
- return
- import psutil
- with suppress(psutil.NoSuchProcess):
- parent = psutil.Process(proc.pid)
- for child in parent.children(recursive=True):
- with suppress(psutil.NoSuchProcess):
- getattr(child, action)()
- getattr(parent, action)()
- import sys
- sys.path.insert(0, str(Path(__file__).resolve().parents[3]))
- from gateway.config import Platform, PlatformConfig
- from gateway.platforms.whatsapp_common import WhatsAppBehaviorMixin
- from gateway.whatsapp_identity import normalize_whatsapp_mention_jid, to_whatsapp_jid
- from gateway.platforms.base import (
- BasePlatformAdapter, SendResult, SUPPORTED_DOCUMENT_TYPES, cache_image_from_url, cache_audio_from_url,
- )
- from gateway.platforms.helpers import cancel_task
- from gateway.platforms.event import MessageEvent, MessageType
- from utils import env_int
- def _cache_dirs() -> tuple:
- """``(image, audio, video, document)`` cache dirs, resolved per call so a profile override's cache matches."""
- from gateway.platforms.base import get_audio_cache_dir, get_document_cache_dir, get_image_cache_dir, get_video_cache_dir
- return get_image_cache_dir(), get_audio_cache_dir(), get_video_cache_dir(), get_document_cache_dir()
- def _is_allowed_bridge_path(url: str) -> bool:
- """Absolute bridge path resolves (symlinks included) inside a Hermes cache dir — a rogue bridge could hand back /etc/passwd."""
- try:
- resolved = Path(url).resolve()
- except (OSError, ValueError):
- return False
- for root in _cache_dirs():
- with suppress(OSError, ValueError):
- if resolved.is_relative_to(Path(root).resolve()):
- return True
- return False
- def _file_content_hash(path: Path) -> str:
- """First 16 hex chars of SHA-256 of *path* ("" if unreadable); bridge.js reports its own as ``/health`` ``scriptHash``."""
- import hashlib
- try:
- return hashlib.sha256(path.read_bytes()).hexdigest()[:16]
- except OSError:
- return ""
- def check_whatsapp_requirements() -> bool:
- """
- Check if WhatsApp dependencies are available.
- WhatsApp requires a Node.js bridge for most implementations.
- """
- _node = find_node_executable("node")
- if not _node:
- from pm import lazy_installs_allowed
- # Let connect prepare a missing runtime, but never install during discovery.
- return lazy_installs_allowed()
- try:
- return subprocess.run([_node, "--version"], timeout=5, env=with_hermes_node_path(), **_RUN_TEXT, check=False).returncode == 0
- except Exception:
- return False
- def _import_aiohttp():
- import aiohttp
- if not hasattr(aiohttp, "ClientSession"): # half-removed install leaves a namespace shell (#71308)
- where = getattr(aiohttp, "__file__", None) or list(getattr(aiohttp, "__path__", ())) # a plain aiohttp.py has no __path__
- raise ImportError(f"aiohttp at {where} is an incomplete install")
- return aiohttp
- def ensure_aiohttp() -> Optional[tuple[str, bool]]:
- """None once aiohttp imports (PM installs the ``sms`` extra, which is exactly aiohttp, when it is missing), else
- (why not, retryable).
- Every bridge call imports aiohttp; a sealed env without it used to fail each /health poll silently and loop
- forever on "did not start in 15s" while the bridge was healthy (#126358).
- """
- try:
- _import_aiohttp()
- return None
- except ImportError as exc:
- if not isinstance(exc, ModuleNotFoundError):
- return str(exc), False # present but broken: PM sees it as installed, reinstalling is the user's call
- from pm.environments import running_from_selected_environment
- from pm.environments_adopt import restart_needed
- from pm.extras import ensure_import
- from pm.install import lazy_installs_allowed
- from pm.paths import repo_root
- # Read before the sync moves the selection. A foreign interpreter (dev venv, Nix) can never lazy-install; one an
- # update left on an older generation can after a restart.
- root = repo_root()
- installable = lazy_installs_allowed() and (running_from_selected_environment(root) or restart_needed(root) is not None)
- try:
- ensure_import("sms")
- except (RuntimeError, OSError, ValueError) as exc: # InstallError/DownloadError; anything else escapes as transient
- # Only policy or a foreign interpreter is final. A busy dependency lock, a failed download and "installed;
- # restart Hermes to activate it" stay retryable: as final errors they exit the gateway 78 and keep it down.
- return str(exc) or type(exc).__name__, installable
- try:
- _import_aiohttp()
- return None
- except ImportError as exc:
- return f"{exc} after installing the sms extra", False
- # Env vars bridge.js consumes; injected because a multiplexed subprocess's os.environ lacks the secondary profile's .env.
- _BRIDGE_PASSTHROUGH_ENV = (
- "WHATSAPP_ALLOWED_USERS", "WHATSAPP_ALLOW_FROM", "WHATSAPP_DM_POLICY", "WHATSAPP_GROUP_POLICY",
- "WHATSAPP_GROUP_ALLOWED_USERS", "WHATSAPP_GROUP_ALLOW_FROM", "WHATSAPP_REQUIRE_MENTION",
- "WHATSAPP_MENTION_PATTERNS", "WHATSAPP_FREE_RESPONSE_CHATS", "WHATSAPP_DEBUG",
- "WHATSAPP_FORWARD_OWNER_MESSAGES", "WHATSAPP_MAX_MESSAGE_LENGTH",
- "WHATSAPP_CHUNK_DELAY_MS", "WHATSAPP_SEND_TIMEOUT_MS",
- )
- _TEXT_INJECT_EXTS = {".txt", ".md", ".csv", ".json", ".xml", ".yaml", ".yml", ".log", ".py", ".js", ".ts", ".html", ".css"}
- _MAX_TEXT_INJECT_BYTES = 100 * 1024 # matches Telegram/Discord/Slack
- _NATIVE_MEDIA_TYPES = {"location": MessageType.LOCATION, "live_location": MessageType.LOCATION, "sticker": MessageType.STICKER}
- # Inbound mediaType substring → kind; ptt = WhatsApp voice note, so "ptt" must precede "audio".
- _MEDIA_NEEDLES = (("image", MessageType.PHOTO), ("video", MessageType.VIDEO), ("ptt", MessageType.VOICE), ("audio", MessageType.AUDIO))
- # MessageType → (bridge label, default mime); documents take their mime from SUPPORTED_DOCUMENT_TYPES instead.
- _MEDIA_INFO = {
- MessageType.PHOTO: ("image", "image/jpeg"), MessageType.VOICE: ("audio", "audio/ogg"), MessageType.AUDIO: ("audio", "audio/mpeg"),
- MessageType.VIDEO: ("video", "video/mp4"), MessageType.DOCUMENT: ("document", ""),
- }
- _MEDIA_TYPE_BY_BRIDGE_KIND = {"image": MessageType.PHOTO, "video": MessageType.VIDEO, "audio": MessageType.VOICE, "document": MessageType.DOCUMENT}
- _QUOTED_MIME_BY_BRIDGE_KIND = {
- "image": "image/jpeg", "video": "video/mp4", "gif": "video/mp4", "audio": "audio/ogg", "ptt": "audio/ogg",
- "document": "application/octet-stream", "sticker": "image/webp",
- }
- def _needs_bridge(method):
- """Adapter-method decorator: return ``SendResult(error=...)`` when ``_bridge_unavailable()`` says so."""
- @wraps(method)
- async def _guarded(self, *args, **kwargs):
- unavailable = await self._bridge_unavailable()
- return SendResult(success=False, error=unavailable) if unavailable else await method(self, *args, **kwargs)
- return _guarded
- class WhatsAppAdapter(WhatsAppBehaviorMixin, BasePlatformAdapter):
- """Transport over a local Node.js (Baileys) HTTP bridge; behavior lives in ``WhatsAppBehaviorMixin``. config.extra: bridge_script /
- bridge_port (3000) / session_path, dm_policy / group_policy (open|allowlist|disabled|pairing), allow_from / group_allow_from, send_read_receipts."""
- _DEFAULT_BRIDGE_DIR = None # resolved in __init__
- splits_long_messages = True # send() chunks via truncate_message()
- serial_receive_loop = True # the bridge poll loop awaits each media message before the next
- def __init__(self, config: PlatformConfig):
- super().__init__(config, Platform.WHATSAPP)
- if WhatsAppAdapter._DEFAULT_BRIDGE_DIR is None:
- from gateway.platforms.whatsapp_common import resolve_whatsapp_bridge_dir
- WhatsAppAdapter._DEFAULT_BRIDGE_DIR = resolve_whatsapp_bridge_dir()
- extra = config.extra
- from hermes_constants import get_hermes_home
- self._profile_home = get_hermes_home()
- self._bridge_process: Optional[subprocess.Popen] = None
- self._foreign_bridge_session: Optional[str] = None # set by _reuse_running_bridge when /health names another profile's session
- self._bridge_probe_timed_out = False # set by _reuse_running_bridge when the port's holder gave no /health answer
- from .bridge_ownership import standalone_bridge_port
- try:
- # Same resolution as out-of-process sends, so a profile that recorded a port while serving as a
- # secondary keeps it when it launches; a secondary re-resolves (and may allocate) in connect().
- self._bridge_port: int = standalone_bridge_port(self._profile_home, extra.get("bridge_port"))
- except ValueError as exc:
- logger.warning("[whatsapp] %s; using port 3000", exc)
- self._bridge_port = 3000
- self._bridge_script: str = extra.get("bridge_script", str(self._DEFAULT_BRIDGE_DIR / "bridge.js"))
- self._session_path = _session_dir(extra)
- self._reply_prefix: Optional[str] = extra.get("reply_prefix")
- self._dm_policy = str(_extra_or_secret(extra, "dm_policy", "WHATSAPP_DM_POLICY", "pairing")).strip().lower()
- self._allow_from = self._coerce_allow_list(self._select_dm_allowlist(extra, ("WHATSAPP_ALLOWED_USERS",), _wenv))
- self._group_policy = str(_extra_or_secret(extra, "group_policy", "WHATSAPP_GROUP_POLICY", "pairing")).strip().lower()
- # Same precedence as the DM list. Until #72529 the env carrier only reached the Node bridge, so
- # env-only installs gated groups on an empty allowlist.
- _, raw_groups = self._select_allowlist(
- extra, ("group_allow_from", "groupAllowFrom"), ("WHATSAPP_GROUP_ALLOW_FROM", "WHATSAPP_GROUP_ALLOWED_USERS"), _wenv)
- self._group_allow_from = self._coerce_allow_list(raw_groups)
- rr = extra.get("send_read_receipts", False)
- self._send_read_receipts = rr if isinstance(rr, bool) else str(rr or "").strip().lower() in {"1", "true", "yes", "on"}
- self._mention_patterns = self._compile_mention_patterns()
- self._message_queue: asyncio.Queue = asyncio.Queue()
- self._bridge_log_fh = self._bridge_log = self._poll_task = self._http_session = None
- # Set by disconnect() before SIGTERMing so _check_managed_bridge_exit() can tell an intentional exit (-15/-2/0) from a crash.
- self._shutting_down = False
- # Text debounce batching: rapid bursts (forwards, paste-splits) would otherwise each trigger a separate agent turn.
- # Telegram cadence and ceilings (#44883); ``0`` dispatches each message immediately.
- self._configure_text_batch_delays()
- def _bridge_url(self, path: str) -> str:
- return f"http://127.0.0.1:{self._bridge_port}/{path}"
- def _bridge_req(self, method: str, path: str, timeout: float, **kwargs):
- """``session.<method>`` context manager for a bridge endpoint (caller must ``async with``)."""
- import aiohttp
- return getattr(self._http_session, method)(self._bridge_url(path), **kwargs, timeout=aiohttp.ClientTimeout(total=timeout))
- async def _probe_bridge_health(self) -> tuple[bool, Any]:
- """GET /health with a fresh session → ``(http_200, json)``; unparseable 200 body → ``(True, None)``; connection errors and timeouts propagate."""
- import aiohttp
- async with aiohttp.ClientSession() as session, session.get(self._bridge_url("health"), timeout=aiohttp.ClientTimeout(total=2)) as resp:
- if resp.status != 200:
- return False, None
- try:
- return True, await resp.json()
- except TimeoutError:
- raise # a body that never arrives is no answer, the same as headers that never arrive
- except Exception:
- return True, None
- def _ensure_bridge_deps(self, bridge_dir: Path) -> bool:
- """npm install when node_modules is missing OR package.json hash != stamp file. False = fatal error set."""
- _dep_stamp = bridge_dir / "node_modules" / ".hermes-pkg-hash" # holds the package.json hash of the last install
- _pkg_hash = _file_content_hash(bridge_dir / "package.json")
- try:
- if (bridge_dir / "node_modules").exists() and _dep_stamp.read_text(encoding="utf-8-sig").strip() == _pkg_hash and bool(_pkg_hash):
- return True
- except OSError:
- pass
- print(f"[{self.name}] Installing WhatsApp bridge dependencies...")
- detail = ""
- try: # Default 300s accommodates slow systems like an Unraid NAS.
- import pm
- _npm_bin = find_node_executable("npm")
- env = with_hermes_node_path()
- if _npm_bin is None:
- env = pm.ensure("npm").env
- installed = pm.installed_package("npm")
- if installed is None or installed.binary is None:
- raise pm.InstallError("npm", "ensured but no selected binary was recorded")
- _npm_bin = str(installed.binary)
- install_result = subprocess.run([_npm_bin, "install", "--silent"], cwd=str(bridge_dir), timeout=env_int("WHATSAPP_NPM_INSTALL_TIMEOUT", 300),
- env=env, **_RUN_TEXT, check=False)
- if install_result.returncode == 0:
- print(f"[{self.name}] Dependencies installed")
- with suppress(OSError): # Stamp is an optimization; install still succeeded
- if _pkg_hash:
- _dep_stamp.write_text(_pkg_hash, encoding="utf-8")
- return True
- print(f"[{self.name}] npm install failed: {install_result.stderr}")
- detail = f" ({install_result.stderr.strip()[-500:]})" if install_result.stderr else ""
- except Exception as e:
- print(f"[{self.name}] Failed to install dependencies: {e}")
- detail = f" ({e})"
- self._set_fatal_error("whatsapp_npm_install_failed", f"WhatsApp bridge npm install failed{detail}. "
- "Run `hermes whatsapp`, then restart `hermes gateway`.", retryable=False)
- return False
- def _attach_to_bridge(self, managed_process) -> None:
- import aiohttp
- self._bridge_process = managed_process
- self._http_session = aiohttp.ClientSession()
- self._poll_task = asyncio.create_task(self._poll_messages())
- async def _reuse_running_bridge(self, bridge_path: Path) -> bool:
- """Adopt a connected bridge serving the on-disk bridge.js + same read-receipt config; else say why it restarts."""
- self._foreign_bridge_session = None
- self._bridge_probe_timed_out = False
- try:
- ok, data = await self._probe_bridge_health()
- if not ok or data is None:
- return False
- # Another profile's bridge (same default port) is neither adopted, which would answer as that
- # profile's phone, nor killed: connect() reports it. Checked before status because a bridge in
- # startup, reconnect or QR wait reports "disconnected". A bridge without ``session`` predates the
- # field, so its scriptHash no longer matches bridge.js and it restarts as stale below.
- reported_session = data.get("session")
- if reported_session and reported_session != str(self._session_path):
- self._foreign_bridge_session = reported_session
- return False
- bridge_status = data.get("status", "unknown")
- if bridge_status != "connected":
- print(f"[{self.name}] Bridge found but not connected (status: {bridge_status}), restarting")
- return False
- running_hash, disk_hash = data.get("scriptHash", ""), _file_content_hash(bridge_path)
- if running_hash and disk_hash and running_hash == disk_hash and bool(data.get("sendReadReceipts", False)) == self._send_read_receipts:
- print(f"[{self.name}] Using existing bridge (status: {bridge_status})")
- self._mark_connected()
- self._attach_to_bridge(None) # Not managed by us
- self._wire_plugin_handlers(None)
- return True
- stale_reason = f"running={running_hash or 'unversioned'}, disk={disk_hash}" if running_hash != disk_hash else "send_read_receipts config changed"
- print(f"[{self.name}] Running bridge is stale ({stale_reason}), restarting")
- except TimeoutError:
- self._bridge_probe_timed_out = True # something holds the port but gave no identity; connect() leaves it
- except Exception:
- pass # Bridge not running, start a new one
- return False
- def _bridge_env(self) -> dict:
- """Subprocess env: the adapter's EFFECTIVE profile policy + profile-resolved WHATSAPP_* values + cache dirs."""
- # with_hermes_node_path() copies os.environ when called with no arg: under a multiplexed secondary
- # that copy carries the DEFAULT profile's WHATSAPP_* values, so every bridge-consumed key is
- # re-resolved from this profile (dropped on a scoped miss), never inherited from the launch env.
- bridge_env = with_hermes_node_path()
- reply_prefix = _wenv("WHATSAPP_REPLY_PREFIX")
- if reply_prefix:
- bridge_env["WHATSAPP_REPLY_PREFIX"] = reply_prefix
- elif self._reply_prefix is not None:
- bridge_env["WHATSAPP_REPLY_PREFIX"] = self._reply_prefix
- else:
- bridge_env.pop("WHATSAPP_REPLY_PREFIX", None)
- bridge_env["WHATSAPP_SEND_READ_RECEIPTS"] = "true" if self._send_read_receipts else "false"
- for _key, _v in [("WHATSAPP_MODE", _wenv("WHATSAPP_MODE", "self-chat"))] + [(k, _wenv(k)) for k in _BRIDGE_PASSTHROUGH_ENV]:
- if _v:
- bridge_env[_key] = _v
- else:
- bridge_env.pop(_key, None)
- # bridge.js gates DMs BEFORE Python sees them: it must run the same dm_policy / allow_from the
- # adapter resolved (scoped env → this profile's YAML → default), or a secondary's YAML
- # ``dm_policy: pairing`` runs under the default profile's allowlist and drops valid pairing DMs.
- bridge_env["WHATSAPP_DM_POLICY"] = self._dm_policy
- bridge_env["WHATSAPP_GROUP_POLICY"] = self._group_policy
- for env_key, ids in (("WHATSAPP_ALLOWED_USERS", self._allow_from), ("WHATSAPP_GROUP_ALLOWED_USERS", self._group_allow_from)):
- if ids:
- bridge_env[env_key] = ",".join(sorted(ids))
- else:
- bridge_env.pop(env_key, None)
- # Without these the bridge hardcodes ~/.hermes/{image,audio,document}_cache (wrong under HERMES_HOME/profiles/cache layout).
- img_dir, audio_dir, _video_dir, doc_dir = _cache_dirs()
- bridge_env.update(HERMES_IMAGE_CACHE_DIR=str(img_dir), HERMES_AUDIO_CACHE_DIR=str(audio_dir), HERMES_DOCUMENT_CACHE_DIR=str(doc_dir))
- return bridge_env
- def _bridge_died(self, detail: str, code: str = "whatsapp_bridge_exited") -> bool:
- print(f"[{self.name}] {detail}")
- print(f"[{self.name}] Check log: {self._bridge_log}")
- self._close_bridge_log()
- # Named so the reconnect status and connect telemetry say why instead of an unclassified failure.
- self._set_fatal_error(code, f"{detail} (see {self._bridge_log})", retryable=True)
- return False
- async def _poll_bridge_health(self, died_msg: str) -> tuple[Optional[bool], bool, dict]:
- """Poll /health up to 15×1s → ``(connected, http_ready, data)``; connected False = process died (reported), None = timeout."""
- http_ready = False
- data: dict = {}
- for attempt in range(15):
- await asyncio.sleep(1)
- if self._bridge_process.poll() is not None:
- # bridge.pid must not name a dead PID: the next connect()'s pidfile reap would find
- # nothing there while the real port holder (if any) survives its port scan.
- _unlink_quietly(self._session_path / "bridge.pid")
- return self._bridge_died(died_msg.format(code=self._bridge_process.returncode)), http_ready, data
- try:
- ok, d = await self._probe_bridge_health()
- if ok:
- http_ready = True
- if d is not None:
- data = d
- if data.get("status") == "connected":
- print(f"[{self.name}] Bridge ready (status: connected)")
- return True, http_ready, data
- except Exception:
- continue
- return None, http_ready, data
- async def _wait_for_bridge(self) -> bool:
- """Phase 1: HTTP up (≤15s). Phase 2: ``status: connected`` (≤15s more; warns but proceeds if still connecting)."""
- connected, http_ready, data = await self._poll_bridge_health("Bridge process died (exit code {code})")
- if connected is False:
- return False
- if not http_ready:
- return self._bridge_died("Bridge HTTP server did not start in 15s", "whatsapp_bridge_timeout")
- if data.get("status") != "connected":
- print(f"[{self.name}] Bridge HTTP ready, waiting for WhatsApp connection...")
- connected, _, _ = await self._poll_bridge_health("Bridge process died during connection")
- if connected is False:
- return False
- if connected is None:
- print(f"[{self.name}] ⚠ WhatsApp not connected after 30s")
- print(f"[{self.name}] Bridge log: {self._bridge_log}")
- print(f"[{self.name}] If session expired, re-pair: hermes whatsapp")
- return True
- def _preflight(self) -> bool:
- """Node + bridge script + creds.json + aiohttp present, else a named fatal error (an unpaired bridge only prints QR codes; retries would pay 30s each)."""
- bridge_path = Path(self._bridge_script)
- creds_path = self._session_path / "creds.json"
- checks = (
- (check_whatsapp_requirements, ("[%s] Node.js not found. WhatsApp requires Node.js.", self.name),
- "whatsapp_node_missing", "Node.js is not installed — install Node.js and re-run `hermes gateway`."),
- (bridge_path.exists, ("[%s] Bridge script not found: %s", self.name, bridge_path),
- "whatsapp_bridge_missing", f"WhatsApp bridge script missing at {bridge_path}."),
- (creds_path.exists, ("[%s] WhatsApp is enabled but not paired (no creds.json at %s). Pair from the dashboard or run "
- "`hermes whatsapp`; remove WHATSAPP_ENABLED from your .env to disable.", self.name, creds_path),
- "whatsapp_not_paired", "WhatsApp enabled but not paired — pair from the dashboard or run `hermes whatsapp`."),
- )
- for ok, warn_args, code, message in checks:
- if not ok():
- logger.warning(*warn_args)
- self._set_fatal_error(code, message, retryable=False)
- return False
- if (missing := ensure_aiohttp()) is not None: # may install it: connect runs this off the event loop
- why, retryable = missing
- message = (f"aiohttp is unavailable ({why}); the WhatsApp bridge client needs it. "
- "Run `hermes pm install --extra sms` (it ships aiohttp; `hermes pm repair` for a damaged install), "
- "then restart `hermes gateway`.")
- logger.warning("[%s] %s", self.name, message)
- self._set_fatal_error("whatsapp_aiohttp_missing", message, retryable=retryable)
- return False
- logger.info("[%s] Bridge found at %s", self.name, bridge_path)
- return True
- async def connect(self, *, is_reconnect: bool = False) -> bool:
- """Start (or adopt) the Node.js bridge and wait for it to be ready."""
- if find_node_executable("node") is None:
- import pm
- try:
- await asyncio.to_thread(pm.ensure, "node")
- except pm.InstallError as exc:
- self._set_fatal_error("whatsapp_node_missing", str(exc), retryable=False)
- return False
- secondary = bool(getattr(self, "_runtime_status_platform_key", ""))
- prior_bridge_is_ours = False
- if secondary:
- from .bridge_ownership import secondary_bridge_port, check_secondary_ownership
- try:
- self._bridge_port = secondary_bridge_port(self._profile_home, self.config.extra.get("bridge_port"))
- prior_bridge_is_ours = check_secondary_ownership(self._session_path, self._bridge_port) == "ours"
- except (OSError, ValueError) as exc:
- self._set_fatal_error(
- "whatsapp_bridge_conflict",
- f"{exc}. Set platforms.whatsapp.extra.bridge_port to a distinct free port; "
- "or stop the process holding it.", retryable=False)
- return False
- if not await asyncio.to_thread(self._preflight):
- return False
- bridge_path = Path(self._bridge_script)
- lock_acquired = False
- try:
- if not self._acquire_platform_lock('whatsapp-session', str(self._session_path), 'WhatsApp session'):
- return False
- lock_acquired = True
- except Exception as e:
- logger.warning("[%s] Could not acquire session lock (non-fatal): %s", self.name, e)
- try:
- if not self._ensure_bridge_deps(bridge_path.parent):
- return False
- self._session_path.mkdir(parents=True, exist_ok=True)
- # A secondary adopts or reaps only a bridge its own pidfile identifies; the default keeps
- # its historical adopt-or-clear-the-port path. A bridge this version started dies with
- # its gateway (spawn_owned), so what is adopted here is one a pre-update gateway or
- # another process left running; credentials are on disk, so a fresh bridge needs no re-pair.
- if (not secondary or prior_bridge_is_ours) and await self._reuse_running_bridge(bridge_path):
- return True
- if self._foreign_bridge_session:
- # The port is served by another profile's bridge. Never adopt
- # it and never kill it: it belongs to a live session.
- foreign = self._foreign_bridge_session
- self._set_fatal_error(
- "whatsapp_bridge_foreign_session",
- f"Port {self._bridge_port} is already served by a WhatsApp bridge for a different session "
- f"({foreign}). Give this profile its own port via platforms.whatsapp.extra.bridge_port "
- f"(one distinct bridge_port per profile); nothing on port {self._bridge_port} was stopped.",
- retryable=False,
- )
- return False
- # The reaps below block for up to their SIGTERM grace each; off the loop so every other
- # platform on this gateway keeps running while a slow bridge exits.
- if not secondary or prior_bridge_is_ours:
- await asyncio.to_thread(_kill_stale_bridge_by_pidfile, self._session_path)
- if not secondary:
- if self._bridge_probe_timed_out:
- # No /health answer is no ownership evidence (another profile's busy bridge looks the same), and
- # our own stale bridge was just reaped by its pidfile: a holder that remains is left running.
- await asyncio.sleep(1)
- try:
- held = bool(_port_listener_pids(self._bridge_port))
- except Exception:
- held = True # listeners could not be listed: still no evidence to kill on
- if held:
- self._set_fatal_error(
- "whatsapp_bridge_unresponsive",
- f"Port {self._bridge_port} is held by a process that did not answer /health in time, so "
- f"Hermes cannot tell whose WhatsApp bridge it is; nothing on port {self._bridge_port} was "
- "stopped. Stop that process, or give this profile its own port via "
- "platforms.whatsapp.extra.bridge_port.",
- retryable=True,
- )
- return False
- await asyncio.to_thread(_kill_port_process, self._bridge_port)
- # The kills above return after SIGTERM (or SIGKILL past the grace); a slow-exiting bridge could still
- # hold the port, and the blind sleep that used to sit here spawned onto it — EADDRINUSE, retried forever.
- # A secondary that skipped the kills found the port free, so this returns at once on that path.
- if not await self._wait_bridge_port_free():
- return False
- # Bridge output goes to a log file so QR codes, errors, and reconnection messages survive for troubleshooting.
- self._bridge_log = self._session_path.parent / "bridge.log"
- self._bridge_log_fh = bridge_log_fh = open(self._bridge_log, "a", encoding="utf-8") # noqa: ASYNC230 -- long-lived log handle handed to the bridge subprocess
- node = find_node_executable("node")
- if node is None:
- raise RuntimeError("Node.js is no longer available; run `hermes pm install`")
- self._bridge_process = _spawn_bridge_process(
- [node, str(bridge_path), "--port", str(self._bridge_port), "--session", str(self._session_path),
- "--mode", _wenv("WHATSAPP_MODE", "self-chat")], bridge_log_fh, self._bridge_env())
- _write_bridge_pidfile(self._session_path, self._bridge_process.pid, self._bridge_port)
- if not await self._wait_for_bridge():
- return False
- self._attach_to_bridge(self._bridge_process)
- self._mark_connected()
- print(f"[{self.name}] Bridge started on port {self._bridge_port}")
- self._wire_plugin_handlers(None)
- return True
- except Exception as e:
- logger.error("[%s] Failed to start bridge: %s", self.name, e, exc_info=True)
- return False
- finally:
- if not self._running:
- if lock_acquired:
- self._release_platform_lock()
- self._close_bridge_log()
- def _close_bridge_log(self) -> None:
- if self._bridge_log_fh:
- with suppress(Exception):
- self._bridge_log_fh.close()
- self._bridge_log_fh = None
- async def _wait_bridge_port_free(self) -> bool:
- """Bounded wait for the just-stopped bridge to release its port (``port_is_free`` probes with the
- bridge's own SO_REUSEADDR bind semantics, so TIME-WAIT alone never blocks); False with a named fatal
- when a live listener still holds it — spawning onto a busy port only bought an EADDRINUSE crash-loop."""
- import time
- from .bridge_ownership import port_is_free
- deadline = time.monotonic() + _BRIDGE_PORT_FREE_TIMEOUT_S
- while not port_is_free(self._bridge_port):
- if time.monotonic() >= deadline:
- holders: list = []
- with suppress(Exception):
- holders = _port_listener_pids(self._bridge_port)
- self._set_fatal_error(
- "whatsapp_bridge_port_busy",
- f"Port {self._bridge_port} is still held by PID(s) {holders or 'unknown'} after the previous "
- f"bridge was stopped and {_BRIDGE_PORT_FREE_TIMEOUT_S:.0f}s of waiting; no new bridge was spawned. "
- "Stop the holder, or set platforms.whatsapp.extra.bridge_port to a free port.",
- retryable=True,
- )
- return False
- await asyncio.sleep(0.2)
- return True
- async def _check_managed_bridge_exit(self) -> Optional[str]:
- returncode = self._bridge_process.poll() if self._bridge_process is not None else None
- if returncode is None:
- return None
- # getattr-with-default: tests build the adapter via ``__new__`` without __init__.
- # A container stop (e.g. s6-overlay's stage-3 broadcast) reaches the bridge child (its own session) before the
- # gateway's stop flow reaches this adapter's disconnect(), so ``_shutting_down`` alone
- # misses that window and a normal -15/-2 exit reads as a fatal crash (#127047). The
- # runner flips ``_stop_requested_by_signal`` in its signal handler — the first thing
- # that runs on any signal-driven stop — so consult it too. Un-guarded it stays fatal:
- # a bridge killed while the gateway keeps running still needs the reconnect watcher.
- runner_stop = getattr(getattr(self, "gateway_runner", None), "_stop_requested_by_signal", False)
- if (getattr(self, "_shutting_down", False) or runner_stop) and returncode in {0, -2, -15}:
- logger.info("[%s] Bridge exited during shutdown (code %d).", self.name, returncode)
- return None
- message = f"WhatsApp bridge process exited unexpectedly (code {returncode})."
- if not self.has_fatal_error:
- logger.error("[%s] %s", self.name, message)
- self._set_fatal_error("whatsapp_bridge_exited", message, retryable=True)
- self._close_bridge_log()
- await self._notify_fatal_error()
- return self.fatal_error_message or message
- def _terminate_bridge(self, *, force: bool) -> None:
- try:
- _terminate_bridge_process(self._bridge_process, force=force)
- except (ProcessLookupError, PermissionError):
- getattr(self._bridge_process, "kill" if force else "terminate")()
- async def disconnect(self) -> None:
- """Stop the WhatsApp bridge and clean up any orphaned processes."""
- self._shutting_down = True # flip BEFORE signalling so send()/poll loop don't report the intentional exit as fatal
- if not self._bridge_process:
- print(f"[{self.name}] Disconnecting (external bridge left running)")
- else:
- try:
- self._terminate_bridge(force=False)
- await asyncio.sleep(1)
- if self._bridge_process.poll() is None:
- self._terminate_bridge(force=True)
- # SIGKILL/taskkill /F still takes a moment to be visible to poll(): an in-process
- # restart that spawned immediately after raced the dying bridge for the port.
- with suppress(subprocess.TimeoutExpired):
- await asyncio.to_thread(self._bridge_process.wait, _SIGTERM_GRACE_S)
- except Exception as e:
- print(f"[{self.name}] Error stopping bridge: {e}")
- if not _IS_WINDOWS and self._bridge_process.poll() is not None:
- # Stopped by us; a bridge we failed to stop stays covered by the owner-death supervisor.
- # (POSIX only: Windows has no supervised group, and its stop path stays as on main.)
- release_process_group_once_empty(self._bridge_process.pid, timeout=0)
- if self._bridge_process or not getattr(self, "_runtime_status_platform_key", ""):
- _unlink_quietly(self._session_path / "bridge.pid")
- await cancel_task(self._poll_task)
- if self._http_session and not self._http_session.closed:
- await self._http_session.close()
- self._poll_task = self._http_session = self._bridge_process = None
- self._release_platform_lock()
- self._mark_disconnected()
- self._close_bridge_log()
- print(f"[{self.name}] Disconnected")
- async def _bridge_unavailable(self) -> Optional[str]:
- return "Not connected" if not self._running or not self._http_session else (await self._check_managed_bridge_exit() or None)
- async def _post_bridge_message(self, path: str, payload: dict[str, Any], *, timeout: float) -> SendResult:
- """POST to the bridge; 200 → SendResult(messageId, raw_response), else the error text."""
- try:
- async with self._bridge_req("post", path, timeout, json=payload) as resp:
- if resp.status == 200:
- data = await resp.json()
- return SendResult(success=True, message_id=data.get("messageId"), raw_response=data)
- return SendResult(success=False, error=await resp.text())
- except Exception as e:
- return SendResult(success=False, error=str(e))
- @_needs_bridge
- async def send(self, chat_id: str, content: str, reply_to: Optional[str] = None, metadata: Optional[dict[str, Any]] = None) -> SendResult:
- """Format markdown for WhatsApp, chunk preserving code blocks, send sequentially."""
- if not content or not content.strip():
- return SendResult(success=True, message_id=None)
- chat_id = to_whatsapp_jid(chat_id)
- try:
- chunks = self.truncate_message(self.format_message(content), self._outgoing_chunk_limit())
- sent_message_ids: list[str] = []
- last_message_id = None
- for idx, chunk in enumerate(chunks):
- payload: dict[str, Any] = {"chatId": chat_id, "message": chunk}
- if reply_to and idx == 0:
- payload["replyTo"] = reply_to # Reply-to on the first chunk only.
- result = await self._post_bridge_message("send", payload, timeout=30)
- if not result.success:
- return SendResult(success=False, error=result.error)
- last_message_id = result.message_id
- if last_message_id:
- sent_message_ids.append(str(last_message_id))
- if len(chunks) > 1:
- await asyncio.sleep(0.3) # avoid rate limiting between chunks
- return SendResult(success=True, message_id=last_message_id, continuation_message_ids=tuple(sent_message_ids[:-1]),
- raw_response={"message_ids": sent_message_ids})
- except Exception as e:
- return SendResult(success=False, error=str(e))
- @_needs_bridge
- async def edit_message(self, chat_id: str, message_id: str, content: str, *, finalize: bool = False) -> SendResult:
- try:
- async with self._bridge_req("post", "edit", 15, json={"chatId": to_whatsapp_jid(chat_id), "messageId": message_id, "message": content}) as resp:
- return SendResult(success=True, message_id=message_id) if resp.status == 200 else SendResult(success=False, error=await resp.text())
- except Exception as e:
- return SendResult(success=False, error=str(e))
- @_needs_bridge
- async def _send_media_to_bridge(self, chat_id: str, file_path: str, media_type: str, caption: Optional[str] = None, file_name: Optional[str] = None) -> SendResult:
- if not os.path.exists(file_path):
- return SendResult(success=False, error=f"File not found: {file_path}")
- jid = to_whatsapp_jid(chat_id)
- payload: dict[str, Any] = {"chatId": jid, "filePath": file_path, "mediaType": media_type}
- payload.update({k: v for k, v in (("caption", caption), ("fileName", file_name)) if v})
- result = await self._post_bridge_message("send-media", payload, timeout=120)
- if result.success and result.message_id:
- # A later quote of this attachment carries only a thumbnail stub; the bridge's cache
- # knows inbound media only, so index our own sends (the cron-delivered image case).
- from gateway import rich_sent_store
- mime = mimetypes.guess_type(file_path)[0] or _MEDIA_INFO.get(_MEDIA_TYPE_BY_BRIDGE_KIND.get(media_type), ("", ""))[1]
- await rich_sent_store.record_media_async(jid, result.message_id, [(file_path, mime or "application/octet-stream")])
- return result
- @_needs_bridge
- async def send_poll(self, chat_id: str, question: str, options: list[str], *, selectable_count: int = 1) -> SendResult:
- """Native WhatsApp poll (low-level transport primitive; approval UX stays gateway-owned)."""
- payload: dict[str, Any] = {"chatId": to_whatsapp_jid(chat_id), "question": question, "options": list(options or []), "selectableCount": selectable_count}
- return await self._post_bridge_message("send-poll", payload, timeout=30)
- async def send_clarify(self, chat_id: str, question: str, choices: Optional[list], clarify_id: str, session_key: str,
- metadata: Optional[dict[str, Any]] = None) -> SendResult:
- """Multiple-choice clarify as a native poll (the pick arrives as message text for the normal intercept); else text prompt."""
- clean_choices = [str(choice).strip() for choice in (choices or []) if str(choice).strip()]
- if 2 <= len(clean_choices) <= 12:
- result = await self.send_poll(chat_id, str(question or "").strip(), clean_choices, selectable_count=1)
- if result.success:
- return result
- logger.warning("[%s] Native WhatsApp clarify poll failed; falling back to text: %s", self.name, result.error)
- return await super().send_clarify(chat_id=chat_id, question=question, choices=choices, clarify_id=clarify_id, session_key=session_key, metadata=metadata)
- @_needs_bridge
- async def send_location(self, chat_id: str, latitude: float, longitude: float, *, name: Optional[str] = None, address: Optional[str] = None,
- reply_to: Optional[str] = None, metadata: Optional[dict[str, Any]] = None) -> SendResult:
- try:
- payload: dict[str, Any] = {"chatId": to_whatsapp_jid(chat_id), "latitude": float(latitude), "longitude": float(longitude)}
- except Exception as e:
- return SendResult(success=False, error=str(e))
- payload.update({k: v for k, v in (("name", name), ("address", address)) if v})
- return await self._post_bridge_message("send-location", payload, timeout=30)
- async def send_image(self, chat_id: str, image_url: str, caption: Optional[str] = None, reply_to: Optional[str] = None,
- metadata: Optional[dict[str, Any]] = None) -> SendResult:
- """Download image URL to cache, send natively via bridge (``metadata`` honors the base contract)."""
- try:
- local_path = await cache_image_from_url(image_url)
- return await self._send_media_to_bridge(chat_id, local_path, "image", caption)
- except Exception:
- return await super().send_image(chat_id, image_url, caption, reply_to, metadata)
- async def send_image_file(self, chat_id: str, image_path: str, caption: Optional[str] = None, reply_to: Optional[str] = None, **kwargs) -> SendResult:
- return await self._send_media_to_bridge(chat_id, image_path, "image", caption)
- async def send_video(self, chat_id: str, video_path: str, caption: Optional[str] = None, reply_to: Optional[str] = None, **kwargs) -> SendResult:
- return await self._send_media_to_bridge(chat_id, video_path, "video", caption)
- async def send_voice(self, chat_id: str, audio_path: str, caption: Optional[str] = None, reply_to: Optional[str] = None,
- is_voice: Optional[bool] = None, **kwargs) -> SendResult:
- # The bridge turns every "audio" send into a voice note (ptt, transcoded to Opus); a plain
- # audio MEDIA file (is_voice=False: music, a sound effect) goes as a named document instead.
- if is_voice is False:
- return await self.send_document(chat_id, audio_path, caption=caption, reply_to=reply_to)
- return await self._send_media_to_bridge(chat_id, audio_path, "audio", caption)
- async def send_document(self, chat_id: str, file_path: str, caption: Optional[str] = None, file_name: Optional[str] = None,
- reply_to: Optional[str] = None, **kwargs) -> SendResult:
- return await self._send_media_to_bridge(chat_id, file_path, "document", caption, file_name or os.path.basename(file_path))
- async def send_typing(self, chat_id: str, metadata=None) -> None:
- if await self._bridge_unavailable():
- return
- with suppress(Exception):
- import aiohttp
- # ``async with`` — a bare ``await session.post(...)`` leaves the response (and its CLOSE_WAIT socket) alive until GC.
- async with self._http_session.post(self._bridge_url("typing"), json={"chatId": to_whatsapp_jid(chat_id)}, timeout=aiohttp.ClientTimeout(total=5)):
- pass
- async def get_chat_info(self, chat_id: str) -> dict[str, Any]:
- if not self._running or not self._http_session:
- return {"name": "Unknown", "type": "dm"}
- if not await self._check_managed_bridge_exit():
- try:
- async with self._bridge_req("get", f"chat/{to_whatsapp_jid(chat_id)}", 10) as resp:
- if resp.status == 200:
- data = await resp.json()
- return {"name": data.get("name", chat_id), "type": "group" if data.get("isGroup") else "dm", "participants": data.get("participants", [])}
- except Exception as e:
- logger.debug("Could not get WhatsApp chat info for %s: %s", chat_id, e)
- return {"name": chat_id, "type": "dm"}
- async def _report_bridge_exit(self) -> bool:
- bridge_exit = await self._check_managed_bridge_exit()
- if bridge_exit:
- print(f"[{self.name}] {bridge_exit}")
- return bool(bridge_exit)
- async def _poll_messages(self) -> None:
- while self._running:
- if not self._http_session or await self._report_bridge_exit():
- break
- try:
- async with self._bridge_req("get", "messages", 30) as resp:
- if resp.status == 200:
- for msg_data in await resp.json():
- if msg_data.get("event") == "delivery_status":
- self._log_delivery_status(msg_data)
- continue
- event = await self._build_message_event(msg_data)
- if event:
- # Fire-and-forget: a slow bridge /read must not delay dispatch.
- asyncio.create_task(self._send_read_receipt(msg_data))
- if event.message_type == MessageType.TEXT:
- self._enqueue_text_event(event)
- else:
- await self.handle_message(event)
- except asyncio.CancelledError:
- break
- except Exception as e:
- if await self._report_bridge_exit():
- break
- print(f"[{self.name}] Poll error: {e}")
- await asyncio.sleep(5)
- await asyncio.sleep(1) # Poll interval
- def _log_delivery_status(self, data: dict[str, Any]) -> None:
- """One gateway.log line per delivery/read status change of a message Hermes sent (Baileys
- ``messages.update`` for DMs, ``message-receipt.update`` per recipient in groups)."""
- logger.info(
- "[%s] WhatsApp delivery status: message=%s chat=%s status=%s%s at=%s%s", self.name,
- data.get("messageId"), data.get("chatId"), data.get("status"),
- f" recipient={data['recipientId']}" if data.get("recipientId") else "", data.get("timestamp"),
- f" error={data['error']}" if data.get("error") else "",
- )
- async def _send_read_receipt(self, data: dict[str, Any]) -> None:
- key = data.get("readReceiptKey")
- if not self._send_read_receipts or not self._http_session or not isinstance(key, dict):
- return
- try:
- async with self._bridge_req("post", "read", 5, json={"key": key}) as resp:
- if resp.status != 200:
- logger.warning("[%s] WhatsApp read receipt failed with HTTP %s", self.name, resp.status)
- except Exception as exc:
- logger.warning("[%s] WhatsApp read receipt failed: %s", self.name, exc)
- _SPLIT_THRESHOLD = 6000 # WhatsApp supports ~65K chars; generous threshold
- @staticmethod
- def _classify_bridge_message(data: dict[str, Any]) -> MessageType:
- media_type = str(data.get("mediaType", "") or "")
- if media_type in _NATIVE_MEDIA_TYPES:
- return _NATIVE_MEDIA_TYPES[media_type]
- if not data.get("hasMedia"):
- return MessageType.TEXT
- return next((kind for needle, kind in _MEDIA_NEEDLES if needle in media_type), MessageType.DOCUMENT)
- async def _collect_bridge_media(self, data: dict[str, Any], msg_type: MessageType) -> tuple[list, list]:
- """``mediaUrls`` → ``(cached_urls, media_types)``: remote image/audio cached locally; absolute paths only inside a cache dir."""
- accepted: list[tuple] = [] # (url_or_path, mime)
- label, default_mime = _MEDIA_INFO.get(msg_type, (None, ""))
- bridge_mime = str(data.get("mime") or "").strip()
- for url in data.get("mediaUrls", []):
- mime = bridge_mime or (SUPPORTED_DOCUMENT_TYPES.get(Path(url).suffix.lower(), "application/octet-stream") if msg_type == MessageType.DOCUMENT else default_mime)
- if url.startswith(("http://", "https://")) and msg_type in {MessageType.PHOTO, MessageType.VOICE, MessageType.AUDIO}:
- cacher, ext = (cache_image_from_url, ".jpg") if msg_type == MessageType.PHOTO else (cache_audio_from_url, ".ogg")
- try:
- url = await cacher(url, ext=ext)
- print(f"[{self.name}] Cached user {label}: {url}", flush=True)
- except Exception as e:
- print(f"[{self.name}] Failed to cache {label}: {e}", flush=True)
- accepted.append((url, mime))
- elif label is not None and os.path.isabs(url):
- if _is_allowed_bridge_path(url):
- accepted.append((url, mime))
- print(f"[{self.name}] Using bridge-cached {label}: {url}", flush=True)
- else:
- print(f"[{self.name}] Rejected bridge {label} path outside cache dir: {url}", flush=True)
- else:
- accepted.append((url, "unknown"))
- return [u for u, _ in accepted], [m for _, m in accepted]
- def _inject_document_text(self, cached_urls: list, body: str) -> tuple[str, list[bool]]:
- """Prepend text-readable document contents (≤100KB) so the agent reads them inline; returns
- ``(body, media_text_inlined)`` with one flag per ``cached_urls`` entry (True = injected)."""
- inlined = [False] * len(cached_urls)
- for i, doc_path in enumerate(cached_urls):
- p = Path(doc_path)
- if p.suffix.lower() not in _TEXT_INJECT_EXTS:
- continue
- try:
- file_size = p.stat().st_size
- if file_size > _MAX_TEXT_INJECT_BYTES:
- print(f"[{self.name}] Skipping text injection for {doc_path} ({file_size} bytes > {_MAX_TEXT_INJECT_BYTES})", flush=True)
- continue
- content = p.read_text(encoding="utf-8-sig", errors="replace")
- parts = p.name.split("_", 2) # strip the doc_<hex>_ prefix for display
- injection = f"[Content of {parts[2] if len(parts) >= 3 else p.name}]:\n{content}"
- body = f"{injection}\n\n{body}" if body else injection
- inlined[i] = True
- print(f"[{self.name}] Injected text content from: {doc_path}", flush=True)
- except Exception as e:
- print(f"[{self.name}] Failed to read document text: {e}", flush=True)
- return body, inlined
- def _quoted_media(self, data: dict[str, Any], raw_reply_id: Any) -> list[tuple[str, str]]:
- """``(path, mime)`` for the quoted message's attachment, folded into this event's own media so the
- vision/audio pipeline sees it like a direct send. ``contextInfo.quotedMessage`` carries only a
- thumbnail stub, so the bridge resolves INBOUND quotes from its download cache (``quotedMediaUrls``,
- guarded like direct media: a rogue bridge could hand back /etc/passwd); quotes of OUR media (cron
- chart, generated image — any path we chose) resolve from the outbound index written by
- ``_send_media_to_bridge``."""
- quoted_type = str(data.get("quotedMediaType") or "").strip()
- accepted: list[tuple[str, str]] = []
- for path in data.get("quotedMediaUrls") or []:
- if not (isinstance(path, str) and os.path.isabs(path) and _is_allowed_bridge_path(path)):
- print(f"[{self.name}] Rejected quoted-media path outside cache dir: {path}", flush=True)
- continue
- accepted.append((path, _QUOTED_MIME_BY_BRIDGE_KIND.get(quoted_type, "application/octet-stream")))
- if not accepted and raw_reply_id is not None:
- from gateway import rich_sent_store
- accepted = rich_sent_store.lookup_media(data.get("chatId", ""), str(raw_reply_id))
- for path, _ in accepted:
- print(f"[{self.name}] Attached quoted-reply media: {path}", flush=True)
- return accepted
- async def _build_message_event(self, data: dict[str, Any]) -> Optional[MessageEvent]:
- """Build a MessageEvent from bridge message data, downloading images to cache."""
- try:
- if not self._should_process_message(data):
- return None
- msg_type = self._classify_bridge_message(data)
- source = self.build_source(chat_id=data.get("chatId", ""), chat_name=data.get("chatName"), chat_type="group" if data.get("isGroup", False) else "dm",
- user_id=data.get("senderId"), user_name=data.get("senderName"),
- message_id=data.get("messageId"))
- cached_urls, media_types = await self._collect_bridge_media(data, msg_type)
- body = data.get("body", "")
- if data.get("isGroup"):
- body = self._clean_bot_mention_text(body, data)
- if msg_type == MessageType.VOICE and cached_urls and str(body).strip().lower() == "[ptt received]":
- body = "" # Bridge placeholder for captionless voice notes; the audio is the payload.
- # Quoted message stays in structured fields only — GatewayRunner renders the "[Replying to: ...]" pointer.
- quoted = bool(data.get("hasQuotedMessage"))
- raw_reply_id = data.get("quotedMessageId") if quoted else None
- if quoted:
- for path, mime in self._quoted_media(data, raw_reply_id):
- cached_urls.append(path)
- media_types.append(mime)
- media_text_inlined: list[bool] = []
- if msg_type == MessageType.DOCUMENT and cached_urls:
- body, media_text_inlined = self._inject_document_text(cached_urls, body)
- native_metadata = data.get("nativeMetadata")
- metadata: dict[str, Any] = {k: v for k, v in (
- ("whatsapp_native_type", str(data.get("nativeType") or "").strip()),
- ("whatsapp_native", native_metadata if isinstance(native_metadata, dict) else None),
- ) if v}
- # ``fromOwner`` = owner-typed inbound fromMe (gated by WHATSAPP_FORWARD_OWNER_MESSAGES at the bridge); surfaced as
- # metadata AND a text prefix so the marker survives downstream failures before silent_ingest.
- if data.get("fromOwner"):
- metadata["whatsapp_from_owner"] = True
- if not body.startswith(_OWNER_REPLY_PREFIX):
- body = f"{_OWNER_REPLY_PREFIX}{body}"
- return MessageEvent(
- text=body, message_type=msg_type, source=source, raw_message=data, message_id=data.get("messageId"),
- media_urls=cached_urls, media_types=media_types, media_text_inlined=media_text_inlined, metadata=metadata,
- reply_to_message_id=str(raw_reply_id) if raw_reply_id is not None else None,
- reply_to_text=str(data.get("quotedText") or "").strip() or None,
- reply_to_author_id=(self._normalize_whatsapp_id(data.get("quotedParticipant")) or None) if quoted else None,
- reply_to_is_own_message=self._message_is_reply_to_bot(data) if quoted else False,
- )
- except Exception as e:
- print(f"[{self.name}] Error building event: {e}")
- return None
- # ── Plugin glue: register(ctx) plus the hooks for gateway/run.py, gateway/config.py, hermes_cli/gateway.py, send_message_tool.py.
- _WA_EXT_MEDIA_TYPE = {
- **dict.fromkeys((".jpg", ".jpeg", ".png", ".webp", ".gif"), "image"),
- **dict.fromkeys((".mp4", ".mov", ".avi", ".mkv", ".webm", ".3gp"), "video"),
- **dict.fromkeys((".ogg", ".opus", ".mp3", ".wav", ".m4a", ".flac"), "audio"),
- }
- def _bridge_media_type(file_path: str, is_voice: bool, force_document: bool) -> str:
- """Local file → bridge ``mediaType`` (image|video|audio|document); ``force_document`` = the [[as_document]] directive."""
- return "document" if force_document else "audio" if is_voice else _WA_EXT_MEDIA_TYPE.get(os.path.splitext(file_path)[1].lower(), "document")
- def _normalize_outbound_mentions(mentions: list[str] | None) -> list[str]:
- """Valid participant JIDs, deduplicated, order preserved."""
- return list(dict.fromkeys(jid for m in mentions or () if (jid := normalize_whatsapp_mention_jid(m))))
- async def _standalone_send(pconfig, chat_id, message, *, thread_id=None, media_files=None, force_document=False,
- caption=None, mentions=None):
- """Out-of-process delivery via the bridge HTTP API (standalone_sender_fn: cron apart from the gateway); ``caption`` rides on the media bubble."""
- try:
- import aiohttp
- except ImportError:
- return send_error("aiohttp not installed. Run: pip install aiohttp")
- try:
- from hermes_constants import get_hermes_home
- from .bridge_ownership import standalone_bridge_port
- bridge_port = standalone_bridge_port(
- get_hermes_home(), (getattr(pconfig, "extra", {}) or {}).get("bridge_port")
- )
- own_session = str(_session_dir(getattr(pconfig, "extra", {}) or {}))
- normalized_chat_id = to_whatsapp_jid(chat_id)
- media = media_files or []
- # A caption only applies to a single media file — never repeat it across a multi-file send.
- media_caption = caption if (caption and len(media) == 1) else None
- pending_mentions = _normalize_outbound_mentions(mentions)
- def _mention_first_payload(payload):
- nonlocal pending_mentions
- if pending_mentions:
- payload["mentions"] = pending_mentions
- pending_mentions = []
- return payload
- last_message_id = None
- async with aiohttp.ClientSession() as session:
- # Whose bridge holds the port is checked before anything is posted: on a shared port another profile's
- # bridge would deliver from that profile's WhatsApp account. A bridge without ``session`` predates the field.
- async with session.get(
- f"http://localhost:{bridge_port}/health",
- timeout=aiohttp.ClientTimeout(total=5),
- ) as resp:
- if resp.status != 200:
- return send_error(
- f"WhatsApp bridge on port {bridge_port} answered /health with HTTP {resp.status}; nothing was sent.")
- health = await resp.json()
- reported_session = health.get("session")
- if reported_session and reported_session != own_session:
- return send_error(
- f"WhatsApp bridge on port {bridge_port} serves another profile's session ({reported_session}); "
- "nothing was sent. Give each profile its own platforms.whatsapp.extra.bridge_port.")
- if pending_mentions:
- if not (health.get("capabilities") or {}).get("outboundMentions"):
- return {"error": (
- "WhatsApp bridge does not support native mentions; "
- "restart it from the same Hermes version.")}
- async def _post(path, payload, total, error_label=None):
- """``(messageId, None)`` on 200, else ``(None, error_dict)`` (body read only when labelled)."""
- url = f"http://localhost:{bridge_port}/{path}"
- async with session.post(url, json=payload, timeout=aiohttp.ClientTimeout(total=total)) as resp:
- if resp.status == 200:
- return (await resp.json()).get("messageId"), None
- return None, {} if error_label is None else send_error(f"WhatsApp {error_label} error ({resp.status}): {await resp.text()}")
- # 1) Text first (skipped when media-only or when the text rides as the caption).
- if (message or "").strip() and not media_caption:
- payload = _mention_first_payload({"chatId": normalized_chat_id, "message": message})
- last_message_id, err = await _post("send", payload, 30, "bridge")
- if err:
- return err
- # 2) Each media file as a native attachment (mediaType picks the WhatsApp kind).
- for media_path, is_voice in media:
- if not os.path.exists(media_path):
- # In caption mode the words would vanish with the missing file — deliver the caption as a plain message.
- if media_caption:
- try:
- payload = _mention_first_payload({"chatId": normalized_chat_id, "message": media_caption})
- await _post("send", payload, 30)
- except Exception:
- logger.warning("WhatsApp caption-fallback send failed for missing media")
- return send_error(f"WhatsApp media file not found: {media_path}")
- media_type = _bridge_media_type(media_path, is_voice, force_document)
- payload: dict[str, Any] = {"chatId": normalized_chat_id, "filePath": media_path, "mediaType": media_type}
- payload.update({k: v for k, v in (("fileName", os.path.basename(media_path) if media_type == "document" else None), ("caption", media_caption)) if v})
- payload = _mention_first_payload(payload)
- mid, err = await _post("send-media", payload, 120, "media")
- if err:
- return err
- last_message_id = mid or last_message_id
- return {"success": True, "platform": "whatsapp", "chat_id": normalized_chat_id, "message_id": last_message_id}
- except Exception as e:
- return send_error(f"WhatsApp send failed: {e}")
- def interactive_setup() -> None:
- """Guide the user through WhatsApp setup (CLI helpers lazy-imported)."""
- from hermes_cli.config import get_env_value, remove_env_value, save_env_value
- from hermes_cli.cli_output import prompt, prompt_yes_no, print_header, print_info, print_success
- print_header("WhatsApp")
- print_info("WhatsApp uses a local Node.js bridge (WhatsApp Web client).")
- print_info("Start the bridge separately; the gateway connects to it over HTTP.")
- if (get_env_value("WHATSAPP_ENABLED") or "").lower() in {"true", "1", "yes"}:
- print_info("WhatsApp: already enabled")
- if not prompt_yes_no("Reconfigure WhatsApp?", False):
- return
- if not prompt_yes_no("Enable WhatsApp?", True):
- save_env_value("WHATSAPP_ENABLED", "false")
- print_info("WhatsApp left disabled")
- return
- save_env_value("WHATSAPP_ENABLED", "true")
- print_success("WhatsApp enabled")
- allowed_users = prompt("Allowed user IDs (comma-separated, leave empty for no allowlist)")
- if allowed_users:
- save_env_value("WHATSAPP_ALLOWED_USERS", allowed_users.replace(" ", ""))
- print_success("WhatsApp allowlist configured")
- home_channel = prompt("Home chat ID for cron delivery (leave empty to skip)").strip()
- if home_channel:
- save_env_value("WHATSAPP_HOME_CHANNEL", home_channel)
- elif remove_env_value("WHATSAPP_HOME_CHANNEL"):
- print_info("Home channel cleared.")
- # config.yaml whatsapp: key → env var. Env vars take precedence over YAML.
- _YAML_BRIDGE = ( # (yaml key, env var, kind) for apply_yaml_bridge
- ("require_mention", "WHATSAPP_REQUIRE_MENTION", "lower"), ("dm_policy", "WHATSAPP_DM_POLICY", "lower"),
- ("group_policy", "WHATSAPP_GROUP_POLICY", "lower"), ("mention_patterns", "WHATSAPP_MENTION_PATTERNS", "json"),
- ("free_response_chats", "WHATSAPP_FREE_RESPONSE_CHATS", "csv"), ("allow_from", "WHATSAPP_ALLOWED_USERS", "csv"),
- ("group_allow_from", "WHATSAPP_GROUP_ALLOWED_USERS", "csv"),
- )
- def _apply_yaml_config(yaml_cfg: dict, whatsapp_cfg: dict) -> dict | None:
- """``apply_yaml_config_fn`` (#24849): config.yaml whatsapp: keys → WHATSAPP_* env (env wins; skipped under
- a multiplexed secondary profile's scope, #80099) + ``PlatformConfig.extra`` (extra-first readers)."""
- return _apply_yaml_bridge(whatsapp_cfg, _YAML_BRIDGE)
- def _is_connected(config) -> bool:
- """Connected == WHATSAPP_ENABLED opt-in (or an enabled PlatformConfig with extras); auth lives in the bridge."""
- if config is not None and getattr(config, "enabled", False) and (getattr(config, "extra", {}) or {}):
- return True
- # Via hermes_cli.gateway.get_env_value (not os.getenv) so setup-status callers that patch it observe the same value.
- import hermes_cli.gateway as gateway_mod
- return (gateway_mod.get_env_value("WHATSAPP_ENABLED") or "").strip().lower() in {"true", "1", "yes"}
- # System-prompt platform hint (PlatformEntry.platform_hint); cached-prompt bytes, keep stable.
- _PLATFORM_HINT = (
- "You are on WhatsApp. Standard markdown auto-converts to WhatsApp syntax (*bold*, _italic_, ~strike~, "
- "monospace) \u2014 write markdown freely, bullets included. No tables \u2014 use bullets or labeled lines. "
- "You can send files natively: write MEDIA:/absolute/path/to/file in your response. "
- "Images (.jpg, .png, .webp) send as photos, videos (.mp4, .mov) play "
- "inline, other files arrive as documents; image URLs via  send as photos."
- )
- # WhatsApp JIDs (@g.us, @s.whatsapp.net, @lid, broadcast/newsletter) are native targets the adapter
- # accepts verbatim — explicit, never home-channel. E.164 numbers use core's phone rule.
- _SEND_JID_RE = re.compile(r"^\s*[\w-]+@(?:g\.us|s\.whatsapp\.net|lid|broadcast|newsletter)\s*$", re.IGNORECASE)
- def register(ctx) -> None:
- from . import gateway_env # env -> GatewayConfig bridge (gateway.config_env)
- ctx.register_platform(
- target_ref_syntax_fn=regex_stripped_parser(_SEND_JID_RE),
- # Media goes through Baileys /send-media; ``mentions`` force the standalone route too.
- standalone_send=StandaloneSendPolicy(label="WhatsApp", media=True, captionable=True,
- forward_force_document=True, mentions=True, text_direct=True),
- name="whatsapp", label="WhatsApp", adapter_factory=WhatsAppAdapter, check_fn=check_whatsapp_requirements,
- dashboard_description="Use Hermes through the bundled WhatsApp bridge with QR-based auth.",
- docs_url="https://github.com/tulir/whatsmeow",
- dashboard_env_vars=(
- "WHATSAPP_ENABLED", "WHATSAPP_MODE", "WHATSAPP_DM_POLICY", "WHATSAPP_ALLOWED_USERS",
- ),
- dashboard_required_env=(),
- is_connected=_is_connected, required_env=["WHATSAPP_ENABLED"],
- install_hint="WhatsApp requires a Node.js bridge — see the WhatsApp messaging docs",
- setup_fn=interactive_setup, apply_yaml_config_fn=_apply_yaml_config, cron_deliver_env_var="WHATSAPP_HOME_CHANNEL",
- standalone_sender_fn=_standalone_send, max_message_length=4096, emoji="💬", allow_update_command=True,
- platform_hint=_PLATFORM_HINT,
- # Baileys bridge supports /edit.
- display_tier="medium",
- env_overrides=gateway_env.ENV_OVERRIDES,
- env_enable_credentials=gateway_env.ENV_ENABLE_CREDENTIALS, **gateway_env.AUTHZ,
- )
|