adapter.py 37 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719
  1. """SimpleX Chat adapter: persistent WebSocket to a simplex-chat daemon (``simplex-chat -p 5225``,
  2. or ``docker run -p 5225:5225 simplexchat/simplex-chat-cli -p 5225``); JSON commands out, events in.
  3. Env: SIMPLEX_WS_URL (required; default ws://127.0.0.1:5225) · SIMPLEX_ALLOWED_USERS (numeric
  4. contactIds — stable across renames, see ``/contacts``) · SIMPLEX_ALLOW_ALL_USERS ·
  5. SIMPLEX_AUTO_ACCEPT ('false' disables contact-request auto-accept; default true) ·
  6. SIMPLEX_GROUP_ALLOWED (group IDs or '*'; omit to ignore groups) · SIMPLEX_HOME_CHANNEL[_NAME] ·
  7. HERMES_SIMPLEX_TEXT_BATCH_DELAY (quiet seconds, default 0.8, merging rapid-fire inbound text).
  8. ``websockets`` is imported lazily so the plugin stays discoverable when the package is missing.
  9. """
  10. import asyncio
  11. import base64
  12. import contextlib
  13. import json
  14. import logging
  15. import os
  16. import random
  17. import re
  18. import time
  19. from datetime import datetime, timezone, UTC
  20. from pathlib import Path
  21. from typing import Any, Dict, List, Optional
  22. from urllib.parse import unquote
  23. from gateway.platforms._shared import (
  24. decode_json_list_literal as _decode_json_list_literal, get_scoped_secret as _get_scoped_secret,
  25. platform_gate_env as _platform_gate_env, seed_extra_from_env as _seed_extra_from_env, send_error
  26. )
  27. from gateway.config import Platform, PlatformConfig
  28. from hermes_constants import hermes_home_key
  29. from gateway.platforms.base import BasePlatformAdapter, SendResult, cache_image_from_url
  30. from gateway.platforms.helpers import cancel_task
  31. from gateway.platforms.event import MessageEvent, MessageType
  32. logger = logging.getLogger(__name__)
  33. MAX_MESSAGE_LENGTH = 8000 # SimpleX has no hard limit; chunk for sanity
  34. WS_RETRY_DELAY_INITIAL = 2.0
  35. WS_RETRY_DELAY_MAX = 60.0
  36. HEALTH_CHECK_INTERVAL = 30.0
  37. HEALTH_CHECK_STALE_THRESHOLD = 300.0
  38. _CORR_PREFIX = "hermes-" # marks requests we sent so our own echoes can be ignored
  39. _IMAGE_EXTS = {".jpg", ".jpeg", ".png", ".gif", ".webp"}
  40. _AUDIO_EXTS = {".mp3", ".wav", ".ogg", ".m4a", ".aac", ".opus"}
  41. _VOICE_TAG_EXTS = {".ogg", ".mp3", ".wav", ".m4a", ".opus"} # MEDIA: tags sent as voice notes
  42. _TEXT_BEARING_TYPES = ("text", "file", "image", "voice", "link", "video")
  43. _THUMB_URI_PREFIX = "data:image/jpg;base64,"
  44. _MEDIA_KIND_PRECEDENCE = (("audio/", MessageType.VOICE), ("image/", MessageType.PHOTO)) # first match wins
  45. def _parse_comma_list(value: str) -> list[str]:
  46. return [v.strip() for v in value.split(",") if v.strip()]
  47. # (hermes home key, names) already warned about. Module-level: every reconnect builds a FRESH adapter
  48. # (gateway/run_adapters.py), so an instance flag would re-warn on every retry while the daemon is down.
  49. _NAME_ALLOWLIST_WARNED: set = set()
  50. def _warn_name_allowlist_entries() -> None:
  51. """Warn once per process per profile/allowlist value about SIMPLEX_ALLOWED_USERS entries authz ignores.
  52. Reads and decodes the value exactly as authz does (``platform_gate_env`` + JSON list literal), so the
  53. warning names only entries that really fail the contactId check."""
  54. raw = _decode_json_list_literal(_platform_gate_env("SIMPLEX_ALLOWED_USERS"))
  55. entries = [str(e).strip() for e in raw] if isinstance(raw, list) else _parse_comma_list(raw)
  56. names = [u for u in entries if u and u != "*" and not u.isdigit()]
  57. if not names:
  58. return
  59. key = (hermes_home_key(), frozenset(names))
  60. if key in _NAME_ALLOWLIST_WARNED:
  61. return
  62. _NAME_ALLOWLIST_WARNED.add(key)
  63. logger.warning("SimpleX: SIMPLEX_ALLOWED_USERS entries %s are not numeric contactIds and are ignored "
  64. "(display names are not trusted; see /contacts for IDs)", names)
  65. def _redact_id(contact_id: str) -> str:
  66. if not contact_id:
  67. return "<none>"
  68. s = str(contact_id)
  69. return s if len(s) <= 4 else s[:2] + "**" + s[-2:]
  70. def _is_image_ext(ext: str) -> bool:
  71. return ext.lower() in _IMAGE_EXTS
  72. def _is_audio_ext(ext: str) -> bool:
  73. return ext.lower() in _AUDIO_EXTS
  74. def _mime_for_ext(ext: str) -> str:
  75. if _is_image_ext(ext):
  76. return f"image/{ext.lstrip('.')}"
  77. if _is_audio_ext(ext):
  78. return f"audio/{ext.lstrip('.')}"
  79. return "application/octet-stream"
  80. def _display_name(obj: dict, profile_key: str, default: str = "") -> str:
  81. """``localDisplayName`` falling back to the nested profile's ``displayName``."""
  82. return obj.get("localDisplayName", "") or (obj.get(profile_key, {}) or {}).get("displayName", default)
  83. def _send_cmd(chat_id: str, items: list) -> str:
  84. """Structured ``/_send <target> json …`` addressing *chat_id* by ID. The bare ``@name`` / ``#[id]``
  85. syntax is a display-name lookup that silently drops unresolved names; json.dumps escapes text."""
  86. target = f"#{chat_id[6:]}" if chat_id.startswith("group:") else f"@{chat_id}"
  87. return f"/_send {target} json {json.dumps(items)}"
  88. class SimplexAdapter(BasePlatformAdapter):
  89. """SimpleX Chat adapter using the simplex-chat daemon WebSocket API."""
  90. MAX_MESSAGE_LENGTH = MAX_MESSAGE_LENGTH
  91. serial_receive_loop = True # the WebSocket loop awaits each event before reading the next
  92. def __init__(self, config: PlatformConfig, **kwargs):
  93. super().__init__(config=config, platform=Platform("simplex"))
  94. extra = getattr(config, "extra", {}) or {}
  95. self.ws_url = extra.get("ws_url", "ws://127.0.0.1:5225").rstrip("/")
  96. # Auto-accept is on by default; env wins over the ``_env_enablement`` seed.
  97. env_auto = _get_scoped_secret("SIMPLEX_AUTO_ACCEPT")
  98. if env_auto is not None:
  99. self.auto_accept = env_auto.strip().lower() not in {"0", "false", "no", ""}
  100. else:
  101. self.auto_accept = bool(extra.get("auto_accept", True))
  102. # Without SIMPLEX_GROUP_ALLOWED group messages are ignored (safer default); ``*`` = any group.
  103. group_allowed_str = _get_scoped_secret("SIMPLEX_GROUP_ALLOWED", "") or extra.get("group_allowed", "")
  104. # Parse allowlists — group policy is derived from presence of group allowlist Scoped reads (#93522):
  105. # allowlists are per-profile authorization config; raw os.getenv misses secondary profiles' .env
  106. # values and leaks the default profile's list into them.
  107. self.group_allow_from = set(_parse_comma_list(group_allowed_str))
  108. self._ws = None # websockets connection
  109. self._ws_task: Optional[asyncio.Task] = None
  110. self._health_task: Optional[asyncio.Task] = None
  111. self._running = False
  112. self._last_ws_activity = 0.0
  113. self._pending_corr_ids: set = set() # cosmetic echo filter: corrIds we minted, bounded
  114. self._max_pending_corr = 200
  115. self._pending_file_transfers: dict[int, dict] = {} # awaiting rcvFileComplete, by fileId
  116. self._pending_responses: dict[str, asyncio.Future] = {} # awaited command replies
  117. self._corr_counter = 0
  118. # SimpleX has no client-side split, so the split delay equals the plain one.
  119. self._text_batch_delay_seconds = float(os.getenv("HERMES_SIMPLEX_TEXT_BATCH_DELAY", "0.8"))
  120. self._text_batch_split_delay_seconds = self._text_batch_delay_seconds
  121. logger.info(
  122. "SimpleX adapter initialized: url=%s auto_accept=%s groups=%s",
  123. self.ws_url, self.auto_accept, "enabled" if self.group_allow_from else "disabled")
  124. async def connect(self, *, is_reconnect: bool = False) -> bool:
  125. try:
  126. import websockets as _wsclient
  127. except ImportError:
  128. logger.error("SimpleX: 'websockets' package not installed. Run: pip install websockets")
  129. return False
  130. if not self.ws_url:
  131. logger.error("SimpleX: SIMPLEX_WS_URL is required")
  132. return False
  133. _warn_name_allowlist_entries() # before the probe so a daemon-down cold boot still warns
  134. try: # quick connectivity check — open and immediately close
  135. async with _wsclient.connect(self.ws_url, open_timeout=10):
  136. pass
  137. except Exception as e:
  138. logger.error("SimpleX: cannot reach daemon at %s: %s", self.ws_url, e)
  139. return False
  140. self._running = True
  141. self._last_ws_activity = time.time()
  142. self._ws_task = asyncio.create_task(self._ws_listener())
  143. self._health_task = asyncio.create_task(self._health_monitor())
  144. self._mark_connected()
  145. logger.info("SimpleX: connected to %s", self.ws_url)
  146. self._wire_plugin_handlers(None)
  147. return True
  148. async def disconnect(self) -> None:
  149. self._running = False
  150. await cancel_task(self._ws_task)
  151. await cancel_task(self._health_task)
  152. if self._ws:
  153. with contextlib.suppress(Exception):
  154. await self._ws.close()
  155. self._ws = None
  156. for pending in (self._pending_text_batch_tasks.values(), self._pending_responses.values()):
  157. for item in list(pending):
  158. if not item.done():
  159. item.cancel()
  160. self._pending_text_batch_tasks.clear()
  161. self._pending_text_batches.clear()
  162. self._pending_responses.clear()
  163. self._mark_disconnected()
  164. logger.info("SimpleX: disconnected")
  165. async def _ws_listener(self) -> None:
  166. import websockets as _wsclient
  167. from websockets.exceptions import ConnectionClosed
  168. backoff = WS_RETRY_DELAY_INITIAL
  169. while self._running:
  170. try:
  171. logger.debug("SimpleX WS: connecting to %s", self.ws_url)
  172. async with _wsclient.connect(self.ws_url, ping_interval=20, ping_timeout=20, close_timeout=10) as ws:
  173. self._ws = ws
  174. backoff = WS_RETRY_DELAY_INITIAL
  175. self._last_ws_activity = time.time()
  176. logger.info("SimpleX WS: connected")
  177. async for raw in ws:
  178. if not self._running:
  179. break
  180. self._last_ws_activity = time.time()
  181. try:
  182. await self._handle_event(json.loads(raw))
  183. except json.JSONDecodeError:
  184. logger.debug("SimpleX WS: invalid JSON: %.100s", raw)
  185. except Exception:
  186. logger.exception("SimpleX WS: error handling event")
  187. except asyncio.CancelledError:
  188. break
  189. except ConnectionClosed as e:
  190. if self._running:
  191. logger.warning("SimpleX WS: connection closed: %s (reconnecting in %.0fs)", e, backoff)
  192. except Exception as e:
  193. if self._running:
  194. logger.warning("SimpleX WS: unexpected error: %s (reconnecting in %.0fs)", e, backoff)
  195. finally:
  196. self._ws = None
  197. if self._running:
  198. await asyncio.sleep(backoff + backoff * 0.2 * random.random())
  199. backoff = min(backoff * 2, WS_RETRY_DELAY_MAX)
  200. async def _health_monitor(self) -> None:
  201. """Log (never reconnect on) WebSocket idleness: simplex-chat legitimately stays
  202. application-silent for long periods and the client already sends protocol pings."""
  203. while self._running:
  204. await asyncio.sleep(HEALTH_CHECK_INTERVAL)
  205. if not self._running:
  206. break
  207. elapsed = time.time() - self._last_ws_activity
  208. if elapsed > HEALTH_CHECK_STALE_THRESHOLD:
  209. logger.debug("SimpleX: WS application-idle for %.0fs", elapsed)
  210. async def _handle_event(self, event: dict) -> None:
  211. # Usually {"corrId": ..., "resp": {"type": ...}}, but some daemons put the
  212. # response fields at top level — normalize both.
  213. resp = event.get("resp") if isinstance(event.get("resp"), dict) else event
  214. corr_id = event.get("corrId")
  215. if corr_id and corr_id in self._pending_responses:
  216. fut = self._pending_responses.pop(corr_id)
  217. if not fut.done():
  218. fut.set_result(resp)
  219. return
  220. if corr_id and isinstance(corr_id, str) and corr_id.startswith(_CORR_PREFIX):
  221. self._pending_corr_ids.discard(corr_id) # our own un-awaited echo
  222. return
  223. resp_type = resp.get("type") or event.get("type", "")
  224. handler = self._EVENT_HANDLERS.get(resp_type)
  225. if handler is not None:
  226. await handler(self, resp)
  227. elif resp_type:
  228. logger.debug("SimpleX: unhandled event type: %s", resp_type)
  229. async def _on_contact_request(self, resp: dict) -> None:
  230. if not self.auto_accept:
  231. logger.debug("SimpleX: unhandled event type: %s", "contactRequest")
  232. return
  233. contact_req_id = (resp.get("contactRequest", {}) or {}).get("contactRequestId")
  234. if contact_req_id is not None:
  235. logger.info("SimpleX: auto-accepting contact request %s", _redact_id(str(contact_req_id)))
  236. await self._send_command(f"/accept {contact_req_id}")
  237. async def _on_rcv_file_descr_ready(self, resp: dict) -> None:
  238. """XFTP files fire this before newChatItems; start the download now, the chat item arrives later."""
  239. rcv_file = resp.get("rcvFileTransfer", {}) or {}
  240. if (file_id := rcv_file.get("fileId") if isinstance(rcv_file, dict) else None) is not None:
  241. logger.debug("SimpleX: rcvFileDescrReady for fileId=%s — sending /freceive", file_id)
  242. await self._send_fire_and_forget(f"/freceive {file_id}")
  243. async def _on_new_chat_items(self, resp: dict) -> None:
  244. chat_items = resp.get("chatItems", []) or []
  245. for item in chat_items if isinstance(chat_items, list) else [chat_items]:
  246. await self._safe_handle_chat_item(item, "SimpleX: error processing chat item")
  247. async def _on_new_chat_item(self, resp: dict) -> None: # singular variant from some daemon versions
  248. await self._safe_handle_chat_item(resp, "SimpleX: error processing chat item")
  249. async def _on_rcv_file_complete(self, resp: dict) -> None:
  250. """Deliver a chat item deferred until its file transfer completed."""
  251. chat_item_data = (resp.get("chatItem", {}) or {}).get("chatItem", {}) or {}
  252. file_info = chat_item_data.get("file", {}) or {}
  253. file_id = file_info.get("fileId") if isinstance(file_info, dict) else None
  254. if file_id is None or file_id not in self._pending_file_transfers:
  255. return
  256. pending = self._pending_file_transfers.pop(file_id)
  257. file_source = file_info.get("fileSource", {}) or {}
  258. file_path = file_source.get("filePath") if isinstance(file_source, dict) else None
  259. if file_path:
  260. pending_item_data = pending.get("chatItem", {}) or {}
  261. pending_item_data.setdefault("file", {})["fileSource"] = {"filePath": file_path}
  262. pending["chatItem"] = pending_item_data
  263. await self._safe_handle_chat_item(pending, "SimpleX: error processing deferred file message")
  264. _EVENT_HANDLERS = {
  265. "contactRequest": _on_contact_request, "rcvFileDescrReady": _on_rcv_file_descr_ready,
  266. "newChatItems": _on_new_chat_items, "newChatItem": _on_new_chat_item, "rcvFileComplete": _on_rcv_file_complete,
  267. }
  268. async def _safe_handle_chat_item(self, item: dict, err_msg: str) -> None:
  269. try:
  270. await self._handle_chat_item(item)
  271. except Exception:
  272. logger.exception(err_msg)
  273. async def _handle_chat_item(self, chat_item: dict) -> None:
  274. chat_info = chat_item.get("chatInfo", {}) or {}
  275. chat_item_data = chat_item.get("chatItem", {}) or {}
  276. chat_type = chat_info.get("type", "")
  277. meta = chat_item_data.get("meta", {}) or {}
  278. content = chat_item_data.get("content", {}) or {}
  279. msg_content = content.get("msgContent", {}) or {}
  280. item_direction = chat_item_data.get("chatDir", {}) or {}
  281. direction_type = item_direction.get("type", "") if isinstance(item_direction, dict) else ""
  282. if direction_type in ("directSnd", "groupSnd"): # our own messages
  283. return
  284. content_type = content.get("type", "") if isinstance(content, dict) else ""
  285. if content_type != "rcvMsgContent":
  286. return
  287. msg_type_str = msg_content.get("type", "") if isinstance(msg_content, dict) else ""
  288. text = msg_content.get("text", "") if msg_type_str in _TEXT_BEARING_TYPES else ""
  289. if not text and msg_type_str not in ("image", "file", "voice"):
  290. return
  291. is_group = chat_type == "group"
  292. if chat_type == "direct":
  293. contact = chat_info.get("contact", {}) or {}
  294. sender_id = chat_id = str(contact.get("contactId", ""))
  295. sender_name = chat_name = _display_name(contact, "profile")
  296. elif is_group:
  297. group_info = chat_info.get("groupInfo", {}) or {}
  298. group_id = str(group_info.get("groupId", ""))
  299. chat_id = f"group:{group_id}"
  300. member = item_direction.get("groupMember", {}) or {}
  301. sender_id = str(member.get("memberId", ""))
  302. sender_name = _display_name(member, "memberProfile")
  303. chat_name = _display_name(group_info, "groupProfile", chat_id)
  304. if not self.group_allow_from:
  305. logger.debug("SimpleX: ignoring group message (no SIMPLEX_GROUP_ALLOWED)")
  306. return
  307. if "*" not in self.group_allow_from and group_id not in self.group_allow_from:
  308. logger.debug("SimpleX: group %s not in allowlist", _redact_id(group_id))
  309. return
  310. else:
  311. logger.debug("SimpleX: unhandled chat type: %s", chat_type)
  312. return
  313. if not sender_id:
  314. logger.debug("SimpleX: ignoring message with no sender")
  315. return
  316. # Attachment: chatItem.chatItem.file (sibling of meta/content/chatDir).
  317. media_urls: list[str] = []
  318. media_types: list[str] = []
  319. file_info = chat_item_data.get("file")
  320. if file_info and isinstance(file_info, dict):
  321. file_source = file_info.get("fileSource", {}) or {}
  322. file_path = file_source.get("filePath") if isinstance(file_source, dict) else None
  323. file_id = file_info.get("fileId")
  324. ext = Path(file_path).suffix.lower() if file_path else ""
  325. if not ext and file_info.get("fileName", ""):
  326. ext = Path(file_info["fileName"]).suffix.lower()
  327. # Voice notes typically arrive before the file finishes downloading; defer until
  328. # rcvFileComplete. /freceive gets no corrId reply, so awaiting one would block the loop.
  329. if not file_path and _is_audio_ext(ext) and file_id is not None:
  330. logger.info("SimpleX: voice file %d not yet received, accepting transfer", file_id)
  331. self._pending_file_transfers[file_id] = chat_item
  332. await self._send_fire_and_forget(f"/freceive {file_id}")
  333. return
  334. if file_path:
  335. media_urls.append(file_path)
  336. media_types.append(_mime_for_ext(ext))
  337. source = self.build_source(
  338. chat_id=chat_id, chat_name=chat_name, chat_type="group" if is_group else "dm",
  339. user_id=sender_id, user_name=sender_name or sender_id)
  340. # Non-image/non-audio files are DOCUMENT so run.py's document-context injection surfaces them.
  341. msg_type = MessageType.TEXT
  342. if media_types:
  343. msg_type = next((t for prefix, t in _MEDIA_KIND_PRECEDENCE if any(mt.startswith(prefix) for mt in media_types)),
  344. MessageType.DOCUMENT)
  345. ts_str = meta.get("itemTs") or meta.get("createdAt", "")
  346. try:
  347. timestamp = datetime.fromisoformat(ts_str) if ts_str else datetime.now(tz=UTC)
  348. except (ValueError, AttributeError):
  349. timestamp = datetime.now(tz=UTC)
  350. msg_event = MessageEvent(
  351. source=source, text=text or "", message_type=msg_type, media_urls=media_urls,
  352. media_types=media_types, timestamp=timestamp, raw_message=chat_item)
  353. logger.debug("SimpleX: message from %s in %s: %s", _redact_id(sender_id), chat_id[:20], (text or "")[:50])
  354. if msg_type == MessageType.TEXT and text: # batch rapid-fire text into one combined message
  355. self._enqueue_text_event(msg_event)
  356. else:
  357. await self.handle_message(msg_event)
  358. # Text batching: enqueue lives on BasePlatformAdapter.
  359. def _text_batch_key(self, event: MessageEvent) -> str:
  360. return f"{event.source.platform.value}:{event.source.chat_id}"
  361. def _make_corr_id(self) -> str:
  362. """Mint a correlation ID and remember it for echo-filtering; the set is bounded by
  363. ``_max_pending_corr`` (overflow evicted in one sweep)."""
  364. self._corr_counter += 1
  365. corr_id = f"{_CORR_PREFIX}{self._corr_counter}-{int(time.time() * 1000)}"
  366. self._pending_corr_ids.add(corr_id)
  367. for _ in range(len(self._pending_corr_ids) - self._max_pending_corr):
  368. self._pending_corr_ids.pop()
  369. return corr_id
  370. async def _send_ws(self, payload: dict) -> None:
  371. """Fire-and-forget JSON write; drops cleanly when the WS is missing/closed."""
  372. if not self._ws:
  373. logger.debug("SimpleX: WS send dropped (not connected)")
  374. return
  375. try:
  376. await self._ws.send(json.dumps(payload))
  377. except Exception as e:
  378. logger.warning("SimpleX: WS send error: %s", e)
  379. async def _send_command(self, command: str, timeout: float = 30.0) -> Optional[dict]:
  380. ws = self._ws
  381. if not ws:
  382. logger.warning("SimpleX: command sent but WebSocket not connected")
  383. return None
  384. corr_id = self._make_corr_id()
  385. fut: asyncio.Future = asyncio.get_event_loop().create_future()
  386. self._pending_responses[corr_id] = fut
  387. try:
  388. await ws.send(json.dumps({"corrId": corr_id, "cmd": command}))
  389. return await asyncio.wait_for(fut, timeout=timeout)
  390. except TimeoutError:
  391. logger.warning("SimpleX: command timed out: %s", command[:50])
  392. except Exception as e:
  393. logger.warning("SimpleX: command failed: %s — %s", command[:50], e)
  394. self._pending_responses.pop(corr_id, None)
  395. return None
  396. async def _send_fire_and_forget(self, command: str) -> None:
  397. """Send a command the daemon never replies to with a corrId (e.g. ``/freceive``)."""
  398. await self._send_ws({"corrId": self._make_corr_id(), "cmd": command})
  399. async def _send_items(self, chat_id: str, items: list, error: str) -> SendResult:
  400. """Send a structured ``/_send`` payload and await the reply."""
  401. result = await self._send_command(_send_cmd(chat_id, items))
  402. return SendResult(success=True) if result is not None else SendResult(success=False, error=error)
  403. async def send(
  404. self, chat_id: str, content: str, reply_to: Optional[str] = None, metadata: Optional[dict[str, Any]] = None,
  405. ) -> SendResult:
  406. """Send text; ``MEDIA:<path>`` tags (TTS / audio tools) are stripped and sent as native voice
  407. notes or documents. The text send is fire-and-forget: the daemon doesn't always return a corrId
  408. reply for chat commands, and waiting would serialise all outbound traffic behind a 30s timeout."""
  409. media_paths = re.findall(r"MEDIA:(\S+)", content)
  410. if media_paths:
  411. content = re.sub(r"MEDIA:\S+", "", content).strip()
  412. if content:
  413. cmd_str = _send_cmd(chat_id, [{"msgContent": {"type": "text", "text": content}}])
  414. await self._send_ws({"corrId": self._make_corr_id(), "cmd": cmd_str})
  415. for path in media_paths:
  416. if os.path.splitext(path)[1].lower() in _VOICE_TAG_EXTS:
  417. media_result = await self.send_voice(chat_id, path)
  418. else:
  419. media_result = await self.send_document(chat_id, path)
  420. if not media_result.success:
  421. return media_result
  422. return SendResult(success=True)
  423. async def list_channels(self) -> Optional[list[dict[str, Any]]]:
  424. """Enumerate contacts and allowed groups for the channel directory.
  425. Returns ``None`` (not ``[]``) when the WebSocket is down or the daemon is unresponsive so
  426. the directory falls back to session-history discovery instead of wiping known targets.
  427. Entry ``id`` values match the send targets: display name for DMs, ``group:<id>`` for groups.
  428. """
  429. if not self._ws:
  430. return None
  431. resp = await self._send_command("/contacts", timeout=10.0)
  432. if resp is None:
  433. return None
  434. channels: list[dict[str, Any]] = []
  435. for contact in resp.get("contacts") or []:
  436. if not isinstance(contact, dict):
  437. continue
  438. contact_id = contact.get("contactId")
  439. name = _display_name(contact, "profile")
  440. if contact_id is None and not name:
  441. continue
  442. # Display name is what the DM send path addresses; fall back to contactId.
  443. channels.append({"id": str(name or contact_id), "name": str(name or contact_id), "type": "dm"})
  444. resp = await self._send_command("/groups", timeout=10.0)
  445. for group in (resp.get("groups") or []) if resp is not None else []:
  446. if isinstance(group, list) and group: # groupInfo dict or [groupInfo, groupSummary] pair
  447. group = group[0]
  448. if not isinstance(group, dict) or group.get("groupId") is None:
  449. continue
  450. group_id = group["groupId"]
  451. name = _display_name(group, "groupProfile") or str(group_id)
  452. channels.append({"id": f"group:{group_id}", "name": str(name), "type": "group"})
  453. return channels
  454. @staticmethod
  455. def _prepare_image(file_path: str) -> tuple[str, str]:
  456. """Ensure *file_path* is PNG/JPEG and return ``(png_path, thumb_data_uri)``. SimpleX clients
  457. can't show WebP etc. inline, so convert to PNG when needed and build a 128px JPEG thumbnail for
  458. the ``image`` field. Uses Pillow when available, else ImageMagick ``convert``."""
  459. import subprocess
  460. import tempfile
  461. p = Path(file_path)
  462. needs_png = p.suffix.lower() not in (".png", ".jpg", ".jpeg")
  463. png_path = str(p.with_suffix(".png")) if needs_png else file_path
  464. thumb_uri = ""
  465. try:
  466. from PIL import Image
  467. import io
  468. img = Image.open(file_path)
  469. if needs_png:
  470. img.save(png_path, "PNG")
  471. thumb = img.copy()
  472. thumb.thumbnail((128, 128))
  473. if thumb.mode not in ("RGB", "L"):
  474. if thumb.mode in ("RGBA", "LA", "P"):
  475. layer = thumb.convert("RGBA")
  476. background = Image.new("RGB", layer.size, (255, 255, 255))
  477. background.paste(layer, mask=layer.getchannel("A"))
  478. thumb = background
  479. else:
  480. thumb = thumb.convert("RGB")
  481. buf = io.BytesIO()
  482. thumb.save(buf, "JPEG", quality=70)
  483. thumb_uri = _THUMB_URI_PREFIX + base64.b64encode(buf.getvalue()).decode()
  484. except ImportError:
  485. try:
  486. if needs_png:
  487. subprocess.run(["convert", file_path, png_path],
  488. check=True, capture_output=True, timeout=30, stdin=subprocess.DEVNULL)
  489. with tempfile.NamedTemporaryFile(suffix=".jpg", delete=False) as tmp:
  490. tmp_path = tmp.name
  491. subprocess.run(["convert", file_path, "-resize", "128x128", "-quality", "70", tmp_path],
  492. check=True, capture_output=True, timeout=30, stdin=subprocess.DEVNULL)
  493. with open(tmp_path, "rb") as f:
  494. thumb_uri = _THUMB_URI_PREFIX + base64.b64encode(f.read()).decode()
  495. os.remove(tmp_path)
  496. except (FileNotFoundError, subprocess.SubprocessError) as exc:
  497. logger.warning("SimpleX: image conversion unavailable: %s", exc)
  498. return png_path, thumb_uri
  499. async def send_image(self, chat_id: str, image_url: str, caption: Optional[str] = None, **kwargs) -> SendResult:
  500. """Send an image. Supports ``file://`` URLs and ``http(s)://`` URLs."""
  501. if image_url.startswith("file://"):
  502. file_path = unquote(image_url[7:])
  503. else:
  504. try:
  505. file_path = await cache_image_from_url(image_url)
  506. except Exception as e:
  507. logger.warning("SimpleX: failed to download image: %s", e)
  508. return SendResult(success=False, error=str(e))
  509. if not file_path or not Path(file_path).exists():
  510. return SendResult(success=False, error="Image file not found")
  511. try:
  512. png_path, thumb_uri = self._prepare_image(file_path)
  513. except Exception as exc:
  514. logger.warning("SimpleX: failed to prepare image: %s", exc)
  515. return SendResult(success=False, error=f"Failed to prepare image: {exc}")
  516. # /_send addresses by numeric ID; /f only accepts display names.
  517. item = {"filePath": png_path, "msgContent": {"type": "image", "image": thumb_uri, "text": caption or ""}}
  518. return await self._send_items(chat_id, [item], "Failed to send image")
  519. async def send_image_file(self, chat_id: str, image_path: str, caption: Optional[str] = None,
  520. reply_to: Optional[str] = None, **kwargs) -> SendResult:
  521. return await self.send_image(chat_id, f"file://{image_path}", caption=caption, **kwargs)
  522. async def send_video(self, chat_id: str, video_path: str, caption: Optional[str] = None,
  523. reply_to: Optional[str] = None, **kwargs) -> SendResult:
  524. """Videos go as file attachments."""
  525. return await self.send_document(chat_id, video_path, caption=caption)
  526. async def send_document(self, chat_id: str, file_path: str, caption: Optional[str] = None,
  527. filename: Optional[str] = None, **kwargs) -> SendResult:
  528. if not Path(file_path).exists():
  529. return SendResult(success=False, error="File not found")
  530. item = {"filePath": file_path, "msgContent": {"type": "file", "text": caption or ""}}
  531. return await self._send_items(chat_id, [item], "Failed to send document")
  532. async def send_voice(self, chat_id: str, audio_path: str, caption: Optional[str] = None,
  533. reply_to: Optional[str] = None, duration: int = 0, **kwargs) -> SendResult:
  534. """Send an audio file as an inline SimpleX voice note (``msgContent.type == "voice"``)."""
  535. if not Path(audio_path).exists():
  536. return SendResult(success=False, error="Voice file not found")
  537. item = {"msgContent": {"type": "voice", "text": caption or "", "duration": duration},
  538. "fileSource": {"filePath": audio_path}}
  539. return await self._send_items(chat_id, [item], "Failed to send voice message")
  540. async def send_typing(self, chat_id: str, metadata=None) -> None:
  541. """SimpleX has no typing-indicator API — no-op."""
  542. async def get_chat_info(self, chat_id: str) -> dict[str, Any]:
  543. is_group = chat_id.startswith("group:")
  544. return {"chat_id": chat_id, "type": "group" if is_group else "dm", "name": chat_id[6:] if is_group else chat_id}
  545. def check_requirements() -> bool:
  546. """Plugin gate: require SIMPLEX_WS_URL AND the websockets package."""
  547. if not _get_scoped_secret("SIMPLEX_WS_URL"):
  548. return False
  549. try:
  550. import websockets
  551. return True
  552. except ImportError:
  553. return False
  554. def validate_config(config) -> bool:
  555. extra = getattr(config, "extra", {}) or {}
  556. return bool(_get_scoped_secret("SIMPLEX_WS_URL") or extra.get("ws_url", ""))
  557. def is_connected(config) -> bool:
  558. """Configured (env or config.yaml) ⇒ shown as connected in status."""
  559. return validate_config(config)
  560. def _env_enablement() -> Optional[dict]:
  561. """``env_enablement_fn``: seed ``PlatformConfig.extra`` from the profile's env BEFORE adapter
  562. construction; ``None`` when ``SIMPLEX_WS_URL`` is unset."""
  563. ws_url = _get_scoped_secret("SIMPLEX_WS_URL", "").strip()
  564. if not ws_url:
  565. return None
  566. seed = _seed_extra_from_env((
  567. ("SIMPLEX_AUTO_ACCEPT", "auto_accept", lambda v: v.lower() not in {"0", "false", "no"}),
  568. ("SIMPLEX_GROUP_ALLOWED", "group_allowed", None),
  569. ), home_env="SIMPLEX_HOME_CHANNEL")
  570. return {"ws_url": ws_url, **seed}
  571. async def _standalone_send(
  572. pconfig, chat_id: str, message: str, *,
  573. thread_id: Optional[str] = None, media_files: Optional[list[str]] = None, force_document: bool = False,
  574. ) -> dict[str, Any]:
  575. """Ephemeral WebSocket send for ``tools/send_message_tool`` when the gateway runner is not in
  576. this process (``hermes cron``). ``thread_id``/``force_document`` are signature parity only;
  577. ``media_files`` is accepted but only the text body is delivered — SimpleX file transfers need
  578. the daemon's filesystem-backed flow, which an ephemeral connection cannot drive safely."""
  579. try:
  580. import websockets as _wsclient
  581. except ImportError:
  582. return send_error("websockets not installed. Run: pip install websockets")
  583. extra = getattr(pconfig, "extra", {}) or {}
  584. ws_url = _get_scoped_secret("SIMPLEX_WS_URL") or extra.get("ws_url", "ws://127.0.0.1:5225")
  585. if not ws_url:
  586. return send_error("SimpleX standalone send: SIMPLEX_WS_URL is required")
  587. try:
  588. payload = {
  589. "corrId": f"{_CORR_PREFIX}snd-{int(time.time() * 1000)}",
  590. "cmd": _send_cmd(chat_id, [{"msgContent": {"type": "text", "text": message}}])}
  591. async with _wsclient.connect(ws_url, open_timeout=10, close_timeout=5) as ws:
  592. await ws.send(json.dumps(payload))
  593. await asyncio.sleep(0.5) # let the daemon process the command before closing
  594. return {"success": True, "platform": "simplex", "chat_id": chat_id}
  595. except Exception as e:
  596. return send_error(f"SimpleX send failed: {e}")
  597. _SETUP_PROMPTS = (
  598. ("SIMPLEX_WS_URL", "Daemon WebSocket URL (default ws://127.0.0.1:5225)"),
  599. ("SIMPLEX_ALLOWED_USERS", "Allowed contactIds (comma-separated; blank=skip)"),
  600. ("SIMPLEX_GROUP_ALLOWED", "Allowed group IDs (comma-separated, or '*' for any; blank=disable groups)"),
  601. ("SIMPLEX_AUTO_ACCEPT", "Auto-accept incoming contact requests? (true/false, default true)"),
  602. ("SIMPLEX_HOME_CHANNEL", "Home channel contact/group ID (or empty)"))
  603. def interactive_setup() -> None:
  604. """``hermes setup gateway`` → SimpleX wizard (writes ``~/.hermes/.env``); CLI helpers are lazy-imported."""
  605. from hermes_cli.config import get_env_value, save_env_value
  606. from hermes_cli.cli_output import print_header, print_info, prompt
  607. from hermes_cli.setup_platforms import declines_reconfigure
  608. print_header("SimpleX Chat")
  609. if declines_reconfigure("SimpleX", "Reconfigure SimpleX?", "SIMPLEX_WS_URL"):
  610. return
  611. for line in ("Requirements:", " 1. simplex-chat daemon running (e.g. `simplex-chat -p 5225`).",
  612. " 2. Python package `websockets` installed (`pip install websockets`)."):
  613. print_info(line)
  614. for var, question in _SETUP_PROMPTS:
  615. suffix = " [keep current]" if get_env_value(var) else ""
  616. value = prompt(f"{question}{suffix}")
  617. if value:
  618. save_env_value(var, value)
  619. print_info("Done. Make sure the simplex-chat daemon is running before starting the gateway.")
  620. def register(ctx) -> None:
  621. ctx.register_platform(
  622. name="simplex", label="SimpleX Chat", adapter_factory=lambda cfg: SimplexAdapter(cfg),
  623. dashboard_description="Talk to Hermes over SimpleX Chat via a local simplex-chat daemon.",
  624. docs_url="https://hermes-agent.nousresearch.com/docs/user-guide/messaging/simplex",
  625. check_fn=check_requirements, validate_config=validate_config, is_connected=is_connected,
  626. required_env=["SIMPLEX_WS_URL"],
  627. install_hint=("pip install websockets # SimpleX adapter requires the websockets package"),
  628. setup_fn=interactive_setup, env_enablement_fn=_env_enablement, cron_deliver_env_var="SIMPLEX_HOME_CHANNEL",
  629. standalone_sender_fn=_standalone_send, allowed_users_env="SIMPLEX_ALLOWED_USERS",
  630. allow_all_env="SIMPLEX_ALLOW_ALL_USERS", max_message_length=MAX_MESSAGE_LENGTH, emoji="🔒",
  631. pii_safe=True, # SimpleX uses opaque contact IDs only — nothing to redact
  632. allow_update_command=True,
  633. platform_hint=(
  634. "You are chatting via SimpleX Chat, a private decentralised "
  635. "messenger. Contacts are identified by opaque internal IDs, "
  636. "not phone numbers or usernames. SimpleX supports standard "
  637. "markdown formatting. There is no typing indicator and no "
  638. "hard message length limit, but keep responses conversational. "
  639. "You can attach native images, voice notes, and arbitrary "
  640. "files; the adapter handles MEDIA:<path> tags by sending them "
  641. "as inline voice notes (audio extensions) or documents."))