send_message_tool.py 41 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748
  1. """Send Message Tool -- cross-channel messaging via platform APIs (send, list targets,
  2. react); works in both CLI and gateway contexts."""
  3. import asyncio
  4. import json
  5. import logging
  6. import os
  7. import re
  8. from agent.secret_scope import get_secret
  9. logger = logging.getLogger(__name__)
  10. from tools.send_message_targets import (
  11. _HOME_CHANNEL_ENV_OVERRIDES, resolve_send_target, unknown_platform_error,
  12. )
  13. from tools.send_message_senders import (
  14. _AUDIO_EXTS, _DEFAULT_CAPTION_LIMIT, _IMAGE_EXTS, _NO_DELIVERABLE, _VIDEO_EXTS, _VOICE_EXTS,
  15. _adapter_media_method, _error, _live_adapter, _media_caption_split, _plugin_standalone_sender,
  16. _registry_standalone_send, _resolve_slack_user_target, _sanitize_error_text,
  17. _send_matrix_via_adapter, _send_telegram)
  18. from tools.registry import tool_error
  19. # A bare Slack user id (session metadata / home-channel config) is opened as a DM; same shape the
  20. # slack plugin's target parser turns into ``user:U...``.
  21. _SLACK_USER_ID_RE = re.compile(r"^\s*(U[A-Z0-9]{8,})\s*$")
  22. # NOTE: ``send_message`` is intentionally NOT registered as an agent-callable model tool
  23. # (the agent must not fire cross-platform messages on its own); cron delivery, the
  24. # ``hermes send`` CLI, the kanban notifier and the opt-in MCP server import the helpers.
  25. def prepare_send_message_platforms() -> None:
  26. """Load enabled standalone plugins before tool schemas/cache keys are built."""
  27. from hermes_cli.plugins import discover_plugins
  28. discover_plugins()
  29. def send_message_tool(args, **kw):
  30. """Handle cross-channel send_message tool calls."""
  31. action = args.get("action", "send")
  32. if action == "list":
  33. return _handle_list()
  34. if action in ("react", "unreact"):
  35. return _handle_react(args, remove=action == "unreact")
  36. return _handle_send(args)
  37. def _resolve_tool_target(target: str, *, pass_unresolved_references: bool = False):
  38. """``(platform_name, chat_id, thread_id, error)``; ``chat_id`` is None when no ref was given
  39. (caller falls back to the home channel)."""
  40. platform_name, _, target_ref = target.partition(":")
  41. platform_name, target_ref = platform_name.strip().lower(), target_ref.strip() or None
  42. prepare_send_message_platforms()
  43. if not target_ref:
  44. return platform_name, None, None, None
  45. return platform_name, *resolve_send_target(platform_name, target_ref,
  46. pass_unresolved_references=pass_unresolved_references)
  47. def _handle_list():
  48. try:
  49. from gateway.channel_directory import format_directory_for_display
  50. return json.dumps({"targets": format_directory_for_display()})
  51. except Exception as e:
  52. return json.dumps(_error(f"Failed to load channel directory: {e}"))
  53. _TOKEN_UNSET = object()
  54. def _authorize_relay_target(platform_name: str, chat_id, thread_id=None, *,
  55. native_token=_TOKEN_UNSET) -> str | None:
  56. """Relay egress-authorization guard (P5a); None when the send may proceed.
  57. Thin delegate to ``gateway.relay.egress`` so the tool keeps working in
  58. environments where the gateway package can't be imported.
  59. THE TWO FAILURES ARE NOT THE SAME, and conflating them disabled the
  60. boundary. A missing gateway module means there is no relay egress to
  61. authorize, so proceeding is correct. A fault INSIDE the guard means
  62. authorization did not happen — and returning None there means "authorized",
  63. so a single runtime bug in the guard silently switched the whole P5(a)
  64. boundary off. Review found this by making the guard raise and watching the
  65. send go through.
  66. So: the import is tolerated, the CALL is not. A guard that cannot answer
  67. refuses, which is the only safe polarity for an authorization check.
  68. """
  69. try:
  70. from gateway.relay.egress import authorize_relay_target
  71. except ImportError as exc:
  72. # ABSENCE ONLY, and absence means the gateway relay module ITSELF is
  73. # missing — `exc.name` says which module was not found. An ImportError
  74. # naming a NESTED dependency is a broken installation, i.e. a fault,
  75. # and returning None here means "authorized". Review probed exactly
  76. # that (`ImportError.name = "gateway.relay.dependency"`) and got an
  77. # authorized verdict, so `except ImportError` alone was still fail-open.
  78. # ABSENCE has one shape and it is checkable: a genuinely missing module
  79. # raises ModuleNotFoundError with `.name` set to the module that was not
  80. # found (verified: `import gateway.relay.x` -> ModuleNotFoundError,
  81. # name="gateway.relay.x"). So a plain ImportError, or a nameless one, is
  82. # an unattributable FAULT — never proof that there is no relay here.
  83. # I previously admitted the nameless case to protect the CLI/cron path;
  84. # that reasoning was wrong, because that path does not produce one.
  85. _missing = getattr(exc, "name", None)
  86. if not isinstance(exc, ModuleNotFoundError) or _missing not in (
  87. "gateway",
  88. "gateway.relay",
  89. "gateway.relay.egress",
  90. ):
  91. logger.exception(
  92. "relay egress module failed to import for %s — refusing the send",
  93. platform_name,
  94. )
  95. return (
  96. f"Refusing to send to relay target '{platform_name}': the egress "
  97. "authorization module could not be loaded, so this destination "
  98. "could not be verified."
  99. )
  100. logger.debug("relay target authorization unavailable", exc_info=True)
  101. return None
  102. except Exception:
  103. logger.exception(
  104. "relay egress module failed to import for %s — refusing the send",
  105. platform_name,
  106. )
  107. return (
  108. f"Refusing to send to relay target '{platform_name}': the egress "
  109. "authorization module could not be loaded, so this destination "
  110. "could not be verified."
  111. )
  112. try:
  113. # ONE SNAPSHOT. `native_token` is the token from the SAME pconfig the
  114. # dispatch below will actually send with. Letting the guard reload
  115. # config independently allowed a transition where authorization saw a
  116. # connector-only setup (exemption granted) while dispatch still held a
  117. # native token and sent the unattested handle itself.
  118. if native_token is _TOKEN_UNSET:
  119. # A caller that forgets the snapshot must NOT silently look like
  120. # "no native token", which would grant the @handle exemption.
  121. return authorize_relay_target(platform_name, chat_id, thread_id)
  122. return authorize_relay_target(
  123. platform_name, chat_id, thread_id, native_token=native_token
  124. )
  125. except Exception:
  126. logger.exception(
  127. "relay target authorization FAILED for %s — refusing the send",
  128. platform_name,
  129. )
  130. return (
  131. f"Refusing to send to relay target '{platform_name}': the egress "
  132. "authorization check failed, so this destination could not be "
  133. "verified. This is a bug — the send was blocked rather than "
  134. "allowed through unchecked."
  135. )
  136. def _handle_react(args, remove=False):
  137. """Attach (``remove=True``: retract) an emoji reaction via the live gateway adapter; no
  138. standalone fallback because reacting needs the adapter's live message-id state."""
  139. target, emoji = args.get("target", ""), (args.get("emoji") or "").strip()
  140. message_id = (args.get("message_id") or "").strip() or None
  141. if not target or (not remove and not emoji):
  142. return tool_error("'target' is required when action='unreact'" if remove
  143. else "Both 'target' and 'emoji' are required when action='react'")
  144. # Platform-native ids (e.g. photon GUIDs) match no parser/directory entry; the adapter validates.
  145. platform_name, chat_id, _thread_id, resolution_error = _resolve_tool_target(target, pass_unresolved_references=True)
  146. if resolution_error:
  147. return tool_error(resolution_error)
  148. platform, err = _platform_enum(platform_name)
  149. if err:
  150. return tool_error(err)
  151. if not chat_id:
  152. try:
  153. from gateway.config import load_gateway_config
  154. chat_id = load_gateway_config().get_home_channel(platform).chat_id
  155. except Exception:
  156. return tool_error(f"No chat specified and no home channel set for {platform_name}. "
  157. f"Use '{platform_name}:chat_id'.")
  158. # P5(a): same egress-authorization floor as the send path — a reaction is
  159. # an outbound act against a named destination, so an unattested relay
  160. # target must be refused here too, not just on `send`.
  161. # The react path has no pconfig snapshot of its own; it dispatches through
  162. # the LIVE adapter below, never through a native token, so the guard does
  163. # its own credential probe here.
  164. _relay_denial = _authorize_relay_target(platform_name, chat_id, _thread_id)
  165. if _relay_denial:
  166. return tool_error(_relay_denial)
  167. _, adapter = _live_adapter(platform)
  168. if adapter is None:
  169. return tool_error(f"Reactions require a live {platform_name} adapter in the running "
  170. "gateway (not available from cron/standalone contexts).")
  171. react_fn = getattr(adapter, "remove_reaction" if remove else "add_reaction", None)
  172. if not callable(react_fn):
  173. return tool_error(f"Platform '{platform_name}' does not support message reactions.")
  174. try:
  175. from model_tools import _run_async
  176. result = _run_async(react_fn(chat_id=chat_id, message_id=message_id, **({} if remove else {"emoji": emoji})))
  177. except Exception as e:
  178. return json.dumps(_error(f"Reaction failed: {e}"))
  179. return json.dumps(result if isinstance(result, dict) else {"success": bool(result)})
  180. def _handle_send(args):
  181. target, message = args.get("target", ""), args.get("message", "")
  182. if not target or not message:
  183. return tool_error("Both 'target' and 'message' are required when action='send'")
  184. # Lone surrogates reach the outbound body via surrogateescape-decoded argv
  185. # (`hermes send` MESSAGE) and crash the UTF-8 marshal inside platform SDK
  186. # request bodies (feishu/lark, #113799). Every send_message caller (model tool
  187. # call, `hermes send`, dashboard console) enters here, so scrub once before the
  188. # media extraction, the session mirror and the platform sender see the text.
  189. # Model output delivered by the gateway/cron is already scrubbed upstream
  190. # (``agent/turn_finalizer.py::finalize_turn``, ``gateway/run.py``).
  191. from agent.message_sanitization import _sanitize_surrogates
  192. message = _sanitize_surrogates(message)
  193. platform_name, chat_id, thread_id, resolution_error = _resolve_tool_target(target)
  194. if resolution_error:
  195. return tool_error(resolution_error)
  196. from tools.interrupt import is_interrupted
  197. if is_interrupted():
  198. return tool_error("Interrupted")
  199. try:
  200. from gateway.config import load_gateway_config
  201. config = load_gateway_config()
  202. except Exception as e:
  203. return json.dumps(_error(f"Failed to load gateway config: {e}"))
  204. platform, pconfig, entry, err = _resolve_platform_config(platform_name, config)
  205. if err:
  206. return tool_error(err)
  207. from gateway.platforms.base import BasePlatformAdapter
  208. # Capture [[as_document]] before extract_media strips it (images keep original bytes via send_document).
  209. force_document_attachments = "[[as_document]]" in message
  210. media_files, cleaned_message = BasePlatformAdapter.extract_media(message)
  211. media_dropped: list = []
  212. media_files = BasePlatformAdapter.filter_media_delivery_paths(media_files, dropped=media_dropped)
  213. mirror_text = cleaned_message.strip() or _describe_media_for_mirror(media_files)
  214. used_home_channel = not chat_id
  215. if used_home_channel:
  216. chat_id, err = _home_chat_id(config, platform, platform_name)
  217. if err:
  218. return tool_error(err)
  219. if duplicate_skip := _maybe_skip_cron_duplicate_send(platform_name, chat_id, thread_id):
  220. return json.dumps(duplicate_skip)
  221. # Slack: resolve user targets to DM channel IDs before sending. _parse_target_ref emits internal
  222. # ``user:U...`` / ``user_name:@handle`` targets; a bare U... id can also arrive from session metadata or
  223. # the home-channel config. All are opened via conversations.open (fixes #19236).
  224. if platform_name == "slack" and chat_id:
  225. chat_id, resolve_err = _slack_dm_chat_id(pconfig, chat_id)
  226. if resolve_err:
  227. return json.dumps(resolve_err)
  228. # POSITION IS LOAD-BEARING — this must stay BELOW Slack user→DM resolution.
  229. # `_parse_target_ref` emits internal pseudo-ids (`user_name:ben`,
  230. # `user:U...`) that no provenance can ever contain, because provenances
  231. # record RESOLVED conversation ids. Authorizing above the resolver compared
  232. # a handle against a set of `D...` ids and refused every Slack DM — a fix
  233. # that caused the outage it was meant to prevent. Pinned by
  234. # test_slack_user_targets_resolve_then_authorize; moving this call back up
  235. # turns those cases red.
  236. # thread_id is part of the DESTINATION: on Discord the thread is the literal
  237. # REST target, so an attested parent must not vouch for an arbitrary thread.
  238. _relay_denial = _authorize_relay_target(platform_name, chat_id, thread_id,
  239. native_token=getattr(pconfig, "token", None))
  240. if _relay_denial:
  241. return tool_error(_relay_denial)
  242. try:
  243. from model_tools import _run_async
  244. # Only custom plugin handlers receive the complete typed request. ``mentions`` is only for platforms
  245. # whose StandaloneSendPolicy declares it (WhatsApp; the CLI rejects it elsewhere); other platforms'
  246. # standalone senders don't accept the kwarg.
  247. handler_args = {"args": args} if entry is not None and entry.send_message_handler is not None else {}
  248. mentions = args.get("mentions")
  249. if mentions and entry is not None and entry.standalone_send is not None and entry.standalone_send.mentions:
  250. handler_args["mentions"] = [mentions] if isinstance(mentions, str) else list(mentions)
  251. result = _run_async(_send_to_platform(platform, pconfig, chat_id, cleaned_message, thread_id=thread_id,
  252. media_files=media_files, force_document=force_document_attachments,
  253. **handler_args))
  254. if isinstance(result, dict) and result.get("success"):
  255. if used_home_channel:
  256. result["note"] = f"Sent to {platform_name} home channel (chat_id: {chat_id})"
  257. if mirror_text and _mirror_sent_message(platform_name, chat_id, mirror_text, thread_id):
  258. result["mirrored"] = True
  259. if media_dropped:
  260. # The text went out but an attachment the caller asked for did not: a script reading
  261. # ``success`` / exit 0 must not book a delivery that never happened (#115908).
  262. result["success"] = False
  263. result["partial_success"] = True
  264. result["error"] = (f"Delivery incomplete: {len(media_dropped)} requested MEDIA attachment(s) "
  265. "dropped before delivery (see media_dropped)")
  266. if isinstance(result, dict) and media_dropped:
  267. result["media_dropped"] = media_dropped
  268. if isinstance(result, dict) and "error" in result:
  269. result["error"] = _sanitize_error_text(result["error"])
  270. return json.dumps(result)
  271. except Exception as e:
  272. return json.dumps(_error(f"Send failed: {e}"))
  273. def _platform_enum(platform_name):
  274. """``(Platform, None)`` or ``(None, error)`` for a platform name."""
  275. from gateway.config import Platform
  276. try:
  277. return Platform(platform_name), None
  278. except (ValueError, KeyError):
  279. return None, f"Unknown platform: {platform_name}"
  280. def _resolve_platform_config(platform_name, config):
  281. """``(platform, pconfig, registry_entry, error)``. Plugin platforms must be registered;
  282. disabled/missing platforms error, except Weixin, which may be configured purely via .env."""
  283. from gateway.config import Platform
  284. from gateway.platform_registry import platform_registry
  285. entry = platform_registry.get(platform_name)
  286. if entry is None and platform_name not in {member.value for member in Platform}:
  287. return None, None, None, unknown_platform_error(platform_name)
  288. platform, err = _platform_enum(platform_name)
  289. if err:
  290. return None, None, None, err
  291. pconfig = config.platforms.get(platform)
  292. if not pconfig or not pconfig.enabled:
  293. pconfig = _weixin_env_pconfig() if platform_name == "weixin" else None
  294. if pconfig is None:
  295. return None, None, None, _not_configured_error(platform_name, platform, entry)
  296. return platform, pconfig, entry, None
  297. def _not_configured_error(platform_name, platform, entry):
  298. """Name the resolved home and what each credential source held, so the user edits the file this
  299. process actually read (a hardcoded ``~/.hermes`` does not exist on a Windows or profile home)."""
  300. from agent.secret_scope import load_env_file
  301. from gateway.config import _getenv
  302. from gateway.config_env import _ENV_ENABLE_CREDENTIALS
  303. from hermes_constants import get_hermes_home
  304. from hermes_cli.config_backend import config_exists
  305. home = get_hermes_home()
  306. env_names = list(_ENV_ENABLE_CREDENTIALS.get(platform) or (entry.required_env if entry else ()))
  307. names = "/".join(env_names) or "credentials"
  308. env_path, config_path = home / ".env", home / "config.yaml"
  309. dotenv_keys = load_env_file(env_path)
  310. dotenv_state = (f"{names} present" if any(n in dotenv_keys for n in env_names) else f"no {names}") \
  311. if env_path.exists() else "missing"
  312. try:
  313. from hermes_cli.config_effective import load_user_config_effective
  314. user_config = load_user_config_effective(config_path) or {}
  315. block = user_config.get("platforms", {}).get(platform_name)
  316. except Exception:
  317. user_config, block = {}, None
  318. if not config_exists(config_path):
  319. config_state = "missing"
  320. elif not isinstance(block, dict):
  321. config_state = f"no platforms.{platform_name} block"
  322. elif block.get("enabled") is False:
  323. config_state = f"platforms.{platform_name}.enabled: false"
  324. else:
  325. config_state = f"platforms.{platform_name} has no token"
  326. env_state = f"{names} set" if any(_getenv(n) for n in env_names) else f"{names} unset"
  327. msg = (f"Platform '{platform_name}' is not configured. Looked in: {env_path} ({dotenv_state}), "
  328. f"{config_path} ({config_state}), environment ({env_state}), "
  329. f"external secret sources ({_secret_sources_state(user_config)}).")
  330. # The gateway can hold a token only in its own process environment; a fresh CLI cannot see it. A
  331. # gateway started from the default root (the reporter's shell had HERMES_HOME=<root>/profiles/<p>)
  332. # never reads this profile's .env at all.
  333. try:
  334. from gateway.status import read_runtime_status, runtime_status_pid_is_live
  335. from hermes_constants import get_default_hermes_root, hermes_home_key
  336. root = get_default_hermes_root()
  337. gateways = [(home, read_runtime_status())]
  338. if hermes_home_key(root) != hermes_home_key(home):
  339. gateways.append((root, read_runtime_status(root / "gateway_state.json")))
  340. for gw_home, record in gateways:
  341. state = ((record or {}).get("platforms") or {}).get(platform_name, {}).get("state")
  342. if state != "connected" or "present" in dotenv_state or not runtime_status_pid_is_live(record):
  343. continue
  344. msg += f" A gateway (pid {record.get('pid')}) running from {gw_home} has {platform_name} connected"
  345. msg += (f", so its credentials live only in that process's environment; add {names} to {env_path}."
  346. if gw_home is home else
  347. f"; this shell is scoped to profile home {home} whose .env has no {names}.")
  348. except Exception:
  349. pass
  350. return msg
  351. def _secret_sources_state(user_config):
  352. """``name: enabled|disabled`` for every registered secret source with a ``secrets.<name>`` section,
  353. or ``none configured``; names only, never values."""
  354. try:
  355. from agent.secret_sources.registry import list_sources
  356. secrets_cfg = user_config.get("secrets") if isinstance(user_config.get("secrets"), dict) else {}
  357. states = [f"{s.name}: {'enabled' if s.is_enabled(secrets_cfg[s.name]) else 'disabled'}"
  358. for s in list_sources() if isinstance(secrets_cfg.get(s.name), dict)]
  359. except Exception:
  360. states = []
  361. return ", ".join(states) or "none configured"
  362. def _home_chat_id(config, platform, platform_name):
  363. """``(home chat_id, None)`` or ``(None, actionable error)``; Weixin also honours WEIXIN_HOME_CHANNEL."""
  364. home = config.get_home_channel(platform)
  365. if home:
  366. return home.chat_id, None
  367. # Home channel is a per-profile target like the token beside it: a raw environ read would post a
  368. # multiplexed secondary's message into the default profile's Weixin chat.
  369. wx_home = (get_secret("WEIXIN_HOME_CHANNEL", "") or "").strip() if platform_name == "weixin" else ""
  370. if wx_home:
  371. return wx_home, None
  372. home_env = _HOME_CHANNEL_ENV_OVERRIDES.get(platform_name, f"{platform_name.upper()}_HOME_CHANNEL")
  373. return None, (f"No home channel set for {platform_name} to determine where to send the message. "
  374. f"Either specify a channel directly with '{platform_name}:CHANNEL_NAME', "
  375. f"or set a home channel via: hermes config set {home_env} <channel_id>")
  376. def _slack_dm_chat_id(pconfig, chat_id):
  377. """Open Slack user targets (``user:``/``user_name:`` from the parser, or a bare U... id from
  378. session metadata / home-channel config) as DM conversations. ``(chat_id, None)`` or ``(None, error_dict)``."""
  379. dm_target = f"user:{chat_id}" if chat_id.startswith("U") and _SLACK_USER_ID_RE.fullmatch(chat_id) else chat_id
  380. if not dm_target.startswith(("user:", "user_name:")):
  381. return chat_id, None
  382. from model_tools import _run_async
  383. return _run_async(_resolve_slack_user_target(pconfig.token, dm_target))
  384. def _mirror_sent_message(platform_name, chat_id, mirror_text, thread_id):
  385. """Best-effort mirror of the sent message into the target's gateway session."""
  386. try:
  387. from gateway.mirror import mirror_to_session
  388. from gateway.session_context import get_session_env
  389. return bool(mirror_to_session(
  390. platform_name, chat_id, mirror_text, thread_id=thread_id,
  391. source_label=get_session_env("HERMES_SESSION_PLATFORM", "cli"),
  392. user_id=get_session_env("HERMES_SESSION_USER_ID", "") or None))
  393. except Exception:
  394. return False
  395. def _weixin_env_pconfig():
  396. """Synthesize a Weixin PlatformConfig from .env secrets, or None."""
  397. wx_token = get_secret("WEIXIN_TOKEN", "").strip()
  398. wx_account = get_secret("WEIXIN_ACCOUNT_ID", "").strip()
  399. if not (wx_token and wx_account):
  400. return None
  401. from gateway.config import PlatformConfig
  402. return PlatformConfig(enabled=True, token=wx_token, extra={
  403. "account_id": wx_account, "base_url": get_secret("WEIXIN_BASE_URL", "").strip(),
  404. "cdn_base_url": get_secret("WEIXIN_CDN_BASE_URL", "").strip()})
  405. def _describe_media_for_mirror(media_files):
  406. """Return a human-readable mirror summary when a message only contains media."""
  407. if not media_files:
  408. return ""
  409. if len(media_files) != 1:
  410. return f"[Sent {len(media_files)} media attachments]"
  411. media_path, is_voice = media_files[0]
  412. ext = os.path.splitext(media_path)[1].lower()
  413. if is_voice and ext in _VOICE_EXTS:
  414. return "[Sent voice message]"
  415. kind = next((k for exts, k in ((_IMAGE_EXTS, "image"), (_VIDEO_EXTS, "video"), (_AUDIO_EXTS, "audio"))
  416. if ext in exts), "document")
  417. return f"[Sent {kind} attachment]"
  418. def _maybe_skip_cron_duplicate_send(platform_name: str, chat_id: str, thread_id: str | None):
  419. """Skip redundant cron send_message calls when the scheduler will auto-deliver there."""
  420. from gateway.session_context import get_session_env
  421. auto_platform = get_session_env("HERMES_CRON_AUTO_DELIVER_PLATFORM", "").strip().lower()
  422. auto_chat_id = get_session_env("HERMES_CRON_AUTO_DELIVER_CHAT_ID", "").strip()
  423. if not (auto_platform and auto_chat_id and auto_platform == platform_name and auto_chat_id == str(chat_id)
  424. and (get_session_env("HERMES_CRON_AUTO_DELIVER_THREAD_ID", "").strip() or None) == thread_id):
  425. return None
  426. target_label = f"{platform_name}:{chat_id}" + (f":{thread_id}" if thread_id is not None else "")
  427. return {"success": True, "skipped": True, "reason": "cron_auto_delivery_duplicate_target", "target": target_label,
  428. "note": (f"Skipped send_message to {target_label}. This cron job will already auto-deliver "
  429. "its final response to that same target. Put the intended user-facing content in "
  430. "your final response instead, or use a different target if you want an additional message.")}
  431. def _bounded_send_error(detail, max_chars=900):
  432. """Bound untrusted adapter/plugin error detail returned by send_message."""
  433. text = str(detail or "send failed")
  434. return text if len(text) <= max_chars else f"{text[: max_chars - 3]}..."
  435. async def _send_live_adapter_media(adapter, chat_id, message, media_files, *, thread_id=None, metadata=None,
  436. force_document=False):
  437. """Deliver text and every media descriptor through adapter media APIs; adapters that only
  438. inherit the BasePlatformAdapter stub for a kind are unsupported, not no-op'd."""
  439. caption, separate_text = _media_caption_split(message, media_files, max_caption_len=_DEFAULT_CAPTION_LIMIT)
  440. last_result = None
  441. if separate_text and separate_text.strip():
  442. last_result = await adapter.send(chat_id=chat_id, content=separate_text, metadata=metadata)
  443. if not last_result.success:
  444. return {"error": f"Adapter send failed: {_bounded_send_error(last_result.error)}"}
  445. from gateway.platforms.base import BasePlatformAdapter
  446. total = len(media_files)
  447. unconfirmed = []
  448. for index, descriptor in enumerate(media_files):
  449. media_path = descriptor[0] if isinstance(descriptor, (list, tuple)) and descriptor else None
  450. if not isinstance(media_path, str) or not media_path:
  451. return {"error": f"Adapter media send failed: invalid media descriptor {index + 1}/{total}"}
  452. is_voice = len(descriptor) > 1 and bool(descriptor[1])
  453. if not os.path.exists(media_path):
  454. return {"error": f"Adapter media send failed: media file {index + 1}/{total} was not found"}
  455. ext = os.path.splitext(media_path)[1].lower()
  456. method_name, media_kind = _adapter_media_method(ext, is_voice or ext in _AUDIO_EXTS, force_document)
  457. adapter_method = getattr(type(adapter), method_name, None)
  458. if adapter_method is None or adapter_method is getattr(BasePlatformAdapter, method_name):
  459. return {"error": (f"Live adapter does not implement native {media_kind} delivery; "
  460. f"media file {index + 1}/{total} was not sent")}
  461. try:
  462. last_result = await getattr(adapter, method_name)(
  463. chat_id, media_path, caption=caption if index == 0 else None, reply_to=thread_id, metadata=metadata)
  464. except asyncio.CancelledError:
  465. raise
  466. except Exception as exc:
  467. detail = _bounded_send_error(exc)
  468. else:
  469. if last_result.success:
  470. raw = last_result.raw_response
  471. if isinstance(raw, dict) and raw.get("ambiguous"):
  472. unconfirmed.append(index + 1)
  473. continue
  474. detail = _bounded_send_error(last_result.error or "media send failed")
  475. return {"error": f"Adapter media send failed after {index}/{total} files: {detail}"}
  476. if last_result is None:
  477. return {"error": _NO_DELIVERABLE}
  478. result = {"success": True, "message_id": last_result.message_id, "media_delivered": True}
  479. if unconfirmed:
  480. # Frame sent, ack lost: possibly delivered. A failure here would invite a duplicate re-send.
  481. result["delivery_unconfirmed"] = (
  482. f"media file(s) {unconfirmed} of {total} were sent but the platform never confirmed "
  483. "receipt; they may already be in the chat, so do not resend them")
  484. return result
  485. async def _dispatch_on_gateway_loop(runner, make_coro, log_message):
  486. """Await ``make_coro()`` on the gateway's loop: adapter.send() uses queues/tasks bound to it,
  487. so awaiting from another loop (the tool worker thread) deadlocks."""
  488. gateway_loop = getattr(runner, "_gateway_loop", None)
  489. if gateway_loop is None or asyncio.get_running_loop() is gateway_loop:
  490. return await make_coro() # same loop / no gateway loop (CLI, tests)
  491. if not gateway_loop.is_running():
  492. return {"error": "Gateway loop is not running; cannot dispatch adapter send"}
  493. from agent.async_utils import safe_schedule_threadsafe
  494. fut = safe_schedule_threadsafe(make_coro(), gateway_loop, logger=logger, log_message=log_message)
  495. if fut is None:
  496. return {"error": "Gateway loop unavailable for send dispatch"}
  497. # shield: a cancelled caller must not cancel the enqueued send (a retry would duplicate it).
  498. # No timeout: the adapter and outer _run_async bound the wait.
  499. return await asyncio.shield(asyncio.wrap_future(fut))
  500. async def _send_via_adapter(platform, pconfig, chat_id, chunk, *, thread_id=None, media_files=None,
  501. force_document=False):
  502. """Live in-process gateway adapter first, else the plugin's ``standalone_sender_fn`` (cron),
  503. else an error naming both; media uses the adapter's native media APIs under the same rules."""
  504. platform_name = platform.value if hasattr(platform, "value") else str(platform)
  505. runner, adapter = _live_adapter(platform)
  506. if adapter is not None:
  507. try:
  508. metadata = {**({"thread_id": thread_id} if thread_id else {}),
  509. **({"publish_topic": chat_id} if platform_name == "ntfy" and chat_id else {})} or None
  510. if media_files: # always a dict result, returned as-is below
  511. make_coro = lambda: _send_live_adapter_media(
  512. adapter, chat_id, chunk, media_files, thread_id=thread_id, metadata=metadata,
  513. force_document=force_document)
  514. else:
  515. make_coro = lambda: adapter.send(chat_id=chat_id, content=chunk, metadata=metadata)
  516. result = await _dispatch_on_gateway_loop(
  517. runner, make_coro, f"send_message: failed to schedule{' media send' if media_files else ''} on gateway loop")
  518. except asyncio.CancelledError:
  519. raise
  520. except Exception as e:
  521. return {"error": f"Plugin platform send failed: {_bounded_send_error(e)}"}
  522. if isinstance(result, dict):
  523. return result
  524. if result.success:
  525. return {"success": True, "message_id": result.message_id}
  526. return {"error": f"Adapter send failed: {_bounded_send_error(result.error)}"}
  527. try:
  528. # Discover first: a fresh process (cron/CLI) has not registered plugin platforms yet.
  529. sender, _ = _plugin_standalone_sender(platform_name)
  530. except Exception:
  531. sender = None
  532. if sender is None:
  533. return {"error": (f"No live adapter for platform '{platform_name}'. Is the gateway running with this platform "
  534. f"connected? For out-of-process delivery (e.g. cron in a separate process), the platform "
  535. f"plugin must register a standalone_sender_fn on its PlatformEntry.")}
  536. try:
  537. result = await sender(pconfig, chat_id, chunk, thread_id=thread_id, media_files=media_files,
  538. force_document=force_document)
  539. except asyncio.CancelledError:
  540. raise
  541. except Exception as e:
  542. logger.debug("Plugin standalone send for %s raised", platform_name, exc_info=True)
  543. return {"error": f"Plugin standalone send failed: {_bounded_send_error(e)}"}
  544. if isinstance(result, dict) and (result.get("success") or result.get("error")):
  545. return {**result, "error": _bounded_send_error(result["error"])} if result.get("error") else result
  546. return {"error": (f"Plugin standalone send for '{platform_name}' returned an invalid result: "
  547. f"expected a dict with 'success' or 'error' keys, got {type(result).__name__}")}
  548. async def _send_chunks(chunks, send_one):
  549. """``send_one(chunk, is_last)`` in order; stop at the first error dict, else last result."""
  550. result = None
  551. # --- Matrix: route ALL sends through the native adapter so text is encrypted in E2EE rooms too (issue:
  552. # text-only sends arrived with a red padlock because they took the raw-HTTP standalone path). The
  553. # adapter reuses the live gateway's E2EE session when available (#46310) and falls back to an
  554. # encryption-aware ephemeral adapter for standalone/cron. ---
  555. for i, chunk in enumerate(chunks):
  556. result = await send_one(chunk, i == len(chunks) - 1)
  557. if isinstance(result, dict) and result.get("error"):
  558. break
  559. return result
  560. def _platform_max_length(platform):
  561. """Chunking limit: the registry's ``max_message_length`` for plugins, else None (no chunking)."""
  562. try:
  563. from gateway.platform_registry import platform_registry
  564. entry = platform_registry.get(platform.value)
  565. return entry.max_message_length if entry and entry.max_message_length > 0 else None
  566. except Exception:
  567. return None
  568. def _standalone_send_policy(platform_name):
  569. """The plugin's ``StandaloneSendPolicy`` (None = generic routing). Cron calls
  570. ``_send_to_platform`` directly, so discover first when the name is not yet registered
  571. (idempotent manifest scan; only this platform's adapter is materialized)."""
  572. from gateway.platform_registry import platform_registry
  573. if not platform_registry.is_registered(platform_name):
  574. from hermes_cli.plugins import discover_plugins
  575. discover_plugins()
  576. entry = platform_registry.get(platform_name)
  577. return entry.standalone_send if entry is not None else None
  578. async def _send_plugin_standalone(platform_name, pconfig, chat_id, message, chunks, media_files, *, thread_id,
  579. max_len, force_document, mentions=None):
  580. """Chunked send through a plugin's standalone_sender_fn; one captionable file + short text
  581. rides as the media caption. WhatsApp re-pings recipients on every message that carries
  582. ``mentions``, so only the first payload of a logical send gets them."""
  583. from gateway.platforms.send_targets import StandaloneSendPolicy
  584. policy = _standalone_send_policy(platform_name) or StandaloneSendPolicy()
  585. sender, err = _plugin_standalone_sender(platform_name, label=policy.label or None)
  586. if err:
  587. return err
  588. extra = {"force_document": force_document} if policy.forward_force_document else {}
  589. first_only = {"mentions": mentions} if mentions else {}
  590. empty_media = [] if policy.empty_list_between_chunks else None
  591. if policy.captionable:
  592. # Cap on the platform's own message limit so the caption is deliverable.
  593. caption, _ = _media_caption_split(message, media_files, max_caption_len=(max_len or _DEFAULT_CAPTION_LIMIT))
  594. if caption is not None:
  595. return await sender(pconfig, chat_id, "", thread_id=thread_id, media_files=media_files,
  596. caption=caption, **extra, **first_only)
  597. def send_one(chunk, is_last):
  598. kwargs = {**extra, **first_only}
  599. first_only.clear()
  600. return sender(pconfig, chat_id, chunk, thread_id=thread_id,
  601. media_files=media_files if is_last else empty_media, **kwargs)
  602. return await _send_chunks(chunks, send_one)
  603. def _via_adapter_route(p, pc, cid, chunk, media, tid, fd):
  604. return _send_via_adapter(p, pc, cid, chunk, thread_id=tid, media_files=media, force_document=fd)
  605. # Native-media chunked routes for built-in platforms; media rides on the final chunk, non-final
  606. # chunks get the sentinel. platform -> (media required, sentinel, sender(platform, pconfig,
  607. # chat_id, chunk, media, thread_id, force_document)). Matrix: ALL sends use the native adapter
  608. # (E2EE text). WeCom: media needs the running gateway. Slack text: live adapter (multi-workspace, ignored_channels gates) else the
  609. # plugin's standalone sender. Names resolve at call time so tests can monkeypatch the senders.
  610. _CHUNKED_ROUTES = {
  611. "matrix": (False, [], lambda p, pc, cid, chunk, media, tid, fd: _send_matrix_via_adapter(
  612. pc, cid, chunk, media_files=media, thread_id=tid)),
  613. "slack": (False, [], _via_adapter_route),
  614. "wecom": (True, None, _via_adapter_route)}
  615. _MEDIA_PLATFORMS_NOTE = "telegram, discord, matrix, weixin, signal, yuanbao, feishu, whatsapp, slack and qqbot"
  616. async def _send_to_platform(platform, pconfig, chat_id, message, thread_id=None, media_files=None,
  617. force_document=False, mentions=None, args=None):
  618. """Route to the platform sender, chunking long text with the adapters' splitter. Order matters:
  619. Weixin first (its native helper must not be blocked by unrelated optional imports such as
  620. lark-oapi), Telegram (chunks itself), plugin standalone media, native chunked, generic text."""
  621. from gateway.config import Platform
  622. platform_name = platform.value if hasattr(platform, "value") else str(platform)
  623. media_files = media_files or []
  624. if platform_name == "weixin": # plugin standalone sender only: no other plugin's import can block it
  625. return await _send_plugin_standalone(platform_name, pconfig, chat_id, message, [message], media_files,
  626. thread_id=thread_id, max_len=None, force_document=force_document)
  627. # Telegram chunks internally on the *formatted* text (escaping inflates length).
  628. if platform == Platform.TELEGRAM:
  629. return await _send_telegram(
  630. pconfig.token, chat_id, message, media_files=media_files, thread_id=thread_id, force_document=force_document,
  631. disable_link_previews=bool(getattr(pconfig, "extra", {}) and pconfig.extra.get("disable_link_previews")))
  632. from gateway.platforms.base import BasePlatformAdapter
  633. max_len = _platform_max_length(platform)
  634. chunks = BasePlatformAdapter.truncate_message(message, max_len) if max_len else [message]
  635. policy = _standalone_send_policy(platform_name)
  636. if policy is not None and (policy.all_sends or (policy.mentions and mentions) or (media_files and policy.media)):
  637. return await _send_plugin_standalone(platform_name, pconfig, chat_id, message, chunks, media_files,
  638. thread_id=thread_id, max_len=max_len, force_document=force_document,
  639. mentions=mentions)
  640. route = _CHUNKED_ROUTES.get(platform_name)
  641. if route is not None and (media_files or not route[0]):
  642. _, empty_media, sender = route
  643. return await _send_chunks(chunks, lambda chunk, is_last: sender(
  644. platform, pconfig, chat_id, chunk, media_files if is_last else empty_media, thread_id, force_document))
  645. # Generic path: text only. Buzz delivers media natively via _send_via_adapter, so no warning.
  646. warning = None
  647. if media_files and platform_name != "buzz":
  648. if not message.strip():
  649. return {"error": (f"send_message MEDIA delivery is currently only supported for {_MEDIA_PLATFORMS_NOTE}; "
  650. f"target {platform_name} had only media attachments")}
  651. warning = (f"MEDIA attachments were omitted for {platform_name}; "
  652. f"native send_message media delivery is currently only supported for {_MEDIA_PLATFORMS_NOTE}")
  653. if policy is not None and policy.text_direct:
  654. # Text-only straight to the plugin's standalone sender (media dropped with the warning above).
  655. send_one = lambda chunk, is_last: _registry_standalone_send(platform_name, pconfig, chat_id, chunk, thread_id)
  656. else:
  657. from gateway.platform_registry import platform_registry
  658. entry = platform_registry.get(platform_name)
  659. if entry is not None and entry.send_message_handler is not None:
  660. # Custom handler receives the full typed request once (not per chunk).
  661. try:
  662. import inspect
  663. result = entry.send_message_handler(args or {}, chat_id, platform_name, pconfig)
  664. return await result if inspect.isawaitable(result) else result
  665. except Exception as e:
  666. return {"error": f"Plugin send_message handler failed: {e}"}
  667. # Plugin platform: live gateway adapter if available, else standalone_sender_fn.
  668. send_one = lambda chunk, is_last: _via_adapter_route(
  669. platform, pconfig, chat_id, chunk, media_files if is_last else [], thread_id, force_document)
  670. last_result = await _send_chunks(chunks, send_one)
  671. if (warning and isinstance(last_result, dict) and last_result.get("success")
  672. and not last_result.get("media_delivered")):
  673. last_result["warnings"] = [*last_result.get("warnings", []), warning]
  674. return last_result