adapter.py 107 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894189518961897189818991900190119021903190419051906190719081909191019111912191319141915191619171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954195519561957195819591960196119621963196419651966
  1. # health: allow FILE_LINES -- platform-tables refactor: core's _PLATFORM_DEFAULTS row for this platform moved onto its register() call as display_tier; the growth is only that kwarg
  2. """Buzz platform adapter (Block's Nostr-based human+agent community relay).
  3. Outbound and polling go through the ``buzz`` CLI ("JSON in, JSON out", never a shell);
  4. inbound prefers a NIP-42-authenticated WebSocket subscription with a CLI poll fallback.
  5. Config lives in ``gateway.platforms.buzz.extra`` (relay_url, channels, home_channel,
  6. poll_interval, cli_path, credentials_file, allowed_users, reply_in_thread, reaction_only_users)
  7. or the matching ``BUZZ_*`` env vars (env overrides config). The only secret is
  8. BUZZ_PRIVATE_KEY (nsec or hex): it reaches the CLI via the subprocess env and is never logged.
  9. """
  10. import asyncio
  11. import contextlib
  12. import hashlib
  13. import json
  14. import logging
  15. import mimetypes
  16. import os
  17. import re
  18. import shutil
  19. import tempfile
  20. import time
  21. from collections import OrderedDict
  22. from datetime import datetime
  23. from pathlib import Path
  24. from typing import Any, Dict, List, Optional, Tuple
  25. from urllib.parse import urlsplit, urlunsplit
  26. # Profile-scoped read (adapter startup, Slack pattern #59739): a scoped read honors the profile's own
  27. # secret; only an UNSCOPED read under multiplex (default-profile startup loop) falls back to the process
  28. # env, which is that profile's own value.
  29. from agent.secret_scope import is_multiplex_active as _is_multiplex_active
  30. from gateway.platforms._shared import (
  31. apply_yaml_bridge as _apply_yaml_bridge, get_scoped_secret as _shared_scoped_secret, profile_scoped as _profile_scoped,
  32. seed_extra_from_env as _seed_extra_from_env,
  33. )
  34. from gateway.platforms._shared import send_error
  35. def _get_scoped_secret(name, default=None):
  36. """Buzz reads consult a one-shot profile-scope build when unscoped: ``check_requirements`` runs at
  37. startup before any scope exists, so Bitwarden-managed keys would otherwise be invisible (#95216)."""
  38. return _shared_scoped_secret(name, default, external_fallback=True)
  39. def _scoped_platform_setting(env_name, extra, key):
  40. """Raw non-secret setting; in a secondary profile scope ``os.environ`` is the DEFAULT profile's, so the
  41. profile's own secret scope (its ``.env``) stands in for env and ``extra`` is the fallback.
  42. Inside a secondary profile scope ``os.environ`` holds the DEFAULT profile's YAML-to-env bridge output
  43. (#98738), so the profile's ``PlatformConfig.extra`` is authoritative and env is not consulted: a missing
  44. key yields ``None`` and callers fail closed to their default instead of silently borrowing the default
  45. profile's relay, channels, or allowlist. Everywhere else — single-profile gateways, the default profile
  46. under multiplexing — the legacy ``os.getenv`` read is returned unchanged, so env-over-config precedence
  47. is preserved.
  48. """
  49. if _profile_scoped():
  50. scoped = _get_scoped_secret(env_name)
  51. return scoped if scoped is not None else (extra or {}).get(key)
  52. return os.getenv(env_name)
  53. logger = logging.getLogger(__name__)
  54. from gateway.platforms.base import (
  55. BasePlatformAdapter, CachedMedia, SendResult, cache_media_bytes_async,
  56. )
  57. from gateway.platforms.helpers import cancel_task
  58. from gateway.platforms.event import MessageEvent, MessageType
  59. from gateway.config import Platform
  60. from plugins.platforms.buzz.buzz_cursors import _SEEN_CAP, BuzzCursorMixin
  61. _CHAT_KIND = 9 # ``messages get`` also returns housekeeping kinds, never dispatched
  62. # Chat + forum post/comment; stream kinds wait for confirmed semantics. ``_is_direct_message_event``
  63. # stays kind-9-only so a p-tagged forum post can't be reclassified as a DM and bypass mention gating.
  64. # Kinds that carry agent-relevant conversation content and are dispatched (#90309): chat messages (9) plus
  65. # the Buzz forum kinds — 45001 is a forum post (thread root) and 45003 a comment reply on it. Block's own
  66. # ACP harness documents this set (``buzz-acp --kinds 9,46010,40007,45001, 45002,45003``); the stream kinds
  67. # (46010/40007/45002) are left out until their dispatch semantics are confirmed.
  68. _DISPATCH_KINDS = frozenset({_CHAT_KIND, 45001, 45003})
  69. _UNRESOLVED_MENTION_ERROR_RE = re.compile(r"mention '@(?P<name>[^']+)' does not match a current channel member")
  70. _BUZZ_PRESENTATION_MENTION_SEPARATOR = "\u200b"
  71. _HEX64_RE = re.compile(r"[0-9a-f]{64}")
  72. def _escape_unresolved_presentation_mention(content: str, error: str) -> Optional[str]:
  73. """Make a CLI-rejected ``@name`` presentation-only via an invisible separator after the ``@`` (Buzz
  74. p-tags whitespace-prefixed @tokens at publish, so prose like ``@session:...`` fails preflight)."""
  75. match = _UNRESOLVED_MENTION_ERROR_RE.search(error or "")
  76. name = match.group("name") if match else ""
  77. if not name:
  78. return None
  79. token = re.compile(rf"(?<!\S)@{re.escape(name)}(?=$|[^A-Za-z0-9._-])", re.IGNORECASE)
  80. escaped, count = token.subn(lambda m: "@" + _BUZZ_PRESENTATION_MENTION_SEPARATOR + m.group(0)[1:], content)
  81. return escaped if count else None
  82. _FETCH_LIMIT = 50 # events per poll / seed call
  83. _DM_DISCOVERY_EVERY = 5 # re-run DM discovery every N poll sweeps
  84. _DEFAULT_POLL_INTERVAL = 4.0
  85. _MIN_POLL_INTERVAL = 1.0
  86. _CLI_TIMEOUT = 30.0
  87. # Mention-resolution caches: member lists are hit on every publish containing "@"; names must not outlive a rename.
  88. _MEMBER_CACHE_TTL = 60.0
  89. _PROFILE_NAME_TTL = 300.0
  90. # Inbound attachments download only after the gates pass and must match their declared NIP-94 size + SHA-256.
  91. _MAX_INBOUND_ATTACHMENTS = 4
  92. _MAX_INBOUND_ATTACHMENT_BYTES = 20 * 1024 * 1024
  93. _ATTACHMENT_DOWNLOAD_TIMEOUT = 30.0
  94. _MAX_ATTACHMENT_FILENAME_BYTES = 120
  95. def _safe_attachment_filename(value: str) -> str:
  96. """Return a basename that is safe for cache files and agent context."""
  97. name = str(value or "").replace("\\", "/").rsplit("/", 1)[-1]
  98. name = "".join(c for c in name if ord(c) >= 32 and c != "\x7f").strip()
  99. if name in {"", ".", ".."}:
  100. return "attachment.bin"
  101. suffix = Path(name).suffix if len(Path(name).suffix.encode("utf-8")) <= 20 else ""
  102. stem = name[:-len(suffix)] if suffix else name
  103. byte_budget = _MAX_ATTACHMENT_FILENAME_BYTES - len(suffix.encode("utf-8"))
  104. safe_stem = stem.encode("utf-8")[:byte_budget].decode("utf-8", errors="ignore").rstrip(" .")
  105. return f"{safe_stem or 'attachment'}{suffix}"
  106. def _attachment_origin(value: str) -> Optional[tuple[str, int]]:
  107. """Normalize a configured host/URL to an exact HTTPS-equivalent origin."""
  108. raw = str(value or "").strip()
  109. if not raw:
  110. return None
  111. try:
  112. parsed = urlsplit(raw if "://" in raw else f"//{raw}")
  113. host = (parsed.hostname or "").lower().rstrip(".")
  114. port = parsed.port or 443
  115. except ValueError:
  116. return None
  117. if (parsed.scheme and parsed.scheme not in {"https", "wss"}) or not host:
  118. return None
  119. return host, port
  120. # WebSocket transport (NIP-42 authenticated Nostr subscription).
  121. _WS_AUTH_TIMEOUT = 20.0
  122. # Last-resort read bound: an unsurfaced relay-side close (CLOSE_WAIT) would leave us "connected" with inbound stopped.
  123. # The library keepalive (ping_interval/ping_timeout below) should catch a dead relay first, but a relay-side
  124. # close the transport never surfaces (observed as a CLOSE_WAIT socket with the loop parked on recv, #98097)
  125. # leaves the gateway "connected" while inbound stops; this timeout forces the normal reconnect path instead.
  126. _WS_READ_IDLE_TIMEOUT = 300.0
  127. _WS_MAX_MESSAGE_BYTES = 2_000_000
  128. _WS_MEMBERSHIP_KIND = 44100 # Buzz channel-membership event — live DM discovery
  129. _WS_MEMBERSHIP_SUB_ID = "hermes-buzz-membership"
  130. # Credentials JSON fallback when BUZZ_PRIVATE_KEY is not set; module-level so tests can point it at a tmpdir.
  131. _DEFAULT_CREDENTIALS_DIR = Path("~/.config/buzz").expanduser()
  132. # Buzz-hosted media is private to the community: same-relay URLs must be authenticated + localised for vision.
  133. _MEDIA_URL_PATTERN = r"https?://[^\s<>\[\]()]+/media/[0-9a-f]{64}(?:\.[a-z0-9]{1,10})?(?:\?[^\s<>\[\]()]*)?"
  134. _MARKDOWN_MEDIA_RE = re.compile(
  135. rf"!\[(?P<alt>[^\]]*)\]\(\s*(?P<url>{_MEDIA_URL_PATTERN})(?:\s+[\"'][^\"']*[\"'])?\s*\)", re.IGNORECASE
  136. )
  137. _BARE_MEDIA_RE = re.compile(_MEDIA_URL_PATTERN, re.IGNORECASE)
  138. _MEDIA_PATH_RE = re.compile(r"^/media/(?P<sha>[0-9a-f]{64})(?P<ext>\.[a-z0-9]{1,10})?/?$", re.IGNORECASE)
  139. def _consume_ws_read_task(task: asyncio.Task) -> None:
  140. """Retrieve a detached stalled receive task's result without blocking recovery."""
  141. if not task.cancelled():
  142. with contextlib.suppress(Exception):
  143. task.exception()
  144. def _effective_port(parsed) -> Optional[int]:
  145. try:
  146. if parsed.port is not None:
  147. return parsed.port
  148. except ValueError:
  149. return None
  150. return {"https": 443, "wss": 443, "http": 80, "ws": 80}.get(parsed.scheme)
  151. def _is_relay_media_url(url: str, relay_url: str) -> bool:
  152. """Return whether *url* is a Buzz media object on the configured relay."""
  153. candidate, relay = urlsplit(url), urlsplit(relay_url)
  154. return bool(
  155. candidate.scheme in ("http", "https") and candidate.hostname and relay.hostname
  156. and candidate.hostname.lower() == relay.hostname.lower()
  157. and _effective_port(candidate) == _effective_port(relay) and _MEDIA_PATH_RE.fullmatch(candidate.path)
  158. )
  159. def _find_relay_media_refs(text: str, relay_url: str) -> tuple[list[str], list[tuple[int, int, str]]]:
  160. """Find same-relay media URLs and their safe text replacements."""
  161. urls: list[str] = []
  162. replacements: list[tuple[int, int, str]] = []
  163. markdown_spans: list[tuple[int, int]] = []
  164. for match in _MARKDOWN_MEDIA_RE.finditer(text):
  165. url = match.group("url")
  166. if not _is_relay_media_url(url, relay_url):
  167. continue
  168. markdown_spans.append(match.span())
  169. replacements.append((*match.span(), match.group("alt").strip()))
  170. if url not in urls:
  171. urls.append(url)
  172. for match in _BARE_MEDIA_RE.finditer(text):
  173. if any(start <= match.start() and match.end() <= end for start, end in markdown_spans):
  174. continue
  175. url = match.group(0)
  176. if not _is_relay_media_url(url, relay_url):
  177. continue
  178. replacements.append((*match.span(), ""))
  179. if url not in urls:
  180. urls.append(url)
  181. return urls, replacements
  182. def _replace_media_refs(text: str, replacements: list[tuple[int, int, str]]) -> str:
  183. for start, end, replacement in sorted(replacements, reverse=True):
  184. text = f"{text[:start]}{replacement}{text[end:]}"
  185. return re.sub(r"\n{3,}", "\n\n", re.sub(r"[ \t]+\n", "\n", text)).strip()
  186. def _load_sibling(name: str):
  187. """Import a sibling module loader-agnostically (the test loader imports this file as a bare module)."""
  188. import importlib
  189. try:
  190. return importlib.import_module(f".{name}", __package__) if __package__ else _load_sibling_file(name)
  191. except ImportError:
  192. return _load_sibling_file(name)
  193. def _load_sibling_file(name: str):
  194. import importlib.util
  195. path = Path(__file__).with_name(f"{name}.py")
  196. spec = importlib.util.spec_from_file_location(f"plugin_adapter_buzz_{name}", path)
  197. assert spec is not None and spec.loader is not None
  198. module = importlib.util.module_from_spec(spec)
  199. spec.loader.exec_module(module)
  200. return module
  201. _nostr_auth = _load_sibling("nostr_auth")
  202. # bech32 (BIP-173) npub <-> hex so mention detection and allow-lists accept either form.
  203. from gateway.authz_mixin import (
  204. _BECH32_CHARSET, _bech32_hrp_expand, _bech32_polymod, _convertbits, _npub_to_hex as npub_to_hex,
  205. )
  206. def hex_to_npub(pubkey_hex: str) -> Optional[str]:
  207. """Encode a 64-char hex pubkey as an ``npub1…`` bech32 string."""
  208. try:
  209. raw = bytes.fromhex(pubkey_hex)
  210. except ValueError:
  211. return None
  212. if len(raw) != 32 or (data := _convertbits(raw, 8, 5)) is None:
  213. return None
  214. polymod = _bech32_polymod(_bech32_hrp_expand("npub") + data + [0, 0, 0, 0, 0, 0]) ^ 1
  215. checksum = [(polymod >> 5 * (5 - i)) & 31 for i in range(6)]
  216. return "npub1" + "".join(_BECH32_CHARSET[d] for d in data + checksum)
  217. def _split_csv(raw):
  218. return raw.split(",") if isinstance(raw, str) else raw
  219. def _pubkey_set(raw) -> set:
  220. """Normalize a csv string / list of hex pubkeys or npubs to a set of hex pubkeys."""
  221. return {n for entry in _split_csv(raw) if isinstance(entry, str) and (n := _normalize_user_ref(entry))}
  222. def _setting_or(env_name: str, extra: dict, key: str, default):
  223. """Scoped setting read with an explicit ``None`` -> ``extra`` fallback."""
  224. raw = _scoped_platform_setting(env_name, extra, key)
  225. return extra.get(key, default) if raw is None else raw
  226. def _ttl_get(cache: dict, key, ttl: float):
  227. """Value of a ``(monotonic_ts, value)`` cache entry if younger than *ttl*, else None."""
  228. cached = cache.get(key)
  229. return cached[1] if cached is not None and (time.monotonic() - cached[0]) < ttl else None
  230. def _add_pubkey(bucket: list[str], raw) -> None:
  231. """Append the lowercased pubkey once (empty values are skipped)."""
  232. pk = str(raw or "").lower()
  233. if pk and pk not in bucket:
  234. bucket.append(pk)
  235. def _normalize_user_ref(ref: str) -> Optional[str]:
  236. """Normalize a user reference (hex pubkey or npub) to lowercase hex."""
  237. ref = (ref or "").strip().lower()
  238. if not ref:
  239. return None
  240. if ref.startswith("npub1"):
  241. return npub_to_hex(ref)
  242. return ref if _HEX64_RE.fullmatch(ref) else None
  243. # ── buzz-cli invocation helpers ──────────────────────────────────────────────
  244. def _reply_to_mode(config, extra: dict) -> str:
  245. """Reply mode ("first"/"all" thread, "off" posts flat); env overrides config, ``reply_in_thread: false`` = "off"."""
  246. mode_env = _get_scoped_secret("BUZZ_REPLY_TO_MODE") if _profile_scoped() else os.getenv("BUZZ_REPLY_TO_MODE")
  247. mode = str(mode_env or getattr(config, "reply_to_mode", "first") or "first").strip().lower()
  248. rit = _setting_or("BUZZ_REPLY_IN_THREAD", extra, "reply_in_thread", None)
  249. return "off" if rit is not None and str(rit).strip().lower() in ("false", "0", "no", "off") else mode
  250. def _configured_relay(extra: dict) -> str:
  251. return (_scoped_platform_setting("BUZZ_RELAY_URL", extra, "relay_url") or extra.get("relay_url", "")).strip()
  252. def _configured_home_channel(extra: dict) -> str:
  253. raw = _scoped_platform_setting("BUZZ_HOME_CHANNEL", extra, "home_channel")
  254. return (raw or str(extra.get("home_channel", "") or "")).strip()
  255. def _configured_cli_path(extra: dict) -> str:
  256. raw = _scoped_platform_setting("BUZZ_CLI_PATH", extra, "cli_path")
  257. return _resolve_cli_path(str(raw or "").strip() or str(extra.get("cli_path", "") or ""))
  258. def _configured_credentials_file(extra: Optional[dict]) -> str:
  259. # Scoped: a miss falls to the profile's own extra, never the default profile's env; unscoped keeps env precedence.
  260. configured = str(_get_scoped_secret("BUZZ_CREDENTIALS_FILE", "") or "").strip()
  261. return configured or str((extra or {}).get("credentials_file", "") or "").strip()
  262. def _resolve_cli_path(configured: str = "") -> str:
  263. """Resolve the buzz binary: explicit config → ``buzz`` on PATH → ``~/bin/buzz``; "" if none."""
  264. if configured:
  265. p = Path(configured).expanduser()
  266. return str(p) if p.is_file() else ""
  267. if found := shutil.which("buzz"):
  268. return found
  269. fallback = Path.home() / "bin" / "buzz"
  270. return str(fallback) if fallback.is_file() else ""
  271. def _credentials_candidates(extra: Optional[dict] = None) -> list[Path]:
  272. configured = _configured_credentials_file(extra)
  273. if configured:
  274. return [Path(configured).expanduser()]
  275. if _is_multiplex_active():
  276. return []
  277. try:
  278. return sorted(_DEFAULT_CREDENTIALS_DIR.glob("*credentials*.json"))
  279. except OSError:
  280. return []
  281. _KEY_FIELDS = ("nsec", "private_key_hex", "private_key")
  282. def _credentials_key(data: dict) -> str:
  283. """First non-empty private-key field in a credentials record, stripped ("" if none)."""
  284. for field in _KEY_FIELDS:
  285. value = data.get(field)
  286. if isinstance(value, str) and value.strip():
  287. return value.strip()
  288. return ""
  289. def _resolve_credentials_data(extra: Optional[dict] = None) -> dict:
  290. """Load the first credential record containing a private key."""
  291. for path in _credentials_candidates(extra):
  292. try:
  293. data = json.loads(path.read_text(encoding="utf-8-sig"))
  294. except (OSError, ValueError):
  295. continue
  296. if isinstance(data, dict) and _credentials_key(data):
  297. return data
  298. return {}
  299. def _resolve_private_key(extra: Optional[dict] = None) -> str:
  300. """Resolve the Nostr private key: scoped secret first, then credentials JSON. NEVER log it."""
  301. key = str(_get_scoped_secret("BUZZ_PRIVATE_KEY", "") or "").strip()
  302. return key or _credentials_key(_resolve_credentials_data(extra))
  303. def _resolve_auth_tag(extra: Optional[dict] = None) -> str:
  304. """Resolve and validate the optional NIP-OA owner-attestation tag."""
  305. raw: Any = str(_get_scoped_secret("BUZZ_AUTH_TAG", "") or "").strip()
  306. if not raw:
  307. if str(_get_scoped_secret("BUZZ_PRIVATE_KEY", "") or "").strip() and not _configured_credentials_file(extra):
  308. return ""
  309. if "auth_tag" not in (data := _resolve_credentials_data(extra)):
  310. return ""
  311. raw = data["auth_tag"]
  312. return json.dumps(_nostr_auth.parse_auth_tag(raw, "Buzz auth tag"), separators=(",", ":"))
  313. async def _exec_buzz(
  314. cli_path: str, args: list[str], *, relay_url: str, private_key: str, auth_tag: str = "",
  315. input_text: Optional[str] = None, timeout: float = _CLI_TIMEOUT,
  316. ) -> tuple[int, str, str]:
  317. """Run the buzz CLI (argv, never a shell) -> ``(rc, stdout, stderr)``. Key travels via env only."""
  318. from tools.environments.local import hermes_subprocess_env
  319. env = hermes_subprocess_env() # a third-party CLI: its own key only, never Hermes' credentials
  320. env["HOME"] = env["HERMES_REAL_HOME"] # its own config and credentials file live under the user's HOME
  321. env["BUZZ_RELAY_URL"] = relay_url
  322. env["BUZZ_PRIVATE_KEY"] = private_key
  323. env.pop("BUZZ_AUTH_TAG", None)
  324. if auth_tag:
  325. env["BUZZ_AUTH_TAG"] = auth_tag
  326. proc = await asyncio.create_subprocess_exec(
  327. cli_path, *args, stdin=asyncio.subprocess.PIPE if input_text is not None else asyncio.subprocess.DEVNULL,
  328. stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE, env=env,
  329. )
  330. try:
  331. stdin_bytes = input_text.encode("utf-8") if input_text is not None else None
  332. stdout, stderr = await asyncio.wait_for(proc.communicate(stdin_bytes), timeout=timeout)
  333. except TimeoutError:
  334. proc.kill()
  335. await proc.wait()
  336. detail = {"error": "timeout", "message": f"buzz {args[0] if args else ''} timed out after {timeout}s"}
  337. return 124, "", json.dumps(detail)
  338. rc = proc.returncode if proc.returncode is not None else 4
  339. return rc, stdout.decode("utf-8", errors="replace"), stderr.decode("utf-8", errors="replace")
  340. _MAX_CLI_MESSAGE_CHARS = 900
  341. def _bounded_cli_message(message: str, redact_path: Optional[Path] = None) -> str:
  342. """Keep untrusted CLI detail useful without exposing unbounded output."""
  343. if redact_path is not None:
  344. message = message.replace(str(redact_path), redact_path.name)
  345. return message if len(message) <= _MAX_CLI_MESSAGE_CHARS else f"{message[: _MAX_CLI_MESSAGE_CHARS - 3]}..."
  346. def _cli_error_message(stderr: str, returncode: int, *, redact_path: Optional[Path] = None) -> str:
  347. """Extract a bounded human-readable message from the CLI error contract."""
  348. text = (stderr or "").strip()
  349. data = _json_or(text, None)
  350. if isinstance(data, dict):
  351. detail, category = data.get("message"), data.get("error")
  352. if isinstance(detail, str) and detail.strip():
  353. label = category.strip() if isinstance(category, str) and category.strip() else "error"
  354. return _bounded_cli_message(f"{label}: {detail.strip()} (exit {returncode})", redact_path)
  355. return _bounded_cli_message(text or f"buzz CLI failed with exit code {returncode}", redact_path)
  356. def _parse_send_receipt(stdout: str) -> tuple[Optional[str], Optional[str]]:
  357. """Validate the buzz-cli success receipt and return ``(event_id, error)``."""
  358. data = _json_or(stdout, None)
  359. if not isinstance(data, dict):
  360. return None, "invalid CLI response"
  361. if data.get("accepted") is False:
  362. detail = data.get("message")
  363. if not isinstance(detail, str) or not detail.strip():
  364. detail = "message was not accepted"
  365. return None, _bounded_cli_message(detail.strip())
  366. event_id = data.get("event_id")
  367. if data.get("accepted") is not True or not isinstance(event_id, str) or not event_id.strip():
  368. return None, "invalid CLI response"
  369. return event_id.strip(), None
  370. def _json_or(text: str, default):
  371. """``json.loads`` of CLI stdout, or *default* when empty/malformed."""
  372. try:
  373. return json.loads(text or json.dumps(default))
  374. except ValueError:
  375. return default
  376. def _parse_json_list(stdout: str) -> list[dict]:
  377. """Parse CLI stdout expected to be a JSON array of objects."""
  378. data = _json_or(stdout, [])
  379. return [item for item in data if isinstance(item, dict)] if isinstance(data, list) else []
  380. def _e_tags(event: dict):
  381. """Yield ``(target, marker)`` for each well-formed NIP-10 ``e`` tag (raw values, unstripped)."""
  382. tags = event.get("tags")
  383. if isinstance(tags, list):
  384. for tag in tags:
  385. if isinstance(tag, (list, tuple)) and len(tag) >= 2 and str(tag[0]) == "e":
  386. yield tag[1], (str(tag[3]) if len(tag) > 3 else "")
  387. def _event_reply_parent_id(event: dict) -> Optional[str]:
  388. """Direct parent id from NIP-10 ``e`` tags: ``reply`` marker, then ``root``, else last positional."""
  389. reply_id = root_id = last_e = None
  390. for raw_target, marker in _e_tags(event):
  391. target = str(raw_target or "").strip()
  392. if not target:
  393. continue
  394. last_e = target
  395. if marker == "reply":
  396. reply_id = target
  397. elif marker == "root":
  398. root_id = target
  399. return reply_id or root_id or last_e
  400. def _p_tagged(event: dict, pubkey: str) -> bool:
  401. """True when the event carries a ``p`` tag equal to *pubkey* (case-insensitive)."""
  402. tags = event.get("tags")
  403. return isinstance(tags, list) and any(
  404. isinstance(tag, (list, tuple)) and len(tag) > 1 and tag[0] == "p" and str(tag[1]).lower() == pubkey for tag in tags)
  405. # Cap stored parent content snippets (gateway reply injection also clips).
  406. _EVENT_META_CONTENT_CAP = 500
  407. _MEDIA_KIND_PRIORITY = (("image", MessageType.PHOTO), ("audio", MessageType.AUDIO), ("video", MessageType.VIDEO))
  408. _ATTACHMENT_KIND_TYPES = {"image": MessageType.PHOTO, "video": MessageType.VIDEO, "audio": MessageType.AUDIO, "document": MessageType.DOCUMENT}
  409. class BuzzAdapter(BuzzCursorMixin, BasePlatformAdapter):
  410. """Buzz adapter (WebSocket push with poll fallback) for the BasePlatformAdapter interface."""
  411. serial_receive_loop = True # WS listener and poll sweep both await each event batch before reading the next
  412. def __init__(self, config, **kwargs):
  413. super().__init__(config=config, platform=Platform("buzz"))
  414. extra = getattr(config, "extra", {}) or {}
  415. self._extra = extra
  416. # Env overrides config.yaml, except under a secondary profile scope where extra wins (_scoped_platform_setting).
  417. self.relay_url = _configured_relay(extra)
  418. hosts = _split_csv(extra.get("attachment_hosts", []))
  419. origins = (_attachment_origin(h) for h in hosts if isinstance(h, str))
  420. self._attachment_origins = {o for o in origins if o is not None}
  421. relay_origin = _attachment_origin(self.relay_url)
  422. if relay_origin is not None:
  423. self._attachment_origins.add(relay_origin)
  424. self.cli_path = _configured_cli_path(extra)
  425. # Channels to watch: env csv > extra list/csv; empty = all joined channels
  426. raw_channels = _split_csv(_setting_or("BUZZ_CHANNELS", extra, "channels", []))
  427. self.channels: list[str] = [c.strip() for c in raw_channels if isinstance(c, str) and c.strip()]
  428. self.home_channel = _configured_home_channel(extra)
  429. _pi_raw = _scoped_platform_setting("BUZZ_POLL_INTERVAL", extra, "poll_interval")
  430. try:
  431. self.poll_interval = max(_MIN_POLL_INTERVAL, float(_pi_raw or extra.get("poll_interval", _DEFAULT_POLL_INTERVAL)))
  432. except (TypeError, ValueError):
  433. self.poll_interval = max(_MIN_POLL_INTERVAL, _DEFAULT_POLL_INTERVAL)
  434. # Channel messages must @mention the agent unless disabled; DMs always dispatch.
  435. _rm_cfg = _setting_or("BUZZ_REQUIRE_MENTION", extra, "require_mention", True)
  436. self.require_mention = str(_rm_cfg).strip().lower() not in ("false", "0", "no", "off")
  437. self._reply_to_mode: str = _reply_to_mode(config, extra)
  438. # Inbound transport: "auto" (WebSocket with poll fallback), "websocket" (required), "poll".
  439. _transport_raw = _scoped_platform_setting("BUZZ_TRANSPORT", extra, "transport")
  440. _transport = (_transport_raw or str(extra.get("transport", "auto") or "auto")).strip().lower()
  441. self.transport = _transport if _transport in ("auto", "websocket", "poll") else "auto"
  442. # Entries may be hex or npub (normalized to hex). Reaction-only identities get a 👀 on explicit tags but
  443. # never dispatch; allowed_users wins on overlap.
  444. self._allowed_pubkeys: set = _pubkey_set(_setting_or("BUZZ_ALLOWED_USERS", extra, "allowed_users", []))
  445. self._reaction_only_pubkeys: set = _pubkey_set(_setting_or("BUZZ_REACTION_ONLY_USERS", extra, "reaction_only_users", []))
  446. # Secret — resolved lazily (never at import time, never logged); connect() re-resolves.
  447. self._private_key = self._auth_tag = ""
  448. # Identity — filled in by connect() from ``buzz users get``
  449. self._self_pubkey = self._self_npub = self._display_name = ""
  450. self._poll_task: Optional[asyncio.Task] = None
  451. self._ws_task: Optional[asyncio.Task] = None
  452. self._ws_ready: Optional[asyncio.Event] = None
  453. self._membership_since = self._poll_count = 0
  454. # Channels the relay permanently rejected ("restricted"); persists across reconnects so we never re-subscribe.
  455. # channel_id -> { "chat_type", "last_ts", "seen": OrderedDict[event_id, None], "event_meta":
  456. # OrderedDict[event_id, (author_pubkey, content_snippet)], } event_meta backs NIP-10 reply-parent
  457. # resolution for require_mention (thread replies to our own messages count as addressed — #75826).
  458. # "restricted: not a channel member").
  459. self._restricted_channels: set = set()
  460. # channel_id -> {"chat_type", "last_ts", "seen": OrderedDict[event_id, None], "event_meta":
  461. # OrderedDict[event_id, (author_pubkey, snippet)]}; event_meta backs NIP-10 reply-parent resolution.
  462. self._channel_state: dict[str, dict] = {}
  463. # Cursors read from disk at connect(), consumed by each channel's first seed.
  464. self._restored_cursors: dict[str, dict] = {}
  465. # Orders off-loop cursor writes: each snapshot is taken under it, so an older one never lands last.
  466. self._cursor_write_lock = asyncio.Lock()
  467. self._cursor_snapshots = self._cursor_written = 0 # cursor write generations taken / landed
  468. self._channel_names: dict[str, str] = {}
  469. # channel_id -> raw ``channels list`` entry; drives DM-vs-channel classification.
  470. self._channel_meta: dict[str, dict] = {}
  471. self._user_names: dict[str, str] = {}
  472. self._member_cache: dict[str, tuple[float, list[str]]] = {} # (monotonic, pubkeys)
  473. self._profile_name_cache: dict[str, tuple[float, str]] = {}
  474. # inbound event_id -> thread root (None when top-level), so send() joins the user's thread instead of nesting.
  475. self._thread_roots: OrderedDict[str, Optional[str]] = OrderedDict()
  476. @property
  477. def name(self) -> str:
  478. return "Buzz"
  479. @staticmethod
  480. def normalize_user_id(user_id: str) -> Optional[str]:
  481. """Normalize a user reference (hex or npub) to hex — authz_mixin allowlist hook.
  482. Optional hook consumed by ``gateway/authz_mixin`` when matching the profile allowlist carried in
  483. ``config.extra.allowed_users`` (#98738): entries may be npubs while inbound ``user_id`` is always
  484. the hex pubkey, so a plain string compare would deny listed users.
  485. """
  486. return _normalize_user_ref(user_id)
  487. # ── buzz-cli plumbing ─────────────────────────────────────────────────
  488. async def _run_cli(self, args: list[str], *, input_text: Optional[str] = None) -> tuple[int, str, str]:
  489. if not self._private_key:
  490. self._private_key = _resolve_private_key(self._extra)
  491. self._auth_tag = _resolve_auth_tag(self._extra)
  492. return await _exec_buzz(self.cli_path, args, relay_url=self.relay_url, private_key=self._private_key,
  493. auth_tag=self._auth_tag, input_text=input_text)
  494. async def _cli_json(self, args: list[str], default):
  495. """``_run_cli`` -> parsed stdout on rc 0, else *default*."""
  496. code, out, _err = await self._run_cli(args)
  497. return _json_or(out, default) if code == 0 else default
  498. # ── Connection lifecycle ──────────────────────────────────────────────
  499. def _connect_failed(self, code: str, detail: str, log: str, *log_args, retryable: bool = False) -> bool:
  500. """Log and record a fatal connect() error; always returns False."""
  501. logger.error(log, *log_args)
  502. self._set_fatal_error(code, detail, retryable=retryable)
  503. return False
  504. async def connect(self, *, is_reconnect: bool = False) -> bool:
  505. """Verify relay credentials, seed high-water marks, start polling."""
  506. if not self.relay_url:
  507. return self._connect_failed("config_missing", "BUZZ_RELAY_URL must be set", "Buzz: relay URL must be configured")
  508. if not self.cli_path:
  509. return self._connect_failed(
  510. "cli_missing", "buzz CLI binary not found", "Buzz: buzz CLI binary not found (set BUZZ_CLI_PATH or put 'buzz' on PATH)"
  511. )
  512. try:
  513. self._private_key = _resolve_private_key(self._extra)
  514. self._auth_tag = _resolve_auth_tag(self._extra)
  515. except ValueError as exc:
  516. return self._connect_failed("config_invalid", str(exc), "Buzz: invalid owner-auth configuration — %s", exc)
  517. if not self._private_key:
  518. return self._connect_failed(
  519. "config_missing", "BUZZ_PRIVATE_KEY must be set", "Buzz: no private key (set BUZZ_PRIVATE_KEY or a credentials file)"
  520. )
  521. # Own identity: pubkey drives self-echo suppression, display name drives mention gating.
  522. code, out, err = await self._run_cli(["users", "get"])
  523. if code != 0:
  524. message = _cli_error_message(err, code)
  525. return self._connect_failed(
  526. "connect_failed", message, "Buzz: failed to fetch own profile from %s — %s",
  527. self.relay_url, message, retryable=code == 2,
  528. )
  529. profiles = _parse_json_list(out)
  530. if not profiles or not profiles[0].get("pubkey"):
  531. return self._connect_failed(
  532. "connect_failed", "buzz users get returned no profile",
  533. "Buzz: 'users get' returned no profile — is the key a member of this community?", retryable=True,
  534. )
  535. self._self_pubkey = str(profiles[0]["pubkey"]).lower()
  536. self._display_name = str(profiles[0].get("display_name") or "").strip()
  537. self._self_npub = hex_to_npub(self._self_pubkey) or ""
  538. # Two profiles must not drive the same identity on one relay (duplicate replies, split de-dupe state).
  539. if not self._acquire_platform_lock(
  540. "buzz", f"{self.relay_url}:{self._self_pubkey}", f"Buzz identity {self._self_pubkey[:8]}… on {self.relay_url}"):
  541. return False
  542. # Map channel ids to names and pick the watch set.
  543. code, out, err = await self._run_cli(["channels", "list"])
  544. if code != 0:
  545. message = _cli_error_message(err, code)
  546. return self._connect_failed(
  547. "connect_failed", message, "Buzz: failed to list channels — %s", message, retryable=code == 2
  548. )
  549. self._channel_names = {}
  550. for ch in _parse_json_list(out):
  551. if ch_id := ch.get("channel_id"):
  552. self._channel_names[str(ch_id)] = str(ch.get("name") or ch_id)
  553. self._channel_meta[str(ch_id)] = ch
  554. watch = self.channels or list(self._channel_names)
  555. if not watch:
  556. return self._connect_failed(
  557. "config_missing", "no Buzz channels to watch", "Buzz: no channels to watch (configure BUZZ_CHANNELS or join a channel)"
  558. )
  559. # Seed high-water marks so a (re)start never replays history — except where a restored cursor lets
  560. # events that landed while down still dispatch.
  561. # Skip any channel the relay has permanently rejected in a previous session (e.g. "restricted: not a
  562. # channel member") so we don't reconnect-loop on them. See #90464.
  563. self._load_cursors()
  564. for channel_id in watch:
  565. if channel_id in self._restricted_channels:
  566. logger.debug("Buzz: skipping restricted channel %s (relay rejected subscription)", channel_id)
  567. continue
  568. await self._seed_channel(channel_id, chat_type="group")
  569. await self._discover_dms(seed=True)
  570. self._save_cursors()
  571. # Prefer the NIP-42 WebSocket push; poll when it can't be established (auto) or the user pinned "poll".
  572. transport_used = "poll"
  573. if self.transport in ("auto", "websocket"):
  574. if await self._start_websocket():
  575. transport_used = "websocket"
  576. elif self.transport == "websocket":
  577. self._set_fatal_error(
  578. "ws_auth_failed", "Buzz WebSocket transport did not authenticate (transport=websocket)", retryable=True
  579. )
  580. await self.disconnect()
  581. return False
  582. if transport_used == "poll":
  583. self._poll_task = asyncio.create_task(self._poll_loop())
  584. self._mark_connected()
  585. logger.info(
  586. "Buzz: connected to %s as %s, watching %d channel(s) via %s%s",
  587. self.relay_url, self._display_name or self._self_npub[:16], len(self._channel_state),
  588. transport_used, "" if transport_used == "websocket" else f", poll interval {self.poll_interval:.1f}s",
  589. )
  590. self._wire_plugin_handlers(None)
  591. return True
  592. async def disconnect(self) -> None:
  593. """Stop the inbound transport and drop runtime state."""
  594. self._mark_disconnected()
  595. with contextlib.suppress(Exception):
  596. self._release_platform_lock()
  597. await cancel_task(self._ws_task)
  598. self._ws_task = None
  599. await cancel_task(self._poll_task)
  600. self._poll_task = None
  601. self._channel_state = {}
  602. self._poll_count = 0
  603. # ── Sending ───────────────────────────────────────────────────────────
  604. async def _channel_member_pubkeys(self, chat_id: str) -> list[str]:
  605. """Mention candidates: ``channels members`` (a non-member ``--mention`` is rejected by the CLI), else
  606. recent traffic, which over-approximates — ``send()`` recovers by retrying without mentions."""
  607. cache = self._member_cache
  608. if (cached := _ttl_get(cache, str(chat_id), _MEMBER_CACHE_TTL)) is not None:
  609. return list(cached)
  610. pks: list[str] = []
  611. for row in await self._cli_json(["channels", "members", "--channel", str(chat_id)], []):
  612. _add_pubkey(pks, row.get("pubkey") if isinstance(row, dict) else row)
  613. if pks:
  614. cache[str(chat_id)] = (time.monotonic(), list(pks))
  615. return pks
  616. candidates: list[str] = []
  617. for msg in await self._cli_json(["messages", "get", "--channel", str(chat_id), "--limit", "50"], []):
  618. _add_pubkey(candidates, msg.get("pubkey"))
  619. for t in msg.get("tags") or []:
  620. if isinstance(t, list) and len(t) > 1 and t[0] == "p":
  621. _add_pubkey(candidates, str(t[1]))
  622. if candidates:
  623. cache[str(chat_id)] = (time.monotonic(), list(candidates))
  624. return candidates
  625. async def _profile_display_name(self, pubkey: str) -> str:
  626. """Display name via ``users get --pubkey`` (bare ``users get`` may return only our own profile), TTL-cached."""
  627. cache = self._profile_name_cache
  628. if (cached := _ttl_get(cache, pubkey, _PROFILE_NAME_TTL)) is not None:
  629. return cached
  630. name = ""
  631. profiles = await self._cli_json(["users", "get", "--pubkey", pubkey], [])
  632. if profiles and isinstance(p0 := profiles[0], dict):
  633. name = str(p0.get("display_name") or p0.get("name") or "").strip()
  634. if not name and p0.get("content"):
  635. prof = _json_or(p0["content"], {})
  636. name = str(prof.get("display_name") or prof.get("name") or "").strip()
  637. cache[pubkey] = (time.monotonic(), name)
  638. return name
  639. async def _mention_pubkeys_for(self, chat_id: str, content: str) -> list[str]:
  640. """Resolve ``@Name`` tokens to member pubkeys so genuine mentions notify while @-prose stays text.
  641. Word-bounded ("email@Fizz", "@@Fizz", "@FizzBuzz" don't wake Fizz; "@Riley!!" does); longer names
  642. match first and consume their span; ambiguous names tag nobody."""
  643. if "@" not in content:
  644. return []
  645. by_name: dict[str, list[str]] = {}
  646. display: dict[str, str] = {}
  647. self_pk = getattr(self, "_self_pubkey", None)
  648. for pk in await self._channel_member_pubkeys(chat_id):
  649. if pk == self_pk:
  650. continue
  651. name = await self._profile_display_name(pk)
  652. if not name:
  653. continue
  654. key = name.lower()
  655. pks = by_name.setdefault(key, [])
  656. if pk not in pks:
  657. pks.append(pk)
  658. display.setdefault(key, name)
  659. found: list[str] = []
  660. text = content
  661. for key in sorted(by_name, key=len, reverse=True):
  662. pattern = re.compile(r"(?<![\w@])@" + re.escape(display[key]) + r"(?!\w)", re.IGNORECASE)
  663. if pattern.search(text):
  664. pks = by_name[key]
  665. if len(pks) == 1 and pks[0] not in found:
  666. found.append(pks[0])
  667. # Consume the span either way so a shorter prefix name can't double-match
  668. # and an ambiguous name stays presentation-only.
  669. text = pattern.sub("\x00", text)
  670. return found
  671. async def _run_message_send(self, args: list[str], content: str, mention_pubkeys: Optional[list[str]] = None):
  672. """Send with bounded recovery (each rung once): explicit ``--mention``s; on "not channel members" retry
  673. without; escape an unresolvable ``@token`` and retry; finally ``--mention <self>`` (downgrades @names to text).
  674. 1. publish with explicit ``--mention`` pubkeys resolved from the content (#83414) so genuine member
  675. mentions carry p-tags and mention-subscribed agents actually wake; 2. if the CLI rejects because a
  676. resolved pubkey is no longer a member (membership drift), retry without the explicit mentions —
  677. deliver the message rather than lose it; 3. if the CLI's preflight rejects an unresolvable
  678. presentation ``@token`` in prose, escape exactly that token with an invisible separator and retry
  679. (#82646 / #78797); 4. if the error persists and we know our own pubkey, retry once with ``--mention
  680. <self>`` — supplying any explicit identity downgrades unresolvable @names to presentation-only text
  681. (#83414); the echo de-dupe already suppresses self-notification.
  682. """
  683. mention_args: list[str] = []
  684. for pk in mention_pubkeys or []:
  685. mention_args += ["--mention", pk]
  686. code, out, err = await self._run_cli(args + mention_args, input_text=content)
  687. if code == 0:
  688. return code, out, err
  689. if mention_args and "not channel members" in (err or ""):
  690. code, out, err = await self._run_cli(args, input_text=content)
  691. if code == 0:
  692. return code, out, err
  693. escaped = _escape_unresolved_presentation_mention(content, err)
  694. if escaped is not None:
  695. logger.info("Buzz: retrying message after unresolved presentation-mention preflight")
  696. code, out, err = await self._run_cli(args, input_text=escaped)
  697. if code == 0:
  698. return code, out, err
  699. if "does not match a current channel member" in (err or "") and getattr(self, "_self_pubkey", None):
  700. code, out, err = await self._run_cli(args + ["--mention", self._self_pubkey], input_text=content)
  701. return code, out, err
  702. async def send(self, chat_id: str, content: str, reply_to: Optional[str] = None, metadata: Optional[dict[str, Any]] = None) -> SendResult:
  703. if not content:
  704. return SendResult(success=False, error="Empty message")
  705. # Anchor: metadata.thread_id, then metadata.reply_to_message_id (stream/progress sends), then reply_to.
  706. meta = metadata or {}
  707. args = ["messages", "send", "--channel", str(chat_id), "--content", "-"]
  708. args += self._reply_args(meta.get("thread_id") or meta.get("reply_to_message_id") or reply_to)
  709. mention_pubkeys = await self._mention_pubkeys_for(chat_id, content)
  710. code, out, err = await self._run_message_send(args, content, mention_pubkeys)
  711. result = self._send_result(chat_id, code, out, err)
  712. if result.success:
  713. # Record event_meta so a thread reply to this send matches even if the echo never arrives.
  714. self._remember_event_meta(str(chat_id), result.message_id, self._self_pubkey, content)
  715. return result
  716. def _reply_args(self, anchor: Optional[str]) -> list[str]:
  717. """``--reply-to`` CLI args for *anchor*, honoring ``reply_to_mode``."""
  718. reply_target = self._resolve_reply_anchor(anchor)
  719. return ["--reply-to", str(reply_target)] if reply_target and self._reply_to_mode != "off" else []
  720. def _send_result(self, chat_id: str, code: int, out: str, err: str, *, redact_path: Optional[Path] = None) -> SendResult:
  721. """``messages send`` result -> SendResult; marks the verified id seen (echo suppression belt-and-braces)."""
  722. if code != 0:
  723. return SendResult(success=False, error=_cli_error_message(err, code, redact_path=redact_path), retryable=code == 2)
  724. event_id, receipt_error = _parse_send_receipt(out)
  725. if receipt_error:
  726. return SendResult(success=False, error=receipt_error)
  727. assert event_id is not None
  728. # Belt-and-braces echo suppression: the poll loop already skips our own pubkey, but marking the
  729. # verified id seen makes de-dupe explicit. Also record event_meta so a thread reply to this send
  730. # matches even if the WS/poll echo never arrives (#75826).
  731. self._mark_seen(str(chat_id), event_id)
  732. return SendResult(success=True, message_id=event_id)
  733. async def send_typing(self, chat_id: str, metadata=None) -> None:
  734. """Buzz has no typing indicator API — no-op."""
  735. async def send_reaction(self, chat_id: str, message_id: str, emoji: str) -> bool:
  736. """Best-effort reaction via buzz-cli; failures are logged, never raised."""
  737. if not self.cli_path or not emoji or not message_id:
  738. return False
  739. # The event id IS the dispatched message_id; channel is not a parameter here.
  740. code, _out, err = await self._run_cli(["reactions", "add", "--event", str(message_id), "--emoji", emoji])
  741. if code != 0:
  742. logger.debug("Buzz: reaction add failed for message %s in %s — %s", message_id[:12], chat_id, _cli_error_message(err, code))
  743. return code == 0
  744. async def edit_message(self, chat_id: str, message_id: str, content: str, *, finalize: bool = False) -> SendResult:
  745. """Edit a sent message (streamed replies). The CLI reports a NEW event id but the stream consumer
  746. keeps addressing the original, so return the given id, never the CLI's."""
  747. if not message_id:
  748. return SendResult(success=False, error="Buzz edit needs a message id")
  749. if not content:
  750. return SendResult(success=False, error="Empty message")
  751. # Unlike ``messages send``, the CLI's ``messages edit`` takes ``--content`` literally (no ``-``/stdin
  752. # expansion); the ``=`` form keeps clap from reading hyphen-leading text as a flag.
  753. args = ["messages", "edit", "--event", str(message_id), f"--content={content}"]
  754. code, out, err = await self._run_cli(args)
  755. if code != 0:
  756. return SendResult(success=False, error=_cli_error_message(err, code), retryable=code == 2)
  757. data = _json_or(out, {})
  758. if data.get("event_id"):
  759. # The edit is itself a relay event that echoes back on our subscription.
  760. self._mark_seen(str(chat_id), str(data["event_id"]))
  761. return SendResult(success=bool(data.get("accepted", True)), message_id=str(message_id), raw_response=data)
  762. async def delete_message(self, chat_id: str, message_id: str) -> bool:
  763. """Delete a sent message (stream consumer's fresh-final cleanup path)."""
  764. if not message_id:
  765. return False
  766. code, out, _err = await self._run_cli(["messages", "delete", "--event", str(message_id)])
  767. if code != 0:
  768. return False
  769. try:
  770. data = json.loads(out or "{}")
  771. except ValueError:
  772. return True
  773. if data.get("event_id"):
  774. self._mark_seen(str(chat_id), str(data["event_id"]))
  775. return bool(data.get("accepted", True))
  776. async def send_image(
  777. self, chat_id: str, image_url: str, caption: Optional[str] = None, reply_to: Optional[str] = None,
  778. metadata: Optional[dict[str, Any]] = None) -> SendResult:
  779. """Send an image: local files upload via --file, URLs go as a link."""
  780. local = Path(image_url).expanduser() if not image_url.startswith(("http://", "https://")) else None
  781. if local is not None and local.is_file():
  782. return await self._send_file_attachment(chat_id, local, caption=caption, reply_to=reply_to, metadata=metadata, probe=False)
  783. # Markdown renders in Buzz, so a URL arrives as a clickable image link.
  784. text = f"{caption}\n{image_url}" if caption else image_url
  785. return await self.send(chat_id, text, reply_to=reply_to, metadata=metadata)
  786. async def _send_file_attachment(
  787. self, chat_id: str, file_path: Path, *, caption: Optional[str] = None, reply_to: Optional[str] = None,
  788. metadata: Optional[dict[str, Any]] = None, probe: bool = True,
  789. ) -> SendResult:
  790. """Upload a local file as a native attachment; ``probe=False`` when the caller already verified it (a re-probe could race).
  791. See #74999.
  792. """
  793. local = Path(file_path).expanduser()
  794. if probe and not local.is_file():
  795. # Never leak host filesystem paths into chat-visible errors.
  796. return SendResult(success=False, error="Media file not found")
  797. args = ["messages", "send", "--channel", str(chat_id), "--file", str(local), "--content", "-"]
  798. args += self._reply_args((metadata or {}).get("thread_id") or reply_to)
  799. code, out, err = await self._run_message_send(args, caption or "")
  800. return self._send_result(chat_id, code, out, err, redact_path=local)
  801. async def send_image_file(
  802. self, chat_id: str, image_path: str, caption: Optional[str] = None, reply_to: Optional[str] = None,
  803. metadata: Optional[dict[str, Any]] = None, **kwargs) -> SendResult:
  804. """Upload a local image via ``--file``; missing paths keep the Base fallback so host paths never reach chat.
  805. See #74999.
  806. """
  807. local = Path(image_path).expanduser()
  808. if local.is_file():
  809. return await self._send_file_attachment(chat_id, local, caption=caption, reply_to=reply_to, metadata=metadata, probe=False)
  810. return await super().send_image_file(chat_id=chat_id, image_path=image_path, caption=caption, reply_to=reply_to, metadata=metadata, **kwargs)
  811. async def send_document(
  812. self, chat_id: str, file_path: str, caption: Optional[str] = None, file_name: Optional[str] = None,
  813. reply_to: Optional[str] = None, metadata: Optional[dict[str, Any]] = None, **kwargs) -> SendResult:
  814. """Upload a local document through Buzz's native ``--file`` path."""
  815. return await self._send_file_attachment(chat_id, Path(file_path), caption=caption, reply_to=reply_to, metadata=metadata)
  816. async def send_video(
  817. self, chat_id: str, video_path: str, caption: Optional[str] = None, reply_to: Optional[str] = None,
  818. metadata: Optional[dict[str, Any]] = None, **kwargs) -> SendResult:
  819. """Upload a local video through Buzz's native ``--file`` path."""
  820. return await self._send_file_attachment(chat_id, Path(video_path), caption=caption, reply_to=reply_to, metadata=metadata)
  821. async def send_voice(
  822. self, chat_id: str, audio_path: str, caption: Optional[str] = None, reply_to: Optional[str] = None,
  823. metadata: Optional[dict[str, Any]] = None, **kwargs) -> SendResult:
  824. """Upload a local audio file through Buzz's native ``--file`` path."""
  825. return await self._send_file_attachment(chat_id, Path(audio_path), caption=caption, reply_to=reply_to, metadata=metadata)
  826. async def get_chat_info(self, chat_id: str) -> dict[str, Any]:
  827. chat_id = str(chat_id)
  828. state = self._channel_state.get(chat_id)
  829. if (name := self._channel_names.get(chat_id)) is None and self.cli_path:
  830. data = await self._cli_json(["channels", "get", "--channel", chat_id], {})
  831. if isinstance(data, dict) and data.get("name"):
  832. name = self._channel_names[chat_id] = str(data["name"])
  833. return {"name": name or chat_id, "type": state["chat_type"] if state else "group", "chat_id": chat_id}
  834. # ── Inbound: WebSocket transport (NIP-42) — same _handle_event() as the poll loop ──────
  835. # ── Inbound: WebSocket transport (NIP-42 authenticated) ────────────── Push transport contributed in PR
  836. # #73636 by @ScaleLeanChris, adapted to dispatch through the same _handle_event() machinery as the poll
  837. # loop so de-dupe, mention gating, DM latching, and the allow-list behave identically on both
  838. # transports.
  839. def _websocket_url(self) -> str:
  840. parsed = urlsplit(self.relay_url.strip())
  841. scheme = {"http": "ws", "https": "wss"}.get(parsed.scheme, parsed.scheme)
  842. if scheme not in ("ws", "wss") or not parsed.netloc:
  843. raise ValueError("Buzz relay URL must use http(s) or ws(s)")
  844. return urlunsplit((scheme, parsed.netloc, parsed.path or "", parsed.query, ""))
  845. async def _start_websocket(self) -> bool:
  846. """Start the WS loop; True when it authenticates within the timeout."""
  847. try:
  848. import websockets
  849. self._websocket_url()
  850. except Exception as e:
  851. logger.info("Buzz: WebSocket transport unavailable (%s); falling back to polling", e)
  852. return False
  853. self._ws_ready = asyncio.Event()
  854. self._membership_since = int(time.time())
  855. self._ws_task = asyncio.create_task(self._websocket_loop())
  856. try:
  857. await asyncio.wait_for(self._ws_ready.wait(), timeout=_WS_AUTH_TIMEOUT + 5)
  858. return True
  859. except TimeoutError:
  860. logger.warning("Buzz: WebSocket did not authenticate in time")
  861. await cancel_task(self._ws_task)
  862. self._ws_task = None
  863. return False
  864. async def _authenticate_websocket(self, websocket) -> None:
  865. """NIP-42: await the AUTH challenge, answer with a signed kind-22242 event (+ optional NIP-OA tag), await OK."""
  866. message = json.loads(await asyncio.wait_for(websocket.recv(), timeout=_WS_AUTH_TIMEOUT))
  867. if not isinstance(message, list) or len(message) < 2 or message[0] != "AUTH":
  868. raise ConnectionError("Buzz relay did not send a NIP-42 AUTH challenge")
  869. # BUZZ_AUTH_TAG is per-identity: a scoped profile without one fails closed to "" rather than borrowing
  870. # the default profile's env tag. Resolved lazily so a re-auth on a bare adapter stays scope-correct.
  871. # BUZZ_AUTH_TAG is per-identity NIP-OA owner attestation, so it must resolve through the profile
  872. # secret scope (#98738): inside a scoped multiplex profile a missing tag fails closed to "" instead
  873. # of attaching the default profile's tag from os.environ, while single-profile and unscoped
  874. # default-profile reads keep the legacy env behavior. connect() populates ``self._auth_tag`` via
  875. # ``_resolve_auth_tag`` (scope-aware read + credentials-file fallback, #79514); resolve lazily here
  876. # as well so a re-auth on a bare adapter stays scope-correct.
  877. auth_tag = getattr(self, "_auth_tag", "") or ""
  878. if not auth_tag:
  879. try:
  880. auth_tag = _resolve_auth_tag(getattr(self, "_extra", None))
  881. except ValueError:
  882. auth_tag = ""
  883. event = _nostr_auth.build_auth_event(private_key=self._private_key, challenge=str(message[1]), relay_url=self._websocket_url(), auth_tag_json=auth_tag)
  884. await websocket.send(json.dumps(["AUTH", event], separators=(",", ":")))
  885. while True:
  886. response = json.loads(await asyncio.wait_for(websocket.recv(), timeout=_WS_AUTH_TIMEOUT))
  887. if not isinstance(response, list) or not response:
  888. continue
  889. if response[0] == "OK" and len(response) >= 4 and response[1] == event["id"]:
  890. if response[2] is True:
  891. return
  892. raise ConnectionError(f"Buzz WebSocket AUTH rejected: {response[3]}")
  893. if response[0] in ("NOTICE", "CLOSED"):
  894. raise ConnectionError(f"Buzz WebSocket AUTH failed: {response[-1] if len(response) > 1 else 'authentication failed'}")
  895. @staticmethod
  896. async def _send_req(websocket, subscription_id: str, request_filter: dict) -> None:
  897. await websocket.send(json.dumps(["REQ", subscription_id, request_filter], separators=(",", ":")))
  898. async def _send_channel_subscription(self, websocket, subscription_id: str, channel_id: str) -> None:
  899. state = self._channel_state.get(channel_id) or {}
  900. last_ts = int(state.get("last_ts") or 0)
  901. # A conversation adopted mid-run with no high-water mark is fresh: its history IS the conversation,
  902. # so subscribe from the beginning instead of `since ≈ now` — otherwise the message that *created*
  903. # the conversation (created_at fractionally before this subscription) is silently dropped (#78429).
  904. # `limit` bounds the replay to the same window the poll transport fetches; the seed path gives real
  905. # channels a non-zero last_ts, so they never take this branch.
  906. request_filter = {"kinds": sorted(_DISPATCH_KINDS), "#h": [channel_id]}
  907. if last_ts:
  908. # Resume from the high-water mark (same-second overlap de-duped by id).
  909. request_filter["since"] = max(last_ts - 1, 0)
  910. else:
  911. # A conversation adopted mid-run with no high-water mark is fresh: its history IS the conversation,
  912. # so subscribe from the start or the message that *created* it is dropped. Seeded channels have last_ts != 0.
  913. request_filter["limit"] = _FETCH_LIMIT
  914. await self._send_req(websocket, subscription_id, request_filter)
  915. async def _subscribe_websocket(self, websocket) -> dict[str, Optional[str]]:
  916. """Subscribe to every watched conversation plus membership events (kind 44100 p-tagged to us) for DM discovery."""
  917. subscriptions: dict[str, Optional[str]] = {}
  918. for index, channel_id in enumerate(list(self._channel_state)):
  919. if channel_id in self._restricted_channels:
  920. continue
  921. subscriptions[f"hermes-buzz-{index}"] = channel_id
  922. await self._send_channel_subscription(websocket, f"hermes-buzz-{index}", channel_id)
  923. if self._self_pubkey:
  924. membership = {"kinds": [_WS_MEMBERSHIP_KIND], "#p": [self._self_pubkey], "since": max(self._membership_since - 1, 0)}
  925. await self._send_req(websocket, _WS_MEMBERSHIP_SUB_ID, membership)
  926. subscriptions[_WS_MEMBERSHIP_SUB_ID] = None
  927. return subscriptions
  928. async def _rediscover_and_subscribe(self, websocket, subscriptions: dict[str, Optional[str]]) -> None:
  929. """Rediscover conversations and subscribe to any adopted since (fresh DMs dispatch from their start)."""
  930. before = set(self._channel_state)
  931. await self._discover_dms(seed=False)
  932. for channel_id in list(self._channel_state):
  933. if channel_id in before:
  934. continue
  935. subscription_id = f"hermes-buzz-dm-{len(subscriptions)}"
  936. subscriptions[subscription_id] = channel_id
  937. await self._send_channel_subscription(websocket, subscription_id, channel_id)
  938. logger.info("Buzz: subscribed to new conversation %s", channel_id)
  939. async def _ws_discovery_loop(self, websocket, subscriptions: dict[str, Optional[str]]) -> None:
  940. """Periodic discovery on the poll cadence: relays don't guarantee a kind-44100 event for every new
  941. conversation. Failures retry next tick, except a closed socket: that is the same dead connection the
  942. read loop may still be parked on, so it propagates and tears the connection down (#112049).
  943. The kind-44100 membership subscription is the fast path, but relays do not guarantee a membership
  944. event for every conversation that materializes mid-session (#93557) — some emit none at all for new
  945. DM-shaped conversations. The poll transport papers over this by re-running discovery every
  946. ``_DM_DISCOVERY_EVERY`` sweeps; this loop gives the WS transport the same guarantee on the same
  947. cadence.
  948. """
  949. from websockets.exceptions import ConnectionClosed
  950. interval = max(self.poll_interval * _DM_DISCOVERY_EVERY, _MIN_POLL_INTERVAL)
  951. while True:
  952. await asyncio.sleep(interval)
  953. try:
  954. await self._rediscover_and_subscribe(websocket, subscriptions)
  955. except (asyncio.CancelledError, ConnectionClosed):
  956. raise
  957. except Exception:
  958. logger.warning("Buzz: WebSocket discovery sweep failed", exc_info=True)
  959. async def _websocket_loop(self) -> None:
  960. """Persistent authenticated subscription with bounded reconnect backoff; `since` filters resume on reconnect."""
  961. import websockets
  962. backoff = 1.0
  963. reconnecting = False
  964. while True:
  965. try:
  966. async with websockets.connect(
  967. self._websocket_url(), open_timeout=_WS_AUTH_TIMEOUT, close_timeout=5,
  968. ping_interval=20, ping_timeout=20, max_size=_WS_MAX_MESSAGE_BYTES,
  969. happy_eyeballs_delay=0.25, # race IPv6/IPv4 in loop.create_connection (#114265)
  970. ) as websocket:
  971. await self._authenticate_websocket(websocket)
  972. subscriptions = await self._subscribe_websocket(websocket)
  973. if self._ws_ready is not None:
  974. self._ws_ready.set()
  975. if reconnecting:
  976. # connect() published "connected" once; a recovered socket has to say so again.
  977. reconnecting = False
  978. self._mark_connected()
  979. backoff = 1.0
  980. # Whichever side notices the dead socket first ends the connection: the read loop's idle
  981. # bound, or a discovery send() raising ConnectionClosed while the read is still parked.
  982. tasks = {
  983. asyncio.create_task(self._ws_read_loop(websocket, subscriptions)),
  984. asyncio.create_task(self._ws_discovery_loop(websocket, subscriptions)),
  985. }
  986. try:
  987. done, _ = await asyncio.wait(tasks, return_when=asyncio.FIRST_COMPLETED)
  988. for finished in done:
  989. finished.result()
  990. finally:
  991. for task in tasks:
  992. task.cancel()
  993. await asyncio.gather(*tasks, return_exceptions=True)
  994. except asyncio.CancelledError:
  995. raise
  996. except Exception as e:
  997. # The health map only ever saw "connected"; say "retrying" until the socket is back (#112049).
  998. if not reconnecting:
  999. reconnecting = True
  1000. self._mark_degraded()
  1001. logger.warning("Buzz: WebSocket disconnected; retrying in %.1fs: %s", backoff, e)
  1002. await asyncio.sleep(backoff)
  1003. backoff = min(backoff * 2, 30.0)
  1004. async def _ws_read_loop(self, websocket, subscriptions: dict[str, Optional[str]]) -> None:
  1005. """Read frames until the relay closes; a close or an idle read raises ConnectionError to reconnect."""
  1006. frame_iter = websocket.__aiter__()
  1007. while True:
  1008. read_task = asyncio.ensure_future(frame_iter.__anext__())
  1009. try:
  1010. done, _ = await asyncio.wait(
  1011. {read_task}, timeout=_WS_READ_IDLE_TIMEOUT, return_when=asyncio.FIRST_COMPLETED
  1012. )
  1013. if not done:
  1014. # wait_for() cancels and then waits for its awaitable to acknowledge the cancellation.
  1015. # A transport receive stuck below asyncio can ignore that cancellation forever, leaving the
  1016. # adapter healthy-looking. Detach the read instead so the outer loop can close and reconnect.
  1017. raise ConnectionError(
  1018. f"no WebSocket frame for {_WS_READ_IDLE_TIMEOUT:.0f}s; assuming the connection went silent"
  1019. )
  1020. raw = read_task.result()
  1021. except StopAsyncIteration:
  1022. # A clean relay close is still a disconnect: raising sends it through the same
  1023. # backoff + "retrying" path instead of reconnecting in a hot loop.
  1024. raise ConnectionError("relay closed the WebSocket") from None
  1025. finally:
  1026. if not read_task.done():
  1027. read_task.cancel()
  1028. read_task.add_done_callback(_consume_ws_read_task)
  1029. try:
  1030. message = json.loads(raw)
  1031. except (ValueError, TypeError):
  1032. logger.warning("Buzz: ignoring malformed WebSocket frame")
  1033. continue
  1034. if isinstance(message, list) and message:
  1035. await self._handle_ws_message(websocket, subscriptions, message)
  1036. async def _handle_ws_message(self, websocket, subscriptions: dict[str, Optional[str]], message: list) -> None:
  1037. """Route one parsed relay frame (EVENT / CLOSED / NOTICE)."""
  1038. if message[0] == "EVENT" and len(message) >= 3:
  1039. subscription_id, event = str(message[1]), message[2]
  1040. if not isinstance(event, dict):
  1041. return
  1042. if subscription_id == _WS_MEMBERSHIP_SUB_ID:
  1043. # A membership event p-tagged to us: rediscover and subscribe to new conversations.
  1044. self._membership_since = max(self._membership_since, int(event.get("created_at") or 0))
  1045. await self._rediscover_and_subscribe(websocket, subscriptions)
  1046. return
  1047. channel_id = subscriptions.get(subscription_id)
  1048. state = self._channel_state.get(channel_id or "")
  1049. if channel_id and state is not None:
  1050. await self._handle_events(channel_id, state, [event])
  1051. elif message[0] == "CLOSED":
  1052. detail = message[-1] if len(message) > 2 else "subscription closed"
  1053. sub_id = str(message[1]) if len(message) > 1 else ""
  1054. closed_channel = subscriptions.get(sub_id)
  1055. # A membership rejection is permanent — drop the channel instead of reconnect-looping.
  1056. rejected = any(m in str(detail).lower() for m in ("restricted", "not a channel member", "auth-required"))
  1057. if not (rejected and closed_channel):
  1058. raise ConnectionError(str(detail))
  1059. logger.warning("Buzz: relay permanently rejected channel %s (%s) — removing from watch list", closed_channel, detail)
  1060. self._restricted_channels.add(closed_channel)
  1061. del subscriptions[sub_id]
  1062. self._channel_state.pop(closed_channel, None)
  1063. elif message[0] == "NOTICE":
  1064. logger.warning("Buzz: relay notice: %s", message[-1])
  1065. # ── Inbound polling ───────────────────────────────────────────────────
  1066. async def _poll_loop(self) -> None:
  1067. """Poll every watched channel for new events until cancelled."""
  1068. while True:
  1069. await asyncio.sleep(self.poll_interval)
  1070. self._poll_count += 1
  1071. try:
  1072. if self._poll_count % _DM_DISCOVERY_EVERY == 0:
  1073. await self._discover_dms(seed=False)
  1074. for channel_id in list(self._channel_state):
  1075. await self._poll_channel(channel_id)
  1076. except asyncio.CancelledError:
  1077. raise
  1078. except Exception:
  1079. logger.warning("Buzz: poll sweep failed", exc_info=True)
  1080. def _new_channel_state(self, chat_type: str) -> dict:
  1081. return {"chat_type": chat_type, "last_ts": 0, "seen": OrderedDict(), "event_meta": OrderedDict()}
  1082. def _restore_channel_state(self, channel_id: str, chat_type: str) -> bool:
  1083. """Install a persisted cursor (True when one existed): seeding would mark downtime arrivals as seen.
  1084. Restoring is what closes the restart gap: seeding from current history instead would mark everything
  1085. that arrived while the gateway was down as already seen, so the relay's durable copy is never
  1086. dispatched (#90464).
  1087. """
  1088. restored = self._restored_cursors.pop(channel_id, None)
  1089. if restored is None:
  1090. return False
  1091. state = self._new_channel_state(restored["chat_type"] or chat_type)
  1092. state["last_ts"] = restored["last_ts"]
  1093. state["seen"] = OrderedDict((event_id, None) for event_id in restored["seen"])
  1094. self._channel_state[channel_id] = state
  1095. return True
  1096. async def _seed_channel(self, channel_id: str, chat_type: str) -> None:
  1097. """Initialize a channel's high-water mark from its newest events."""
  1098. if self._restore_channel_state(channel_id, chat_type):
  1099. return
  1100. state = self._channel_state[channel_id] = self._new_channel_state(chat_type)
  1101. code, out, err = await self._run_cli(["messages", "get", "--channel", channel_id, "--limit", str(_FETCH_LIMIT)])
  1102. if code != 0:
  1103. logger.warning("Buzz: could not seed channel %s — %s", channel_id, _cli_error_message(err, code))
  1104. # "now" so a transiently unreadable channel never replays its history later.
  1105. state["last_ts"] = int(time.time())
  1106. return
  1107. for event in _parse_json_list(out):
  1108. if event_id := event.get("id"):
  1109. state["seen"][str(event_id)] = None
  1110. state["last_ts"] = max(state["last_ts"], int(event.get("created_at") or 0))
  1111. # History is never dispatched but feeds event_meta (post-restart replies to us must match) and latches DMs.
  1112. # See #75826.
  1113. self._remember_event(state, event)
  1114. self._maybe_latch_dm(channel_id, state, event)
  1115. self._trim_seen(state)
  1116. async def _discover_dms(self, *, seed: bool) -> None:
  1117. """Watch DMs: startup ones are seeded, mid-run ones dispatch from their start. ``dms list`` is best-effort
  1118. (some relays return ``[]``); the fallback shape is a ``channels list`` entry named "DM" with empty
  1119. description. Named rooms and missing metadata fail closed as groups.
  1120. ``dms list`` is only a best-effort source: on some hosted relays it returns ``[]`` even when DM
  1121. conversations exist (#68871).
  1122. """
  1123. code, out, _err = await self._run_cli(["dms", "list"])
  1124. for dm in _parse_json_list(out) if code == 0 else []:
  1125. dm_id = str(dm.get("dm_id") or "")
  1126. if dm_id and dm_id not in self._channel_state and dm_id not in self._restricted_channels:
  1127. await self._adopt_conversation(dm_id, seed)
  1128. self._channel_names.setdefault(dm_id, "DM")
  1129. code, out, _err = await self._run_cli(["channels", "list"])
  1130. if code != 0:
  1131. return
  1132. for ch in _parse_json_list(out):
  1133. if not (ch_id := str(ch.get("channel_id") or "")):
  1134. continue
  1135. self._channel_meta[ch_id] = ch
  1136. self._channel_names.setdefault(ch_id, str(ch.get("name") or ch_id))
  1137. if ch_id in self._restricted_channels:
  1138. continue
  1139. if self._may_reclassify_as_dm(ch_id):
  1140. # DM-shaped entries promote to DM — including ones already watched.
  1141. # See #77987, #87899, #99431.
  1142. if ch_id in self._channel_state:
  1143. self._channel_state[ch_id]["chat_type"] = "dm"
  1144. else:
  1145. await self._adopt_conversation(ch_id, seed)
  1146. elif ch_id not in self._channel_state and not seed and not self.channels:
  1147. # Watch-all mode adopts channels joined mid-run (seeded: history predates us); explicit lists stay authoritative.
  1148. # Live adoption of real community channels joined mid-run (#75107): in watch-all mode (no
  1149. # explicit channels list) a channel the agent is added to after connect() must start
  1150. # dispatching without a gateway restart. Unlike a fresh DM its history predates us, so it is
  1151. # always seeded from its newest events — only messages sent after adoption dispatch.
  1152. await self._seed_channel(ch_id, chat_type="group")
  1153. logger.info("Buzz: adopted newly joined channel %s (%s)", ch_id, self._channel_names.get(ch_id, ch_id))
  1154. async def _adopt_conversation(self, channel_id: str, seed: bool) -> None:
  1155. """Start watching a DM conversation: seed at startup, else restore or start fresh."""
  1156. if seed:
  1157. await self._seed_channel(channel_id, chat_type="dm")
  1158. elif not self._restore_channel_state(channel_id, "dm"):
  1159. self._channel_state[channel_id] = self._new_channel_state("dm")
  1160. async def _poll_channel(self, channel_id: str) -> None:
  1161. state = self._channel_state.get(channel_id)
  1162. if state is None:
  1163. return
  1164. args = ["messages", "get", "--channel", channel_id, "--limit", str(_FETCH_LIMIT)]
  1165. if state["last_ts"]:
  1166. # Nostr `since` is inclusive: same-second events re-fetch and de-dupe by id.
  1167. args += ["--since", str(state["last_ts"])]
  1168. code, out, err = await self._run_cli(args)
  1169. if code != 0:
  1170. logger.debug("Buzz: poll of channel %s failed — %s", channel_id, _cli_error_message(err, code))
  1171. return
  1172. await self._handle_events(channel_id, state, _parse_json_list(out))
  1173. async def _handle_events(self, channel_id: str, state: dict, events: list[dict]) -> None:
  1174. """Handle a batch, trim, and persist only when the cursor moved (idle channels don't rewrite the file)."""
  1175. before = self._cursor_mark(state)
  1176. for event in events:
  1177. await self._handle_event(channel_id, state, event)
  1178. self._trim_seen(state)
  1179. if self._cursor_mark(state) != before: # never past a busy input held uncommitted (serial reader)
  1180. from gateway.session_ingress_burst import when_returned_inputs_durable
  1181. await when_returned_inputs_durable(self, self._cursor_writer())
  1182. @staticmethod
  1183. def _parse_imeta_attachments(event: dict) -> tuple[list[dict], int]:
  1184. """Return accepted NIP-94 metadata and the rejected ``imeta`` count."""
  1185. tags = event.get("tags")
  1186. if not isinstance(tags, list):
  1187. return [], 0
  1188. attachments: list[dict] = []
  1189. rejected = total_declared_bytes = 0
  1190. for tag in tags:
  1191. if not isinstance(tag, (list, tuple)) or not tag or tag[0] != "imeta":
  1192. continue
  1193. if len(attachments) >= _MAX_INBOUND_ATTACHMENTS:
  1194. rejected += 1
  1195. continue
  1196. fields: dict[str, str] = {}
  1197. for key, separator, value in (f.partition(" ") for f in tag[1:] if isinstance(f, str)):
  1198. if separator and key not in fields:
  1199. fields[key] = value.strip()
  1200. url, digest = fields.get("url", ""), fields.get("x", "").lower()
  1201. try:
  1202. size = int(fields.get("size", ""))
  1203. parsed = urlsplit(url)
  1204. parsed_hostname = parsed.hostname
  1205. parsed.port # access validates malformed/non-numeric ports
  1206. except (TypeError, ValueError):
  1207. rejected += 1
  1208. continue
  1209. if (
  1210. parsed.scheme != "https" or not parsed_hostname or parsed.username or parsed.password or parsed.fragment
  1211. or not _HEX64_RE.fullmatch(digest) or not 0 < size <= _MAX_INBOUND_ATTACHMENT_BYTES
  1212. or total_declared_bytes + size > _MAX_INBOUND_ATTACHMENT_BYTES
  1213. ):
  1214. rejected += 1
  1215. continue
  1216. total_declared_bytes += size
  1217. attachments.append({"url": url, "sha256": digest, "size": size,
  1218. "filename": _safe_attachment_filename(fields.get("filename", "")), "mime_type": fields.get("m", "")[:255]})
  1219. return attachments, rejected
  1220. @staticmethod
  1221. def _imeta_attachments(event: dict) -> list[dict]:
  1222. """Return bounded, structurally valid NIP-94 attachment metadata."""
  1223. return BuzzAdapter._parse_imeta_attachments(event)[0]
  1224. @staticmethod
  1225. def _attachment_rejection_note(rejected: int) -> str:
  1226. """Return a fixed-width diagnostic for malformed or excess metadata."""
  1227. return f"[{rejected if rejected <= 999 else '999+'} Buzz attachment(s) rejected as malformed or over limits.]"
  1228. async def _download_attachment(self, metadata: dict) -> Optional[CachedMedia]:
  1229. """Download, integrity-check, and cache one authorized Buzz attachment."""
  1230. url = metadata["url"]
  1231. try:
  1232. parsed_url = urlsplit(url)
  1233. origin = ((parsed_url.hostname or "").lower().rstrip("."), parsed_url.port or 443)
  1234. except ValueError:
  1235. parsed_url, origin = None, ("", 0)
  1236. if parsed_url is None or parsed_url.scheme != "https" or origin not in self._attachment_origins:
  1237. logger.warning("Buzz: refusing attachment from untrusted origin %s:%s", origin[0] or "<missing>", origin[1])
  1238. return None
  1239. import httpx
  1240. try:
  1241. timeout = httpx.Timeout(_ATTACHMENT_DOWNLOAD_TIMEOUT)
  1242. async with (
  1243. asyncio.timeout(_ATTACHMENT_DOWNLOAD_TIMEOUT),
  1244. httpx.AsyncClient(follow_redirects=False, timeout=timeout, headers={"Accept-Encoding": "identity"}) as client,
  1245. client.stream("GET", url) as response,
  1246. ):
  1247. if response.status_code != 200:
  1248. logger.warning("Buzz: attachment download returned HTTP %s", response.status_code)
  1249. return None
  1250. if content_length := response.headers.get("content-length"):
  1251. try:
  1252. declared_response_size = int(content_length)
  1253. except ValueError:
  1254. return None
  1255. if declared_response_size != metadata["size"]:
  1256. logger.warning("Buzz: attachment Content-Length does not match imeta size")
  1257. return None
  1258. data = bytearray()
  1259. async for chunk in response.aiter_bytes():
  1260. data.extend(chunk)
  1261. if len(data) > metadata["size"]:
  1262. logger.warning("Buzz: attachment exceeded its declared size")
  1263. return None
  1264. except (TimeoutError, httpx.HTTPError, OSError, ValueError) as exc:
  1265. logger.warning("Buzz: attachment download failed: %s", exc)
  1266. return None
  1267. for bad, what in ((len(data) != metadata["size"], "size"), (hashlib.sha256(data).hexdigest() != metadata["sha256"], "SHA-256")):
  1268. if bad:
  1269. logger.warning("Buzz: attachment %s does not match imeta", what)
  1270. return None
  1271. try:
  1272. return await cache_media_bytes_async(bytes(data), filename=metadata["filename"], mime_type=metadata["mime_type"])
  1273. except (OSError, ValueError) as exc:
  1274. logger.warning("Buzz: attachment cache write failed: %s", exc)
  1275. return None
  1276. async def _cache_inbound_attachments(self, metadata_items: list[dict]) -> list[CachedMedia]:
  1277. return [a for m in metadata_items if (a := await self._download_attachment(m)) is not None]
  1278. async def _handle_event(self, channel_id: str, state: dict, event: dict) -> None:
  1279. """De-dupe, filter, and dispatch a single ``messages get`` event."""
  1280. event_id = str(event.get("id") or "")
  1281. created_at = int(event.get("created_at") or 0)
  1282. if not event_id or event_id in state["seen"]:
  1283. return
  1284. state["seen"][event_id] = None
  1285. state["last_ts"] = max(state["last_ts"], created_at)
  1286. if int(event.get("kind") or 0) not in _DISPATCH_KINDS:
  1287. return
  1288. pubkey = str(event.get("pubkey") or "").lower()
  1289. content = event.get("content")
  1290. attachment_metadata, rejected_attachments = self._parse_imeta_attachments(event)
  1291. if not pubkey or not isinstance(content, str) or not (content.strip() or attachment_metadata or rejected_attachments):
  1292. return
  1293. # Cache before any early return so self-echo and concurrent-author traffic can still be reply parents.
  1294. self._remember_event(state, event)
  1295. # See #75826.
  1296. if pubkey == self._self_pubkey:
  1297. return
  1298. # Reclassify a leaked DM before gating so its first un-mentioned message both latches and dispatches.
  1299. self._maybe_latch_dm(channel_id, state, event)
  1300. is_dm = state["chat_type"] == "dm"
  1301. reply_parent_id = _event_reply_parent_id(event)
  1302. reply_meta = self._lookup_event_meta(state, reply_parent_id) if reply_parent_id else None
  1303. reply_to_is_own = bool(reply_meta is not None and reply_meta[0] == self._self_pubkey)
  1304. # Channels dispatch only when addressed (@mention or p-tag) or replying to us (Signal/WhatsApp parity),
  1305. # unless require_mention is off. DMs always dispatch.
  1306. if not is_dm and self.require_mention and not self._is_addressed(event) and not reply_to_is_own:
  1307. return
  1308. # Adapter-level allow-list (gateway also applies it centrally); empty = no filter.
  1309. if self._allowed_pubkeys and pubkey not in self._allowed_pubkeys:
  1310. if pubkey in self._reaction_only_pubkeys and _p_tagged(event, self._self_pubkey) and self._is_mentioned(content):
  1311. await self.send_reaction(channel_id, event_id, "👀")
  1312. logger.debug("Buzz: ignoring message from unauthorized pubkey %s…", pubkey[:8])
  1313. return
  1314. # Strip a leading @mention (DMs often open with one too) so "@Chip /whoami" is recognized as a command.
  1315. dispatch_text = self._strip_mention(content)
  1316. # NIP-10 root scopes the session; remember it so our reply joins the SAME thread instead of nesting.
  1317. thread_id = self._extract_thread_root(event)
  1318. self._record_thread_root(event_id, event)
  1319. # Attachment fetch spends credentials: only the gateway's explicit ``True`` permits it (else fail closed).
  1320. # The message still dispatches so GatewayRunner can apply denial/pairing.
  1321. chat_type = "dm" if is_dm else "group"
  1322. fetch_allowed = bool(attachment_metadata) and self._is_sender_authorized(pubkey, chat_type, channel_id) is True
  1323. attachments = await self._cache_inbound_attachments(attachment_metadata) if fetch_allowed else []
  1324. if rejected_attachments:
  1325. dispatch_text = f"{dispatch_text}\n{self._attachment_rejection_note(rejected_attachments)}".strip()
  1326. if fetch_allowed and (failed := len(attachment_metadata) - len(attachments)):
  1327. dispatch_text = f"{dispatch_text}\n[{failed} Buzz attachment(s) could not be downloaded or failed integrity checks.]".strip()
  1328. message_type = MessageType.TEXT
  1329. if attachments:
  1330. # Mixed kinds use document semantics so an audio member is not mistaken for a voice note (STT).
  1331. kinds = {attachment.kind for attachment in attachments}
  1332. message_type = _ATTACHMENT_KIND_TYPES.get(next(iter(kinds)), MessageType.DOCUMENT) if len(kinds) == 1 else MessageType.DOCUMENT
  1333. await self._dispatch_message(
  1334. text=dispatch_text, chat_id=channel_id, chat_type=chat_type, user_id=pubkey,
  1335. user_name=await self._resolve_user_name(pubkey), message_id=event_id,
  1336. created_at=created_at, thread_id=thread_id, reply_to_message_id=reply_parent_id,
  1337. reply_to_text=reply_meta[1] if reply_meta else None, reply_to_author_id=reply_meta[0] if reply_meta else None,
  1338. reply_to_is_own_message=reply_to_is_own, media_urls=[attachment.path for attachment in attachments],
  1339. media_types=[attachment.media_type for attachment in attachments], message_type=message_type, raw_message=event,
  1340. )
  1341. # ── DM classification: DMs leak in via ``channels list`` as "group"; a real channel's p-tag is only addressing ──
  1342. # ── DM classification (issue #68871) ────────────────────────────────── ``buzz dms list`` returns [] on
  1343. # some hosted relays even when DM conversations exist, so DMs can leak in through ``channels list`` as
  1344. # chat_type="group". Relay-materialized DMs are named "DM" with an empty description, which periodic
  1345. # discovery promotes to DM even when messages omit recipient p-tags. Named channels and missing metadata
  1346. # fail closed. In normal channels a p-tag is only an addressing signal and must wake the agent without
  1347. # changing the conversation type.
  1348. def _may_reclassify_as_dm(self, channel_id: str) -> bool:
  1349. """True when metadata does not rule out a DM (name "DM", empty description); missing metadata fails closed."""
  1350. meta = self._channel_meta.get(channel_id)
  1351. if meta is None:
  1352. return False
  1353. return str(meta.get("name") or "").strip() == "DM" and not str(meta.get("description") or "").strip()
  1354. def _p_tagged_to_self(self, event: dict) -> bool:
  1355. """True when the signed event addresses this identity by pubkey."""
  1356. return bool(self._self_pubkey) and _p_tagged(event, self._self_pubkey)
  1357. def _is_direct_message_event(self, channel_id: str, event: dict) -> bool:
  1358. """Kind-9 from another user, p-tagged to us, text NOT mentioning us — structural DM addressing, not a typed @."""
  1359. pubkey = str(event.get("pubkey") or "").lower()
  1360. content = event.get("content")
  1361. return bool(
  1362. self._self_pubkey and self._may_reclassify_as_dm(channel_id) and int(event.get("kind") or 0) == _CHAT_KIND
  1363. and pubkey and pubkey != self._self_pubkey and self._p_tagged_to_self(event)
  1364. and isinstance(content, str) and not self._is_mentioned(content)
  1365. )
  1366. def _maybe_latch_dm(self, channel_id: str, state: dict, event: dict) -> None:
  1367. """Latch a group conversation to "dm" once a direct message is seen; it sticks."""
  1368. if state["chat_type"] == "dm" or not self._is_direct_message_event(channel_id, event):
  1369. return
  1370. state["chat_type"] = "dm"
  1371. self._channel_names.setdefault(channel_id, "DM")
  1372. logger.info("Buzz: conversation %s reclassified as DM (message p-tagged to self)", channel_id)
  1373. def _is_mentioned(self, content: str) -> bool:
  1374. """True when text explicitly addresses this agent (npub, hex, or @name)."""
  1375. lowered = content.lower()
  1376. patterns = []
  1377. if self._self_pubkey and _HEX64_RE.fullmatch(self._self_pubkey):
  1378. patterns.append(rf"(?<![0-9a-f]){re.escape(self._self_pubkey)}(?![0-9a-f])")
  1379. if self._self_npub:
  1380. patterns.append(rf"(?<![a-z0-9]){re.escape(self._self_npub.lower())}(?![a-z0-9])")
  1381. if self._display_name:
  1382. patterns.append(rf"(?<![\w@])@{re.escape(self._display_name.lower())}" + r"(?=$|[\s,;.!?:)\]}])")
  1383. return any(re.search(p, lowered) for p in patterns)
  1384. def _is_addressed(self, event: dict) -> bool:
  1385. """True when a group event carries an explicit text or p-tag address."""
  1386. content = event.get("content")
  1387. return isinstance(content, str) and (self._is_mentioned(content) or self._p_tagged_to_self(event))
  1388. def _strip_mention(self, content: str) -> str:
  1389. """Strip a LEADING @mention of this agent so ``is_command()`` sees "/whoami"; mid-sentence mentions stay."""
  1390. text = content.strip()
  1391. # Display names require '@'; npub/hex identities are unambiguous without it.
  1392. candidates = []
  1393. if self._display_name:
  1394. candidates.append(rf"@{re.escape(self._display_name)}" + r"(?=$|[\s,;.!?:)\]}])")
  1395. if self._self_npub:
  1396. candidates.append(rf"@?{re.escape(self._self_npub)}(?![a-z0-9])")
  1397. if self._self_pubkey:
  1398. candidates.append(rf"@?{re.escape(self._self_pubkey)}(?![0-9a-f])")
  1399. if not candidates:
  1400. return text
  1401. return re.sub(rf"^(?:{'|'.join(candidates)})[\s:,]*", "", text, count=1, flags=re.IGNORECASE).strip()
  1402. async def _resolve_user_name(self, pubkey: str) -> str:
  1403. """Pubkey -> display name, cached (negatively too, so profile-less pubkeys don't re-query); npub prefix fallback."""
  1404. if (cached := self._user_names.get(pubkey)) is not None:
  1405. return cached
  1406. code, out, _err = await self._run_cli(["users", "get", "--pubkey", pubkey])
  1407. profiles = _parse_json_list(out) if code == 0 else []
  1408. name = str(profiles[0].get("display_name") or "").strip() if profiles else ""
  1409. name = self._user_names[pubkey] = name or (hex_to_npub(pubkey) or pubkey)[:16]
  1410. return name
  1411. @staticmethod
  1412. def _trim_seen(state: dict) -> None:
  1413. seen = state["seen"]
  1414. while len(seen) > _SEEN_CAP:
  1415. seen.popitem(last=False)
  1416. meta = state.get("event_meta")
  1417. if isinstance(meta, OrderedDict):
  1418. while len(meta) > _SEEN_CAP:
  1419. meta.popitem(last=False)
  1420. def _mark_seen(self, channel_id: str, event_id: str) -> None:
  1421. state = self._channel_state.get(channel_id)
  1422. if state is not None:
  1423. state["seen"][event_id] = None
  1424. self._trim_seen(state)
  1425. # ── Thread anchoring: NIP-10 replies carry ["e", root, "", "root"] + ["e", parent, "", "reply"]; a thread
  1426. # STARTER carries a lone "reply". The gateway anchors on the trigger id, which inside a thread would nest
  1427. # a sub-thread under every answer — so remember each inbound message's ROOT and reply against that.
  1428. _THREAD_ROOT_CACHE = 512
  1429. @staticmethod
  1430. def _extract_thread_root(event: dict) -> Optional[str]:
  1431. """Return the NIP-10 thread root of ``event``, or None if top-level."""
  1432. root = reply = None
  1433. for target, marker in _e_tags(event):
  1434. marker = marker.lower()
  1435. if marker == "root":
  1436. root = str(target)
  1437. elif marker == "reply":
  1438. reply = str(target)
  1439. elif not marker and reply is None:
  1440. reply = str(target) # unmarked (deprecated positional) e-tag = parent
  1441. # A lone "reply" e-tag started a thread off <reply>; that parent IS the root.
  1442. return root or reply
  1443. def _record_thread_root(self, event_id: str, event: dict) -> None:
  1444. """Cache the thread root for an inbound message id."""
  1445. if not event_id:
  1446. return
  1447. roots = self._thread_roots
  1448. roots[event_id] = self._extract_thread_root(event)
  1449. roots.move_to_end(event_id)
  1450. while len(roots) > self._THREAD_ROOT_CACHE:
  1451. roots.popitem(last=False)
  1452. def _resolve_reply_anchor(self, anchor: Optional[str]) -> Optional[str]:
  1453. """Thread root when the trigger was inside a thread (reply joins it), else the anchor unchanged."""
  1454. return (self._thread_roots.get(str(anchor)) or anchor) if anchor else anchor
  1455. def _remember_event(self, state: dict, event: dict) -> None:
  1456. """Record author + content snippet for later NIP-10 parent lookup."""
  1457. event_id = str(event.get("id") or "")
  1458. content = event.get("content")
  1459. if event_id:
  1460. snippet = content[:_EVENT_META_CONTENT_CAP] if isinstance(content, str) else ""
  1461. self._store_event_meta(state, event_id, str(event.get("pubkey") or "").lower(), snippet)
  1462. def _remember_event_meta(self, channel_id: str, event_id: str, pubkey: str, content: str) -> None:
  1463. state = self._channel_state.get(channel_id)
  1464. if state is not None:
  1465. self._remember_event(state, {"id": event_id, "pubkey": pubkey, "content": content or ""})
  1466. @staticmethod
  1467. def _store_event_meta(state: dict, event_id: str, pubkey: str, snippet: str) -> None:
  1468. cache = state.setdefault("event_meta", OrderedDict())
  1469. if not isinstance(cache, OrderedDict):
  1470. cache = state["event_meta"] = OrderedDict(cache)
  1471. cache[event_id] = (pubkey, snippet)
  1472. cache.move_to_end(event_id)
  1473. while len(cache) > _SEEN_CAP:
  1474. cache.popitem(last=False)
  1475. @staticmethod
  1476. def _lookup_event_meta(state: dict, event_id: Optional[str]) -> Optional[tuple[str, str]]:
  1477. entry = (state.get("event_meta") or {}).get(event_id) if event_id else None
  1478. if not entry or not isinstance(entry, tuple) or len(entry) < 2:
  1479. return None
  1480. return str(entry[0] or ""), str(entry[1] or "")
  1481. async def _localize_inbound_media(
  1482. self, text: str, message_id: str, *, user_id: str = "", chat_type: Optional[str] = None, chat_id: Optional[str] = None,
  1483. ) -> tuple[str, list[str], list[str], MessageType]:
  1484. """Authenticate and cache same-relay media refs in *text* (failures skipped per object). Spends our
  1485. credentials on a sender-chosen URL, so it runs only on the gateway's explicit ``True``."""
  1486. urls, replacements = _find_relay_media_refs(text, self.relay_url)
  1487. if not urls:
  1488. return text, [], [], MessageType.TEXT
  1489. if self._is_sender_authorized(user_id, chat_type, chat_id) is not True:
  1490. logger.warning("Buzz: not localizing %d media reference(s) in message %s — sender %s… is not explicitly authorized",
  1491. len(urls), message_id[:12], (user_id or "?")[:8])
  1492. return text, [], [], MessageType.TEXT
  1493. cleaned_text = _replace_media_refs(text, replacements)
  1494. media_urls: list[str] = []
  1495. media_types: list[str] = []
  1496. media_kinds: list[str] = []
  1497. from gateway.platforms.base import cache_media_bytes_async, validate_inbound_media_size
  1498. for url in urls:
  1499. path_match = _MEDIA_PATH_RE.fullmatch(urlsplit(url).path)
  1500. if path_match is None:
  1501. continue
  1502. label = f"{path_match.group('sha')[:12]}{(path_match.group('ext') or '.bin').lower()}"
  1503. try:
  1504. with tempfile.TemporaryDirectory(prefix="hermes-buzz-media-") as temp_dir:
  1505. download_path = Path(temp_dir) / f"buzz_{label}"
  1506. code, _out, _err = await self._run_cli(["media", "get", "-o", str(download_path), url])
  1507. if code != 0 or not download_path.is_file():
  1508. logger.warning("Buzz: failed to localize inbound media %s (exit %d)", label, code)
  1509. continue
  1510. validate_inbound_media_size(download_path.stat().st_size, media_type="Buzz media")
  1511. mime_type = mimetypes.guess_type(download_path.name)[0] or "application/octet-stream"
  1512. # Up to the inbound media cap (128 MiB) — read off the loop too.
  1513. data = await asyncio.to_thread(download_path.read_bytes)
  1514. cached = await cache_media_bytes_async(data, filename=download_path.name, mime_type=mime_type)
  1515. except Exception as exc:
  1516. logger.warning("Buzz: failed to localize inbound media %s (%s)", label, type(exc).__name__)
  1517. continue
  1518. if cached is None:
  1519. logger.warning("Buzz: rejected invalid inbound media %s", label)
  1520. continue
  1521. media_urls.append(cached.path)
  1522. media_types.append(cached.media_type)
  1523. media_kinds.append(cached.kind)
  1524. if media_urls:
  1525. logger.info("Buzz: localized %d inbound media attachment(s) for message %s", len(media_urls), message_id[:12])
  1526. # Priority order: image > audio > video > any other kind.
  1527. message_type = MessageType.TEXT if not media_kinds else next((mt for k, mt in _MEDIA_KIND_PRIORITY if k in media_kinds), MessageType.DOCUMENT)
  1528. if not cleaned_text:
  1529. cleaned_text = "(attachment)" if media_urls else "(Buzz media attachment unavailable)"
  1530. return cleaned_text, media_urls, media_types, message_type
  1531. async def _dispatch_message(
  1532. self, text: str, chat_id: str, chat_type: str, user_id: str, user_name: str,
  1533. message_id: str, created_at: int, thread_id: Optional[str] = None,
  1534. reply_to_message_id: Optional[str] = None, reply_to_text: Optional[str] = None,
  1535. reply_to_author_id: Optional[str] = None, reply_to_is_own_message: bool = False,
  1536. media_urls: Optional[list[str]] = None, media_types: Optional[list[str]] = None,
  1537. message_type: MessageType = MessageType.TEXT, raw_message: Any = None,
  1538. ) -> None:
  1539. """Build a MessageEvent and hand it to the base class handler."""
  1540. if not self._message_handler:
  1541. return
  1542. media_urls = list(media_urls or [])
  1543. media_types = list(media_types or [])
  1544. # Same-relay URL refs are localized in addition to the caller's imeta attachments (both explicit-True gated).
  1545. localized = await self._localize_inbound_media(text, message_id, user_id=user_id, chat_type=chat_type, chat_id=chat_id)
  1546. text, localized_urls, localized_types, localized_type = localized
  1547. for path, mime in zip(localized_urls, localized_types):
  1548. if path not in media_urls:
  1549. media_urls.append(path)
  1550. media_types.append(mime)
  1551. if message_type == MessageType.TEXT:
  1552. message_type = localized_type
  1553. elif localized_urls and localized_type not in (message_type, MessageType.TEXT):
  1554. # Mixed sources use document semantics so audio isn't routed to STT.
  1555. message_type = MessageType.DOCUMENT
  1556. source = self.build_source(
  1557. chat_id=chat_id, chat_name=self._channel_names.get(chat_id, chat_id), chat_type=chat_type,
  1558. user_id=user_id, user_name=user_name, thread_id=thread_id, message_id=message_id,
  1559. )
  1560. event = MessageEvent(
  1561. text=text, message_type=message_type, source=source, raw_message=raw_message, message_id=message_id,
  1562. media_urls=list(media_urls), media_types=list(media_types), media_text_inlined=[False] * len(media_urls),
  1563. timestamp=datetime.fromtimestamp(created_at) if created_at else datetime.now(),
  1564. reply_to_message_id=reply_to_message_id, reply_to_text=reply_to_text,
  1565. reply_to_author_id=reply_to_author_id, reply_to_is_own_message=reply_to_is_own_message,
  1566. )
  1567. await self.handle_message(event)
  1568. # "Seen" reaction: signals the message was received and is being processed.
  1569. try:
  1570. await self.send_reaction(chat_id, message_id, "👀")
  1571. except Exception:
  1572. logger.debug("Buzz: reaction failed for message %s", message_id[:12], exc_info=True)
  1573. # ── Plugin registration ──────────────────────────────────────────────────────
  1574. def _profile_buzz_extra() -> dict:
  1575. """``buzz.extra`` from the scoped profile's config.yaml for ``check_requirements``; failures yield {} (fail closed)."""
  1576. if not _profile_scoped():
  1577. return {}
  1578. try:
  1579. from gateway.config_loader import platform_section
  1580. from hermes_constants import get_hermes_home
  1581. from hermes_cli.config import read_user_config_raw
  1582. cfg = read_user_config_raw(Path(get_hermes_home()) / "config.yaml")
  1583. except Exception:
  1584. return {}
  1585. if not isinstance(cfg, dict):
  1586. return {}
  1587. # Same seam the runtime loader hands this plugin's YAML hook: a nested-only read missed the
  1588. # documented top-level ``platforms.buzz`` shape and failed configured profiles closed (#125985).
  1589. buzz, _ = platform_section(cfg, "buzz", (cfg.get("gateway") or {}).get("platforms"))
  1590. extra = buzz.get("extra", buzz) if isinstance(buzz, dict) else None
  1591. return extra if isinstance(extra, dict) else {}
  1592. def check_requirements() -> bool:
  1593. """Check if Buzz is configured: a relay URL plus a resolvable key."""
  1594. if _profile_scoped():
  1595. # Scoped profile: os.environ's BUZZ_* may be another profile's and must not satisfy the gate.
  1596. # Consult the profile's own .env (secret scope) and config.yaml (scoped home override) instead;
  1597. # an unconfigured profile fails closed. See #98738.
  1598. extra = _profile_buzz_extra()
  1599. return bool(_configured_relay(extra) and _resolve_private_key(extra))
  1600. # The gate runs before per-profile scopes install; the relay can be externally managed too.
  1601. return bool((_get_scoped_secret("BUZZ_RELAY_URL", "") or "").strip()) and bool(_resolve_private_key())
  1602. def validate_config(config) -> bool:
  1603. """Validate that the platform config has enough information to connect."""
  1604. extra = getattr(config, "extra", {}) or {}
  1605. # Scoped: extra is authoritative; unscoped: env read gains the external-secret rung.
  1606. if _profile_scoped():
  1607. # See #98738.
  1608. relay = _scoped_platform_setting("BUZZ_RELAY_URL", extra, "relay_url")
  1609. relay = relay if relay is not None else extra.get("relay_url", "")
  1610. else:
  1611. relay = _get_scoped_secret("BUZZ_RELAY_URL", "") or extra.get("relay_url", "")
  1612. return bool(relay and _resolve_private_key(extra))
  1613. def is_connected(config) -> bool:
  1614. """Check whether Buzz is configured (env or config.yaml)."""
  1615. return validate_config(config)
  1616. _YAML_BRIDGE = ( # (extra key, env var, kind) for apply_yaml_bridge
  1617. ("relay_url", "BUZZ_RELAY_URL", "str"), ("cli_path", "BUZZ_CLI_PATH", "str"),
  1618. ("home_channel", "BUZZ_HOME_CHANNEL", "str"), ("transport", "BUZZ_TRANSPORT", "str"),
  1619. ("poll_interval", "BUZZ_POLL_INTERVAL", "str"),
  1620. ("channels", "BUZZ_CHANNELS", "csv"), ("allowed_users", "BUZZ_ALLOWED_USERS", "csv"),
  1621. ("reaction_only_users", "BUZZ_REACTION_ONLY_USERS", "csv"), ("allow_all_users", "BUZZ_ALLOW_ALL_USERS", "lower"),
  1622. ("require_mention", "BUZZ_REQUIRE_MENTION", "lower"), ("reply_in_thread", "BUZZ_REPLY_IN_THREAD", "lower"),
  1623. ("reply_to_mode", "BUZZ_REPLY_TO_MODE", "lower"),
  1624. )
  1625. def _apply_yaml_config(yaml_cfg: dict, buzz_cfg: dict) -> Optional[dict]:
  1626. """``apply_yaml_config_fn``: bridge ``buzz.extra`` into ``BUZZ_*`` env (env wins; skipped under a
  1627. secondary profile's scope, #98738) and seed the same keys into the returned ``extra`` so each profile's
  1628. adapter reads its own. ``BUZZ_PRIVATE_KEY`` is never sourced from config.yaml."""
  1629. extra = buzz_cfg.get("extra", buzz_cfg) or {}
  1630. if not isinstance(extra, dict):
  1631. return None
  1632. return _apply_yaml_bridge(extra, _YAML_BRIDGE)
  1633. def _env_enablement() -> Optional[dict]:
  1634. """``env_enablement_fn``: seed ``PlatformConfig.extra`` from the owning profile's env so env-only setups
  1635. show in gateway status; None if unconfigured. Reads go through the profile scope: a served secondary sees
  1636. only its own ``.env`` (#98738 — the process env is the DEFAULT profile's and must not fabricate Buzz here).
  1637. Cron delivery target defaults to the first watched channel."""
  1638. relay = str(_get_scoped_secret("BUZZ_RELAY_URL", "") or "").strip()
  1639. if not relay or not _resolve_private_key():
  1640. return None
  1641. seed = _seed_extra_from_env((
  1642. ("BUZZ_CHANNELS", "channels", lambda v: [c.strip() for c in v.split(",") if c.strip()]),
  1643. ("BUZZ_POLL_INTERVAL", "poll_interval", float), ("BUZZ_CLI_PATH", "cli_path", None),
  1644. ))
  1645. home = _seed_extra_from_env((), home_env="BUZZ_HOME_CHANNEL", home_default=(seed.get("channels") or [""])[0])
  1646. return {"relay_url": relay, **seed, **home}
  1647. async def _standalone_send(
  1648. pconfig, chat_id: str, message: str, *, thread_id: Optional[str] = None,
  1649. media_files: Optional[list[Any]] = None, force_document: bool = False,
  1650. ) -> dict[str, Any]:
  1651. """One-shot send without a live adapter (out-of-process ``deliver=buzz`` cron)."""
  1652. extra = getattr(pconfig, "extra", {}) or {}
  1653. relay = _configured_relay(extra)
  1654. private_key = _resolve_private_key(extra)
  1655. try:
  1656. auth_tag = _resolve_auth_tag(extra)
  1657. except ValueError as exc:
  1658. return send_error(f"Buzz standalone send: {exc}")
  1659. cli_path = _configured_cli_path(extra)
  1660. if not relay or not private_key:
  1661. return send_error("Buzz standalone send: BUZZ_RELAY_URL and BUZZ_PRIVATE_KEY must be configured")
  1662. if not cli_path:
  1663. return send_error("Buzz standalone send: buzz CLI binary not found")
  1664. if not (target := (chat_id or "").strip() or _configured_home_channel(extra)):
  1665. return send_error("Buzz standalone send: no target channel (set BUZZ_HOME_CHANNEL)")
  1666. args = ["messages", "send", "--channel", target, "--content", "-"]
  1667. # Same reply_to_mode / reply_in_thread gate as the live adapter.
  1668. if thread_id and _reply_to_mode(pconfig, extra) != "off":
  1669. args += ["--reply-to", str(thread_id)]
  1670. for media in media_files or []:
  1671. args += ["--file", str(media[0] if isinstance(media, (list, tuple)) and media else media)]
  1672. try:
  1673. code, out, err = await _exec_buzz(cli_path, args, relay_url=relay, private_key=private_key, auth_tag=auth_tag, input_text=message)
  1674. escaped = _escape_unresolved_presentation_mention(message, err) if code != 0 else None
  1675. if escaped is not None:
  1676. logger.info("Buzz: retrying standalone message after unresolved presentation-mention preflight")
  1677. # Retry intentionally omits auth_tag (legacy behavior).
  1678. code, out, err = await _exec_buzz(cli_path, args, relay_url=relay, private_key=private_key, input_text=escaped)
  1679. except asyncio.CancelledError:
  1680. raise
  1681. except OSError as e:
  1682. return send_error(f"Buzz standalone send failed to launch CLI: {_bounded_cli_message(str(e))}")
  1683. if code != 0:
  1684. return send_error(f"Buzz standalone send failed: {_cli_error_message(err, code)}")
  1685. event_id, receipt_error = _parse_send_receipt(out)
  1686. if receipt_error:
  1687. return send_error(f"Buzz standalone send failed: {receipt_error}")
  1688. result = {"success": True, "message_id": event_id}
  1689. if media_files:
  1690. result["media_delivered"] = True
  1691. return result
  1692. def interactive_setup() -> None:
  1693. """Interactive ``hermes gateway setup`` flow (lazy CLI imports keep the plugin importable elsewhere)."""
  1694. from hermes_cli.setup import (
  1695. prompt, prompt_yes_no, save_env_value, get_env_value, print_header, print_info, print_warning, print_success,
  1696. )
  1697. from hermes_cli.setup_platforms import declines_reconfigure
  1698. def ask(label: str, env: str) -> str:
  1699. return prompt(label, default=get_env_value(env) or "")
  1700. print_header("Buzz")
  1701. existing_relay = get_env_value("BUZZ_RELAY_URL")
  1702. if declines_reconfigure("Buzz", "Reconfigure Buzz?", "BUZZ_RELAY_URL"):
  1703. return
  1704. print_info("Connect Hermes to a Buzz community (Block's Nostr-based human+agent platform).")
  1705. print_info(" Requires the buzz CLI binary and a Nostr key that is a community member.")
  1706. print()
  1707. relay = prompt("Relay URL (e.g. https://mycommunity.communities.buzz.xyz)", default=existing_relay or "")
  1708. if not relay:
  1709. print_warning("Relay URL is required — skipping Buzz setup")
  1710. return
  1711. save_env_value("BUZZ_RELAY_URL", relay.strip())
  1712. key = prompt("Nostr private key (nsec or hex; leave blank to keep current)", password=True)
  1713. if key:
  1714. save_env_value("BUZZ_PRIVATE_KEY", key.strip())
  1715. elif not _resolve_private_key():
  1716. print_warning("No private key configured — set BUZZ_PRIVATE_KEY before starting the gateway")
  1717. channels = ask("Channel UUIDs to watch (comma-separated, empty = all joined channels)", "BUZZ_CHANNELS")
  1718. if channels:
  1719. save_env_value("BUZZ_CHANNELS", channels.replace(" ", ""))
  1720. home = ask("Home channel UUID for cron/notification delivery (optional)", "BUZZ_HOME_CHANNEL")
  1721. if home:
  1722. save_env_value("BUZZ_HOME_CHANNEL", home.strip())
  1723. print()
  1724. print_info("🔒 Access control: restrict who can talk to the agent")
  1725. if prompt_yes_no("Allow all community members to talk to the agent?", False):
  1726. save_env_value("BUZZ_ALLOW_ALL_USERS", "true")
  1727. save_env_value("BUZZ_ALLOWED_USERS", "")
  1728. print_warning("⚠️ Open access — anyone in the community can command the agent.")
  1729. else:
  1730. save_env_value("BUZZ_ALLOW_ALL_USERS", "false")
  1731. allowed = ask("Allowed users (comma-separated npubs or hex pubkeys, empty to deny everyone)", "BUZZ_ALLOWED_USERS")
  1732. save_env_value("BUZZ_ALLOWED_USERS", allowed.replace(" ", "") if allowed else "")
  1733. print()
  1734. print_success("Buzz configuration saved to ~/.hermes/.env")
  1735. print_info("Restart the gateway for changes to take effect: hermes gateway restart")
  1736. def register(ctx):
  1737. """Plugin entry point: called by the Hermes plugin system."""
  1738. ctx.register_platform(
  1739. **_load_sibling("send_targets").SEND_ENTRY_KWARGS, # send_message target syntax + routing
  1740. name="buzz", label="Buzz", adapter_factory=lambda cfg: BuzzAdapter(cfg), check_fn=check_requirements,
  1741. validate_config=validate_config, is_connected=is_connected, required_env=["BUZZ_RELAY_URL", "BUZZ_PRIVATE_KEY"],
  1742. install_hint="Requires the buzz CLI binary (https://github.com/block/buzz) on PATH or at BUZZ_CLI_PATH",
  1743. setup_fn=interactive_setup, env_enablement_fn=_env_enablement, apply_yaml_config_fn=_apply_yaml_config,
  1744. cron_deliver_env_var="BUZZ_HOME_CHANNEL", standalone_sender_fn=_standalone_send,
  1745. allowed_users_env="BUZZ_ALLOWED_USERS", allow_all_env="BUZZ_ALLOW_ALL_USERS", emoji="🐝",
  1746. pii_safe=False, # identities are pubkeys, not phone numbers
  1747. allow_update_command=True,
  1748. platform_hint=(
  1749. "You are collaborating in a Buzz workspace (Block's Nostr-based "
  1750. "human+agent platform). Markdown IS supported. Users address you "
  1751. "by @-mentioning your name or npub in channels; direct messages "
  1752. "reach you without a mention. Keep responses conversational."
  1753. ),
  1754. # Nostr: edits in place but channels are shared community spaces.
  1755. display_tier="medium",
  1756. )