adapter.py 30 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619
  1. """IRC Platform Adapter for Hermes Agent — stdlib asyncio only, zero external dependencies.
  2. config.yaml ``gateway.platforms.irc.extra`` keys: server, port (6697), nickname (hermes-bot), channel,
  3. use_tls (true), server_password, nickserv_password, allowed_users ([] = allow all), max_message_length (450).
  4. Env vars override config.yaml: IRC_SERVER, IRC_PORT, IRC_NICKNAME, IRC_CHANNEL, IRC_USE_TLS,
  5. IRC_SERVER_PASSWORD, IRC_NICKSERV_PASSWORD.
  6. """
  7. import asyncio
  8. import datetime
  9. import contextlib
  10. import logging
  11. import re
  12. import ssl
  13. import time
  14. import uuid
  15. from typing import Any, Dict, List, Optional
  16. from gateway.platforms._shared import (
  17. coerce_port, get_scoped_secret as _get_scoped_secret, seed_extra_from_env as _seed_extra_from_env, send_error
  18. )
  19. from agent.i18n import t
  20. from gateway.platforms.base import BasePlatformAdapter, SendResult
  21. from gateway.platforms.helpers import cancel_task
  22. from gateway.platforms.event import MessageEvent, MessageType
  23. from gateway.config import Platform
  24. logger = logging.getLogger(__name__)
  25. _TRUTHY = {"1", "true", "yes"}
  26. _EOF = object() # _standalone_send: server closed the connection
  27. _MARKDOWN_RULES = (
  28. (r"\*\*(.+?)\*\*", r"\1"), # bold
  29. (r"__(.+?)__", r"\1"),
  30. (r"\*(.+?)\*", r"\1"), # italic
  31. (r"(?<!\w)_(.+?)_(?!\w)", r"\1"),
  32. (r"`(.+?)`", r"\1"), # inline code
  33. (r"```\w*\n?", ""), # code fences
  34. (r"!\[([^\]]*)\]\(([^)]+)\)", r"\2"), # images → url (must precede links)
  35. (r"\[([^\]]+)\]\(([^)]+)\)", r"\1 (\2)"), # links → text (url)
  36. )
  37. # ── IRC protocol helpers ─────────────────────────────────────────────────────
  38. def _parse_irc_message(raw: str) -> dict:
  39. """Parse a raw IRC line into ``{"prefix", "command", "params"}``."""
  40. prefix, trailing = "", ""
  41. if raw.startswith(":"):
  42. prefix, _, raw = raw[1:].partition(" ")
  43. if " :" in raw:
  44. raw, trailing = raw.split(" :", 1)
  45. parts = raw.split()
  46. params = parts[1:] if len(parts) > 1 else []
  47. if trailing:
  48. params.append(trailing)
  49. return {"prefix": prefix, "command": parts[0] if parts else "", "params": params}
  50. def _extract_nick(prefix: str) -> str:
  51. """Extract nickname from IRC prefix (nick!user@host)."""
  52. return prefix.split("!")[0]
  53. def _ms_id() -> str:
  54. return str(int(time.time() * 1000))
  55. def _env_or_extra(extra: dict, env: str, key: str, default: Any = "") -> Any:
  56. """Env var overrides config.yaml ``extra``."""
  57. return _get_scoped_secret(env) or extra.get(key, default)
  58. def _server_channel(config) -> tuple:
  59. extra = getattr(config, "extra", {}) or {}
  60. return _env_or_extra(extra, "IRC_SERVER", "server"), _env_or_extra(extra, "IRC_CHANNEL", "channel")
  61. def _chunk_paragraph(paragraph: str, limit: int) -> list[str]:
  62. """Split one line into UTF-8 chunks of at most ``limit`` bytes, preferring space boundaries."""
  63. chunks: list[str] = []
  64. while paragraph:
  65. if len(paragraph.encode("utf-8")) <= limit:
  66. chunks.append(paragraph)
  67. break
  68. # Binary search for the largest character prefix that fits within limit
  69. low, high, split_at = 1, len(paragraph), 0
  70. while low <= high:
  71. mid = (low + high) // 2
  72. if len(paragraph[:mid].encode("utf-8")) <= limit:
  73. split_at, low = mid, mid + 1
  74. else:
  75. high = mid - 1
  76. space = paragraph.rfind(" ", 0, split_at)
  77. if space > split_at // 3:
  78. split_at = space
  79. chunks.append(paragraph[:split_at].rstrip())
  80. paragraph = paragraph[split_at:].lstrip()
  81. return chunks
  82. def _privmsg_budget(target: str) -> int:
  83. """Payload bytes left in a 510-byte line after ``PRIVMSG <target> :`` and CRLF."""
  84. return 510 - (len(f"PRIVMSG {target} :".encode()) + 2)
  85. def _split_lines(paragraphs, limit: int) -> list[str]:
  86. return [chunk for paragraph in paragraphs for chunk in _chunk_paragraph(paragraph, limit)]
  87. def _encode_line(line: str) -> bytes:
  88. return (line + "\r\n").encode("utf-8")
  89. def _ssl_ctx(use_tls: bool) -> Optional[ssl.SSLContext]:
  90. return ssl.create_default_context() if use_tls else None
  91. # ── IRC Adapter ──────────────────────────────────────────────────────────────
  92. class IRCAdapter(BasePlatformAdapter):
  93. """Async IRC adapter implementing the BasePlatformAdapter interface."""
  94. serial_receive_loop = True # the read loop awaits each PRIVMSG before reading the next line
  95. def __init__(self, config, **kwargs):
  96. super().__init__(config=config, platform=Platform("irc"))
  97. extra = getattr(config, "extra", {}) or {}
  98. self.server = _env_or_extra(extra, "IRC_SERVER", "server")
  99. self.port = coerce_port(_env_or_extra(extra, "IRC_PORT", "port", 6697), 6697)
  100. self.nickname = _env_or_extra(extra, "IRC_NICKNAME", "nickname", "hermes-bot")
  101. self.channel = _env_or_extra(extra, "IRC_CHANNEL", "channel")
  102. _use_tls_raw = _get_scoped_secret("IRC_USE_TLS")
  103. self.use_tls = _use_tls_raw.lower() in _TRUTHY if _use_tls_raw else extra.get("use_tls", True)
  104. self.server_password = _env_or_extra(extra, "IRC_SERVER_PASSWORD", "server_password")
  105. self.nickserv_password = _env_or_extra(extra, "IRC_NICKSERV_PASSWORD", "nickserv_password")
  106. self.allowed_users: list = extra.get("allowed_users", [])
  107. # IRC nicks are case-insensitive — normalise for lookups
  108. self._allowed_users_lower: set = {u.lower() for u in self.allowed_users if isinstance(u, str)}
  109. max_msg = extra.get("max_message_length")
  110. if max_msg is None:
  111. with contextlib.suppress(Exception):
  112. from gateway.platform_registry import platform_registry
  113. max_msg = platform_registry.get("irc").max_message_length
  114. self.max_message_length = int(max_msg or 450)
  115. self._reader: Optional[asyncio.StreamReader] = None
  116. self._writer: Optional[asyncio.StreamWriter] = None
  117. self._recv_task: Optional[asyncio.Task] = None
  118. self._current_nick = self.nickname
  119. self._registered = False # IRC registration complete
  120. self._registration_event = asyncio.Event()
  121. @property
  122. def name(self) -> str:
  123. return "IRC"
  124. def _fail(self, code: str, message: str, *, retryable: bool) -> bool:
  125. self._set_fatal_error(code, message, retryable=retryable)
  126. return False
  127. async def connect(self, *, is_reconnect: bool = False) -> bool:
  128. """Connect to the IRC server, register, and join the channel."""
  129. if not self.server or not self.channel:
  130. logger.error("IRC: server and channel must be configured")
  131. return self._fail("config_missing", "IRC_SERVER and IRC_CHANNEL must be set", retryable=False)
  132. # Prevent two profiles from using the same IRC identity
  133. if not self._acquire_platform_lock("irc", f"{self.server}:{self.nickname}", f"IRC identity {self.nickname}@{self.server}"):
  134. return False
  135. try:
  136. self._reader, self._writer = await asyncio.wait_for(
  137. asyncio.open_connection(self.server, self.port, ssl=_ssl_ctx(self.use_tls)), timeout=30.0)
  138. except Exception as e:
  139. logger.error("IRC: failed to connect to %s:%s — %s", self.server, self.port, e)
  140. return self._fail("connect_failed", str(e), retryable=True)
  141. if self.server_password:
  142. await self._send_raw(f"PASS {self.server_password}")
  143. await self._send_raw(f"NICK {self.nickname}")
  144. await self._send_raw(f"USER {self.nickname} 0 * :Hermes Agent")
  145. self._recv_task = asyncio.create_task(self._receive_loop())
  146. try: # wait for registration (001 RPL_WELCOME)
  147. await asyncio.wait_for(self._registration_event.wait(), timeout=30.0)
  148. except TimeoutError:
  149. logger.error("IRC: registration timed out")
  150. await self.disconnect()
  151. return self._fail("registration_timeout", "IRC server did not send RPL_WELCOME", retryable=True)
  152. if self.nickserv_password:
  153. await self._send_raw(f"PRIVMSG NickServ :IDENTIFY {self.nickserv_password}")
  154. await asyncio.sleep(2) # Give NickServ time to process
  155. await self._send_raw(f"JOIN {self.channel}")
  156. self._mark_connected()
  157. logger.info("IRC: connected to %s:%s as %s, joined %s", self.server, self.port, self._current_nick, self.channel)
  158. self._wire_plugin_handlers(None)
  159. return True
  160. async def disconnect(self) -> None:
  161. """Quit and close the connection."""
  162. with contextlib.suppress(Exception):
  163. self._release_platform_lock()
  164. self._mark_disconnected()
  165. if self._writer and not self._writer.is_closing():
  166. with contextlib.suppress(Exception):
  167. await self._send_raw("QUIT :" + t("platform.irc.quit_message"))
  168. await asyncio.sleep(0.5)
  169. with contextlib.suppress(Exception):
  170. self._writer.close()
  171. await self._writer.wait_closed()
  172. await cancel_task(self._recv_task)
  173. self._reader = None
  174. self._writer = None
  175. self._registered = False
  176. self._registration_event.clear()
  177. async def send(self, chat_id: str, content: str, reply_to: Optional[str] = None,
  178. metadata: Optional[dict[str, Any]] = None):
  179. if not self._writer or self._writer.is_closing():
  180. return SendResult(success=False, error="Not connected")
  181. for line in self._split_message(content, chat_id):
  182. try:
  183. await self._send_raw(f"PRIVMSG {chat_id} :{line}")
  184. await asyncio.sleep(0.3) # Basic flood protection
  185. except Exception as e:
  186. return SendResult(success=False, error=str(e))
  187. return SendResult(success=True, message_id=_ms_id())
  188. async def send_typing(self, chat_id: str, metadata=None) -> None:
  189. """IRC has no typing indicator — no-op."""
  190. async def get_chat_info(self, chat_id: str) -> dict[str, Any]:
  191. return {"name": chat_id, "type": "group" if chat_id.startswith(("#", "&")) else "dm"}
  192. def _split_message(self, content: str, target: str) -> list[str]:
  193. """Split a long message into IRC-safe chunks (510-byte line limit minus PRIVMSG overhead)."""
  194. paragraphs = [p for p in self._strip_markdown(content).split("\n") if p.strip()]
  195. return _split_lines(paragraphs, min(self.max_message_length, _privmsg_budget(target))) or [""]
  196. @staticmethod
  197. def _strip_markdown(text: str) -> str:
  198. """Convert basic markdown to plain text for IRC."""
  199. for pattern, repl in _MARKDOWN_RULES:
  200. text = re.sub(pattern, repl, text)
  201. return text
  202. async def _send_raw(self, line: str) -> None:
  203. """Send a raw IRC protocol line."""
  204. if not self._writer or self._writer.is_closing():
  205. return
  206. self._writer.write(_encode_line(line))
  207. await self._writer.drain()
  208. async def _receive_loop(self) -> None:
  209. """Main receive loop — reads lines and dispatches them."""
  210. buffer = b""
  211. try:
  212. while self._reader and not self._reader.at_eof():
  213. if not (data := await self._reader.read(4096)):
  214. break
  215. buffer += data
  216. while b"\r\n" in buffer:
  217. line, buffer = buffer.split(b"\r\n", 1)
  218. try:
  219. await self._handle_line(line.decode("utf-8", errors="replace"))
  220. except Exception as e:
  221. logger.warning("IRC: error handling line: %s", e)
  222. except asyncio.CancelledError:
  223. raise
  224. except Exception as e:
  225. logger.error("IRC: receive loop error: %s", e)
  226. finally:
  227. if self.is_connected:
  228. logger.warning("IRC: connection lost, marking disconnected")
  229. self._set_fatal_error("connection_lost", "IRC connection closed unexpectedly", retryable=True)
  230. await self._notify_fatal_error()
  231. async def _handle_line(self, raw: str) -> None:
  232. """Dispatch a single IRC protocol line."""
  233. msg = _parse_irc_message(raw)
  234. command, params = msg["command"], msg["params"]
  235. if command == "PING":
  236. await self._send_raw(f"PONG :{params[0] if params else ''}")
  237. elif command == "001": # RPL_WELCOME — registration complete
  238. self._registered = True
  239. self._registration_event.set()
  240. if params:
  241. self._current_nick = params[0] # server may confirm our nick
  242. elif command == "433": # ERR_NICKNAMEINUSE — retry: hermes_, hermes_1, hermes_2...
  243. if suffix_match := re.search(r"_(\d+)$", self._current_nick):
  244. self._current_nick = f"{self.nickname.rstrip('_0123456789')}_{int(suffix_match.group(1)) + 1}"
  245. else:
  246. self._current_nick = self.nickname + ("_" if self._current_nick == self.nickname else "_1")
  247. await self._send_raw(f"NICK {self._current_nick}")
  248. elif command == "PRIVMSG" and len(params) >= 2:
  249. await self._handle_privmsg(_extract_nick(msg["prefix"]), params[0], params[1])
  250. elif command == "NICK" and params and _extract_nick(msg["prefix"]).lower() == self._current_nick.lower():
  251. self._current_nick = params[0] # track our own nick changes
  252. async def _handle_privmsg(self, sender_nick: str, target: str, text: str) -> None:
  253. if sender_nick.lower() == self._current_nick.lower():
  254. return # our own message
  255. if text.startswith("\x01ACTION ") and text.endswith("\x01"):
  256. text = f"* {sender_nick} {text[8:-1]}" # CTCP ACTION (/me)
  257. if text.startswith("\x01"):
  258. return # other CTCP
  259. is_channel = target.startswith(("#", "&"))
  260. # In channels, only respond if addressed (nick: / nick, / nick )
  261. if is_channel:
  262. for prefix in (f"{self._current_nick}:", f"{self._current_nick},", f"{self._current_nick} "):
  263. if text.lower().startswith(prefix.lower()):
  264. text = text[len(prefix):].strip()
  265. break
  266. else:
  267. return
  268. if self._allowed_users_lower and sender_nick.lower() not in self._allowed_users_lower:
  269. logger.debug("IRC: ignoring message from unauthorized user %s", sender_nick)
  270. return
  271. await self._dispatch_message(text=text, chat_id=target if is_channel else sender_nick,
  272. chat_type="group" if is_channel else "dm",
  273. user_id=sender_nick, user_name=sender_nick)
  274. async def _dispatch_message(self, text: str, chat_id: str, chat_type: str, user_id: str, user_name: str) -> None:
  275. """Build a MessageEvent and hand it to the base class handler."""
  276. if not self._message_handler:
  277. return
  278. source = self.build_source(
  279. chat_id=chat_id, chat_name=chat_id, chat_type=chat_type, user_id=user_id, user_name=user_name)
  280. # Native admission deduplicates by message ID; distinct lines can arrive in one millisecond.
  281. await self.handle_message(MessageEvent(text=text, message_type=MessageType.TEXT, source=source,
  282. message_id=uuid.uuid4().hex, timestamp=datetime.datetime.now()))
  283. # ── Plugin registration ──────────────────────────────────────────────────────
  284. def check_requirements() -> bool:
  285. """Check if IRC is configured via env (server + channel; no pip packages needed)."""
  286. return bool(_get_scoped_secret("IRC_SERVER", "") and _get_scoped_secret("IRC_CHANNEL", ""))
  287. def validate_config(config) -> bool:
  288. """Validate that the platform config (env or config.yaml) has enough info to connect."""
  289. server, channel = _server_channel(config)
  290. return bool(server and channel)
  291. def interactive_setup() -> None:
  292. """`hermes gateway setup` flow (lazy hermes_cli imports keep the plugin importable outside the CLI)."""
  293. from hermes_cli.setup import (
  294. prompt, prompt_yes_no, save_env_value, get_env_value, print_header, print_info, print_warning, print_success)
  295. from hermes_cli.setup_platforms import declines_reconfigure
  296. def info(*lines: str) -> None:
  297. for line in lines:
  298. print_info(line)
  299. def _required(label: str, env: str, default: str, what: str) -> bool:
  300. value = prompt(label, default=default)
  301. if not value:
  302. print_warning(f"{what} is required — skipping IRC setup")
  303. return False
  304. save_env_value(env, value.strip())
  305. return True
  306. print_header("IRC")
  307. existing_server = get_env_value("IRC_SERVER")
  308. if declines_reconfigure("IRC", "Reconfigure IRC?", "IRC_SERVER"):
  309. return
  310. info("Connect Hermes to an IRC network. Uses Python stdlib — no extra packages needed.",
  311. " Works with Libera.Chat, OFTC, your own ZNC/InspIRCd, etc.")
  312. print()
  313. if not _required("IRC server hostname (e.g. irc.libera.chat)", "IRC_SERVER", existing_server or "", "Server"):
  314. return
  315. use_tls = prompt_yes_no("Use TLS (recommended)?", True)
  316. save_env_value("IRC_USE_TLS", "true" if use_tls else "false")
  317. default_port = "6697" if use_tls else "6667"
  318. port = prompt(f"Port (default {default_port})", default=get_env_value("IRC_PORT") or "")
  319. if port:
  320. try:
  321. save_env_value("IRC_PORT", str(int(port)))
  322. except ValueError:
  323. print_warning(f"Invalid port — using default {default_port}")
  324. elif get_env_value("IRC_PORT"):
  325. save_env_value("IRC_PORT", "") # user cleared the prompt; drop the override
  326. for label, env, what in (("Bot nickname (e.g. hermes-bot)", "IRC_NICKNAME", "Nickname"),
  327. ("Channel to join (e.g. #hermes — comma-separate for multiple)", "IRC_CHANNEL", "Channel")):
  328. if not _required(label, env, get_env_value(env) or "", what):
  329. return
  330. print()
  331. info("🔑 Optional authentication", " Leave blank to skip.")
  332. for question, label, env in (
  333. ("Configure a server password (PASS command)?", "Server password", "IRC_SERVER_PASSWORD"),
  334. ("Identify with NickServ on connect?", "NickServ password", "IRC_NICKSERV_PASSWORD")):
  335. if prompt_yes_no(question, False) and (secret := prompt(label, password=True)):
  336. save_env_value(env, secret)
  337. print()
  338. info("🔒 Access control: restrict who can message the bot",
  339. " IRC nicks are not authenticated — anyone can claim any nick.",
  340. " For public channels, pair with NickServ-only mode on your network",
  341. " if you want stronger identity guarantees.")
  342. if prompt_yes_no("Allow all users in the channel to talk to the bot?", False):
  343. save_env_value("IRC_ALLOW_ALL_USERS", "true")
  344. save_env_value("IRC_ALLOWED_USERS", "")
  345. print_warning("⚠️ Open access — any nick in the channel can command the bot.")
  346. else:
  347. save_env_value("IRC_ALLOW_ALL_USERS", "false")
  348. allowed = prompt("Allowed nicks (comma-separated, leave empty to deny everyone)",
  349. default=get_env_value("IRC_ALLOWED_USERS") or "")
  350. if allowed:
  351. save_env_value("IRC_ALLOWED_USERS", allowed.replace(" ", ""))
  352. print_success("Allowlist configured")
  353. else:
  354. save_env_value("IRC_ALLOWED_USERS", "")
  355. print_info("No nicks allowed — the bot will ignore all messages until you add nicks.")
  356. print()
  357. print_success("IRC configuration saved to ~/.hermes/.env")
  358. print_info("Restart the gateway for changes to take effect: hermes gateway restart")
  359. def is_connected(config) -> bool:
  360. """Check whether IRC is configured (env or config.yaml)."""
  361. return validate_config(config)
  362. def _env_enablement() -> dict | None:
  363. """``env_enablement_fn``: seed ``PlatformConfig.extra`` from the profile's env BEFORE adapter construction;
  364. ``None`` when IRC isn't minimally configured. Passwords also live in extra for back-compat with
  365. config.yaml users; env wins at construct time. Home channel defaults to IRC_CHANNEL so cron
  366. ``deliver=irc`` has a target without extra config."""
  367. server = _get_scoped_secret("IRC_SERVER", "").strip()
  368. channel = _get_scoped_secret("IRC_CHANNEL", "").strip()
  369. if not (server and channel):
  370. return None
  371. seed = _seed_extra_from_env((
  372. ("IRC_PORT", "port", int), ("IRC_NICKNAME", "nickname", None),
  373. ("IRC_USE_TLS", "use_tls", lambda v: v.lower() in _TRUTHY),
  374. ("IRC_SERVER_PASSWORD", "server_password", None), ("IRC_NICKSERV_PASSWORD", "nickserv_password", None),
  375. ), home_env="IRC_HOME_CHANNEL", home_default=channel)
  376. return {"server": server, "channel": channel, **seed}
  377. def _strip_irc_control_chars(text: str) -> str:
  378. """Neutralise CR/LF (IRC command injection vector) and the protocol-illegal NUL byte."""
  379. return text.replace("\r", " ").replace("\n", " ").replace("\x00", "")
  380. def _is_irc_channel(target: str) -> bool:
  381. return bool(target) and target[0] in "#&+!"
  382. def _sa_error(detail: str) -> dict[str, Any]:
  383. return send_error(f"IRC standalone send: {detail}")
  384. class _StandaloneConn:
  385. """Raw line I/O for ``_standalone_send``; ``pump`` answers PINGs while waiting for a numeric."""
  386. def __init__(self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter):
  387. self.reader, self.writer = reader, writer
  388. self._loop = asyncio.get_running_loop()
  389. async def raw(self, line: str) -> None:
  390. self.writer.write(_encode_line(line))
  391. await self.writer.drain()
  392. async def pump(self, timeout: float, on_msg):
  393. """Feed commands to ``on_msg`` until it returns non-None; None on timeout, ``_EOF`` on close."""
  394. deadline = self._loop.time() + timeout
  395. while (remaining := deadline - self._loop.time()) > 0:
  396. try:
  397. raw_line = await asyncio.wait_for(self.reader.readuntil(b"\r\n"), timeout=remaining)
  398. except TimeoutError:
  399. return None
  400. except asyncio.IncompleteReadError:
  401. return _EOF
  402. msg = _parse_irc_message(raw_line.decode("utf-8", errors="replace").rstrip("\r\n"))
  403. if msg["command"] == "PING":
  404. await self.raw(f"PONG :{msg['params'][0] if msg['params'] else ''}")
  405. elif (result := await on_msg(msg["command"])) is not None:
  406. return result
  407. return None
  408. async def close(self) -> None:
  409. with contextlib.suppress(Exception):
  410. self.writer.close()
  411. await asyncio.wait_for(self.writer.wait_closed(), timeout=5.0)
  412. async def _sa_register(conn: _StandaloneConn, nick_base: str, server_password: str) -> Optional[dict[str, Any]]:
  413. """PASS/NICK/USER and wait for 001, retrying nick collisions; returns an error dict or None on success."""
  414. nick_attempts = 0
  415. standalone_nick = f"{nick_base}-cron"[:30]
  416. async def _on_registration(cmd: str):
  417. nonlocal nick_attempts, standalone_nick
  418. if cmd in {"432", "433"}:
  419. nick_attempts += 1
  420. if nick_attempts > 5:
  421. return _sa_error("too many nick collisions")
  422. # Build from the stable base, not the mutated nick, so the suffix stays bounded.
  423. standalone_nick = f"{nick_base}-cron-{nick_attempts}"[:30]
  424. await conn.raw(f"NICK {standalone_nick}")
  425. elif cmd in {"464", "465"}:
  426. return _sa_error(f"server rejected client ({cmd})")
  427. return True if cmd == "001" else None
  428. if server_password:
  429. await conn.raw(f"PASS {_strip_irc_control_chars(server_password)}")
  430. await conn.raw(f"NICK {standalone_nick}")
  431. await conn.raw(f"USER {standalone_nick} 0 * :Hermes Agent (cron)")
  432. registered = await conn.pump(15.0, _on_registration)
  433. if registered is None:
  434. return _sa_error("registration timeout (no RPL_WELCOME)")
  435. if registered is _EOF:
  436. return _sa_error("server closed connection during registration")
  437. return None if registered is True else registered
  438. async def _sa_join(conn: _StandaloneConn, target: str) -> Optional[dict[str, Any]]:
  439. """JOIN a channel target (+n channels drop PRIVMSG from non-members); error dict only on explicit rejection."""
  440. async def _on_join(cmd: str):
  441. if cmd in {"403", "405", "471", "473", "474", "475"}:
  442. return _sa_error(f"JOIN {target} rejected ({cmd})")
  443. return True if cmd in {"366", "JOIN"} else None
  444. await conn.raw(f"JOIN {target}")
  445. # No JOIN ack within 5s (or EOF): proceed anyway, the server may still deliver.
  446. joined = await conn.pump(5.0, _on_join)
  447. return joined if isinstance(joined, dict) else None
  448. async def _standalone_send(pconfig, chat_id: str, message: str, *, thread_id: Optional[str] = None,
  449. media_files: Optional[list[str]] = None, force_document: bool = False) -> dict[str, Any]:
  450. """Open an ephemeral IRC connection, send a PRIVMSG, and quit (out-of-process cron delivery via
  451. ``send_message_tool``). Uses a distinct ``-cron`` nick so it never collides with the live gateway adapter.
  452. ``thread_id``/``media_files`` are accepted for signature parity only."""
  453. extra = getattr(pconfig, "extra", {}) or {}
  454. server, channel = _server_channel(pconfig)
  455. if not server or not channel:
  456. return _sa_error("IRC_SERVER and IRC_CHANNEL must be configured")
  457. port_value = _env_or_extra(extra, "IRC_PORT", "port", 6697)
  458. try:
  459. port = int(port_value)
  460. except (TypeError, ValueError):
  461. return _sa_error(f"invalid port {port_value!r}")
  462. use_tls_env = _get_scoped_secret("IRC_USE_TLS")
  463. use_tls = use_tls_env.lower() in _TRUTHY if use_tls_env is not None else bool(extra.get("use_tls", True))
  464. # Reject control characters in chat_id to block IRC command injection.
  465. target = chat_id or channel
  466. if any(ch in target for ch in ("\r", "\n", "\x00", " ")):
  467. return _sa_error("chat_id contains illegal IRC characters")
  468. # Cap the base to 24 chars so collision retries stay within the 30-char NICKLEN most networks enforce.
  469. nick_base = _env_or_extra(extra, "IRC_NICKNAME", "nickname", "hermes-bot").rstrip("_0123456789-")[:24] or "hermes-bot"
  470. plain = IRCAdapter._strip_markdown(message)
  471. try:
  472. reader, writer = await asyncio.wait_for(
  473. asyncio.open_connection(server, port, ssl=_ssl_ctx(use_tls)), timeout=15.0)
  474. except asyncio.CancelledError:
  475. raise
  476. except Exception as e:
  477. return send_error(f"IRC standalone connect failed: {e}")
  478. conn = _StandaloneConn(reader, writer)
  479. try:
  480. if error := await _sa_register(conn, nick_base, _env_or_extra(extra, "IRC_SERVER_PASSWORD", "server_password")):
  481. return error
  482. if nickserv_password := _env_or_extra(extra, "IRC_NICKSERV_PASSWORD", "nickserv_password"):
  483. await conn.raw(f"PRIVMSG NickServ :IDENTIFY {_strip_irc_control_chars(nickserv_password)}")
  484. await asyncio.sleep(2)
  485. # JOIN before PRIVMSG; never JOIN bare nicks (DM target) or server queries.
  486. if _is_irc_channel(target) and (error := await _sa_join(conn, target)):
  487. return error
  488. # Bytes-aware per-line splitting (same algorithm as IRCAdapter._split_message),
  489. # with control-character stripping per line to block CRLF injection from content.
  490. paragraphs = [q for q in (_strip_irc_control_chars(p).rstrip() for p in plain.split("\n")) if q]
  491. lines = _split_lines(paragraphs, _privmsg_budget(target))
  492. for line in lines:
  493. await conn.raw(f"PRIVMSG {target} :{line}")
  494. await asyncio.sleep(0.3)
  495. if not lines:
  496. return _sa_error("empty message after stripping")
  497. await conn.raw("QUIT :" + t("platform.irc.standalone_quit"))
  498. with contextlib.suppress(asyncio.TimeoutError):
  499. await asyncio.wait_for(reader.read(1024), timeout=2.0)
  500. return {"success": True, "message_id": _ms_id()}
  501. except asyncio.CancelledError:
  502. raise
  503. except Exception as e:
  504. logger.debug("IRC standalone send raised", exc_info=True)
  505. return send_error(f"IRC standalone send failed: {e}")
  506. finally:
  507. await conn.close()
  508. def register(ctx):
  509. """Plugin entry point: called by the Hermes plugin system."""
  510. ctx.register_platform(
  511. name="irc",
  512. dashboard_description="Relay messages between an IRC channel (or DMs) and Hermes.",
  513. docs_url="https://hermes-agent.nousresearch.com/docs/user-guide/messaging/irc",
  514. label="IRC",
  515. adapter_factory=IRCAdapter,
  516. check_fn=check_requirements,
  517. # ACTIVE lazy-installer — create_adapter() calls this when check_fn is False, right before the
  518. # gateway connects Teams (#79812).
  519. validate_config=validate_config,
  520. is_connected=is_connected,
  521. required_env=["IRC_SERVER", "IRC_CHANNEL", "IRC_NICKNAME"],
  522. install_hint="No extra packages needed (stdlib only)",
  523. setup_fn=interactive_setup,
  524. env_enablement_fn=_env_enablement, # env-only setups show in gateway status
  525. cron_deliver_env_var="IRC_HOME_CHANNEL", # defaults to IRC_CHANNEL (see _env_enablement)
  526. standalone_sender_fn=_standalone_send, # cron running separately from the gateway
  527. allowed_users_env="IRC_ALLOWED_USERS",
  528. allow_all_env="IRC_ALLOW_ALL_USERS",
  529. max_message_length=450, # IRC line limit after protocol overhead
  530. emoji="💬",
  531. pii_safe=False, # IRC doesn't have phone numbers to redact
  532. allow_update_command=True,
  533. platform_hint=(
  534. "You are chatting via IRC. IRC does not support markdown formatting "
  535. "— use plain text only. Messages are limited to ~450 characters per "
  536. "line (long messages are automatically split). In channels, users "
  537. "address you by prefixing your nick. Keep responses concise and "
  538. "conversational."))