adapter.py 92 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758
  1. """Photon Spectrum (iMessage) platform adapter.
  2. Both directions flow through a supervised Node sidecar (``sidecar/index.mjs``) running
  3. the TypeScript-only ``spectrum-ts`` SDK. Inbound: the SDK's gRPC stream re-emitted as
  4. NDJSON over loopback ``GET /inbound`` (no webhook / public URL). Outbound: loopback
  5. POSTs to the sidecar's control endpoints with a shared bearer token.
  6. """
  7. from __future__ import annotations
  8. import asyncio
  9. import base64
  10. import json
  11. import logging
  12. import os
  13. import re
  14. import secrets
  15. import signal
  16. import subprocess
  17. import sys
  18. import time
  19. from datetime import datetime, timezone, UTC
  20. from pathlib import Path
  21. from typing import TYPE_CHECKING, Any, AsyncIterator, Callable, Dict, List, Optional, Tuple
  22. from urllib.parse import urlparse
  23. if TYPE_CHECKING: # type checkers see httpx as always-imported; runtime keeps it optional
  24. import httpx
  25. HTTPX_AVAILABLE = True
  26. else:
  27. try:
  28. import httpx
  29. HTTPX_AVAILABLE = True
  30. except ImportError: # pragma: no cover - httpx is already a Hermes dep
  31. HTTPX_AVAILABLE = False
  32. httpx = None
  33. from gateway.config import Platform, PlatformConfig
  34. from gateway.platforms._shared import coerce_port as _coerce_port
  35. from gateway.platforms._shared import (
  36. extra_or_secret as _extra_or_secret, get_scoped_secret as _get_scoped_secret,
  37. seed_extra_from_env as _seed_extra_from_env, send_error
  38. )
  39. from gateway.platforms.base import BasePlatformAdapter, SendResult
  40. from gateway.platforms.event import MessageEvent, MessageType
  41. from gateway.platforms.helpers import compile_mention_patterns, strip_markdown
  42. from gateway.platforms.helpers import MessageDeduplicator, bounded_put, cancel_task
  43. from gateway.platforms.send_targets import regex_stripped_parser
  44. from utils import atomic_json_write
  45. from .auth import load_project_credentials
  46. # Sidecar dir resolution is lazy (never at import): it probes the filesystem and may
  47. # mirror files. Tests monkeypatch sidecar_paths._SIDECAR_DIR.
  48. from .sidecar_paths import _NPM_ERROR_LOG_MAX_CHARS, _lock_newer_than_install, _npm_error_log, _sidecar_dir
  49. from .sidecar_paths import dir_writable as _dir_writable
  50. from hermes_constants import find_node_executable, with_hermes_node_path
  51. import contextlib
  52. logger = logging.getLogger(__name__)
  53. _DEFAULT_SIDECAR_PORT = 8789
  54. _DEFAULT_SIDECAR_BIND = "127.0.0.1"
  55. _MAX_MESSAGE_LENGTH = 8000 # iMessage caps practical size at ~16 KB; conservative, matches BlueBubbles
  56. # Out-of-process senders (cron, `hermes send`) need the live sidecar's port + spawn-time
  57. # token; persisted once /healthz passes, removed on every stop / failed-start path.
  58. # --------------------------------------------------------------------------- Sidecar runtime record The
  59. # gateway persists this record once the sidecar passes its /healthz readiness check, and removes it on every
  60. # stop / failed-start path so a stale record never outlives a dead sidecar. See #69960. It sits at the top of
  61. # the profile home, where a sandbox can hide it by path (a folder the agent writes, like runtime/, can be
  62. # renamed to expose a hidden file below it).
  63. _RUNTIME_RECORD_NAME = "photon-sidecar.json"
  64. _DEDUP_MAX_SIZE = 4000 # the gRPC stream is at-least-once and a reconnect can replay
  65. _DEDUP_WINDOW_SECONDS = 48 * 3600
  66. _FFFC_WAIT_SECONDS = 15.0 # wait for the real attachment after a U+FFFC placeholder
  67. _NPM_REINSTALL_TIMEOUT = 600 # a wedged self-heal `npm ci` must not stall connect indefinitely
  68. # Photon / Envoy / spectrum-ts substrings meaning transient upstream overload.
  69. _PHOTON_RETRYABLE_PATTERNS = (
  70. "internal sidecar error", "upstream connect error", "upstream unavailable", "connection dropped",
  71. "reset reason: overflow", "upstream_overflow", "upstream_unavailable")
  72. # iMessage emits Open Graph preview art as attachments right after a URL message;
  73. # suppress those so Hermes sees the link once.
  74. _RICHLINK_PREVIEW_SUPPRESS_SECONDS = 30.0
  75. _RICHLINK_PREVIEW_ATTACHMENT_SUFFIX = ".pluginpayloadattachment"
  76. _TYPING_COOLDOWN_SECONDS = 5.0 # per chat; reduces gRPC pressure during overflow
  77. # Group-chat wake words — same defaults as BlueBubbles so both iMessage adapters gate alike.
  78. _DEFAULT_MENTION_PATTERNS = [r"(?<![\w@])@?hermes\s+agent\b[,:\-]?", r"(?<![\w@])@?hermes\b[,:\-]?"]
  79. # Shared/free-tier lines can only reply to conversations the target initiated.
  80. _TARGET_NOT_ALLOWED_MESSAGE = (
  81. "shared/free-tier Photon lines cannot initiate outbound sends to new "
  82. "targets — upgrade to a dedicated line or use another delivery channel")
  83. async def _aiter_ndjson_lines(response: Any) -> AsyncIterator[str]:
  84. """Split the sidecar stream on its protocol delimiter, LF, and nothing else."""
  85. pending = ""
  86. async for chunk in response.aiter_text():
  87. lines = (pending + chunk).split("\n")
  88. pending = lines.pop()
  89. for line in lines:
  90. yield line
  91. if pending:
  92. yield pending
  93. # -- Sidecar runtime record ----------------------------------------------------
  94. def _runtime_record_path() -> Path:
  95. from hermes_constants import get_hermes_home # honors profile overrides
  96. return get_hermes_home() / _RUNTIME_RECORD_NAME
  97. def _legacy_runtime_record_path() -> Path:
  98. """Where earlier releases kept the record: ``<hermes-home>/runtime/``."""
  99. path = _runtime_record_path()
  100. return path.parent / "runtime" / path.name
  101. def _current_runtime_record_path() -> Path:
  102. """The record path. A record at the legacy path is deleted first without being read: the agent
  103. can write that folder."""
  104. with contextlib.suppress(OSError):
  105. _legacy_runtime_record_path().unlink()
  106. return _runtime_record_path()
  107. def _write_runtime_record(port: int, token: str, pid: int) -> None:
  108. """Atomically persist ``{port, token, pid}`` 0600 from creation (best-effort)."""
  109. try:
  110. atomic_json_write(_current_runtime_record_path(), {"port": port, "token": token, "pid": pid}, indent=None, mode=0o600)
  111. except Exception as e:
  112. logger.warning("[photon] failed to write sidecar runtime record: %s", e)
  113. def _read_runtime_record() -> Optional[dict[str, Any]]:
  114. try:
  115. raw = json.loads(_current_runtime_record_path().read_text(encoding="utf-8-sig"))
  116. except (OSError, ValueError):
  117. return None
  118. return raw if isinstance(raw, dict) else None
  119. def _delete_runtime_record() -> None:
  120. for path in (_runtime_record_path(), _legacy_runtime_record_path()):
  121. with contextlib.suppress(OSError):
  122. path.unlink(missing_ok=True)
  123. def _sidecar_pid_alive(pid: Any) -> bool:
  124. """Best-effort liveness check for the recorded sidecar pid."""
  125. try:
  126. pid_int = int(pid)
  127. except (TypeError, ValueError):
  128. return False
  129. if pid_int <= 0:
  130. return False
  131. try:
  132. from gateway.status import _pid_exists # psutil-backed, Windows-safe
  133. return bool(_pid_exists(pid_int))
  134. except Exception:
  135. pass
  136. if os.name != "posix": # os.kill(pid, 0) is destructive on Windows — assume alive; the HTTP send arbitrates
  137. return True
  138. try:
  139. os.kill(pid_int, 0) # windows-footgun: ok — inside os.name == "posix" guard
  140. except PermissionError:
  141. return True
  142. except OSError: # incl. ProcessLookupError
  143. return False
  144. return True
  145. # -- Errors ---------------------------------------------------------------------
  146. class PhotonSidecarStartupError(RuntimeError):
  147. """Startup failure from ``_start_sidecar``; only deterministic failures (deps can't
  148. install, node missing) set ``retryable=False`` so they surface as fatal."""
  149. def __init__(self, message: str, *, code: str = "SIDECAR_FAILED", retryable: bool = True) -> None:
  150. self.code = code
  151. self.retryable = retryable
  152. super().__init__(message)
  153. class PhotonSidecarError(RuntimeError):
  154. """Structured failure returned by the supervised Photon sidecar."""
  155. def __init__(self, *, path: str, status_code: int, error: str, error_class: str = "sidecar_error",
  156. retryable: bool = False) -> None:
  157. self.path = path
  158. self.status_code = status_code
  159. self.error = error
  160. self.error_class = error_class
  161. self.retryable = retryable
  162. super().__init__(
  163. f"Photon sidecar {path} returned {status_code} "
  164. f"({error_class}, retryable={retryable}): {error}")
  165. def _sidecar_error_from_response(path: str, status_code: int, text: str,
  166. data: Optional[dict[str, Any]] = None) -> PhotonSidecarError:
  167. if data is None:
  168. with contextlib.suppress(Exception):
  169. data = json.loads(text)
  170. data = data if isinstance(data, dict) else {}
  171. error = str(data.get("error") or text[:200] or "sidecar error")
  172. error_class = str(data.get("error_class") or "sidecar_error")
  173. retryable = bool(data.get("retryable"))
  174. if error_class == "target_not_allowed":
  175. # Canonical user-facing explanation, never raw upstream error text.
  176. error = _TARGET_NOT_ALLOWED_MESSAGE
  177. retryable = False
  178. return PhotonSidecarError(
  179. path=path, status_code=status_code, error=error, error_class=error_class, retryable=retryable)
  180. # -- Module-level helpers (also used by check_fn / standalone send) ---------------
  181. def sidecar_deps_installed() -> bool:
  182. """True when spectrum-ts is present under node_modules/ (not just node_modules/
  183. itself: npm creates it before aborting on ENOSPC/timeout/EACCES)."""
  184. return (_sidecar_dir() / "node_modules" / "spectrum-ts").exists()
  185. def _is_timeout_error(exc: BaseException) -> bool:
  186. """True when *exc* indicates the request timed out (call hung)."""
  187. if isinstance(exc, (asyncio.TimeoutError, TimeoutError)):
  188. return True
  189. if HTTPX_AVAILABLE and isinstance(exc, httpx.TimeoutException):
  190. return True
  191. return "timeout" in type(exc).__name__.lower()
  192. def check_requirements() -> bool:
  193. """Report readiness or permission to prepare at connect; never provision here."""
  194. from pm import lazy_installs_allowed
  195. can_prepare = lazy_installs_allowed()
  196. if not HTTPX_AVAILABLE:
  197. logger.warning("photon: httpx not installed — pip install httpx")
  198. return False
  199. if not (_get_scoped_secret("PHOTON_NODE_BIN") or find_node_executable("node") or can_prepare):
  200. logger.warning("photon: node binary not found on PATH, in the pm store, or via PHOTON_NODE_BIN")
  201. return False
  202. if not sidecar_deps_installed():
  203. # spectrum-ts not installed yet, or node_modules/ was partially created
  204. # by an aborted npm install (ENOSPC, network timeout, EACCES).
  205. # Checking spectrum-ts presence — not just node_modules/ existence —
  206. # prevents a false positive where an empty/broken node_modules/ dir
  207. # causes check_requirements() to return True while the sidecar crashes
  208. # at runtime with an unrelated-looking missing-module error.
  209. #
  210. # NS-606: if we can self-install at connect time — npm on PATH and
  211. # the (resolved, possibly mirrored) sidecar dir is writable — report
  212. # available so the gateway creates the adapter and ``_start_sidecar``
  213. # cold-installs from the committed lockfile (on hosted images the
  214. # user has no CLI to run `hermes photon setup`, so the connect path
  215. # must self-heal). Otherwise keep returning False so
  216. # `hermes setup` / status surface the missing-deps state.
  217. if (find_node_executable("npm") or can_prepare) and _dir_writable(_sidecar_dir()):
  218. return True
  219. # DEBUG, not WARNING: normal pre-setup state, and check_fn is polled from hot paths.
  220. npm_error = ""
  221. with contextlib.suppress(OSError):
  222. if _npm_error_log().exists():
  223. npm_error = _npm_error_log().read_text(encoding="utf-8-sig").strip()[:_NPM_ERROR_LOG_MAX_CHARS]
  224. if npm_error:
  225. logger.debug(
  226. "photon: spectrum-ts not installed at %s "
  227. "(last npm error: %s) — run: hermes photon setup",
  228. _sidecar_dir(),
  229. npm_error,
  230. )
  231. else:
  232. logger.debug(
  233. "photon: spectrum-ts not installed at %s — run: hermes photon setup",
  234. _sidecar_dir(),
  235. )
  236. return False
  237. return True
  238. def _sidecar_deps_stale() -> bool:
  239. """True when node_modules predates the lockfile (`hermes update` rewrites it without
  240. reinstalling); False if either file is missing."""
  241. return _lock_newer_than_install(_sidecar_dir())
  242. def _reinstall_sidecar_deps() -> None:
  243. """Reinstall the sidecar's node_modules from the lockfile (blocking).
  244. Mirrors ``hermes photon install-sidecar``: ``npm ci`` for an exact,
  245. reproducible install, falling back to ``npm install`` if the lockfile is
  246. missing or drifted. Runs the postinstall patch as part of the install.
  247. Best-effort — a failure here just leaves the (stale) deps in place and the
  248. normal ``_start_sidecar`` readiness check reports the real error.
  249. """
  250. import pm
  251. try:
  252. npm = find_node_executable("npm")
  253. env = with_hermes_node_path()
  254. if npm is None:
  255. env = pm.ensure("npm").env
  256. installed = pm.installed_package("npm")
  257. if installed is None or installed.binary is None:
  258. raise pm.InstallError("npm", "ensured but no selected binary was recorded")
  259. npm = str(installed.binary)
  260. except pm.InstallError as exc:
  261. logger.warning("[photon] cannot prepare sidecar dependencies: %s", exc)
  262. return
  263. from hermes_cli._subprocess_compat import windows_hide_flags # no console flash on Windows
  264. def _run(verb: str) -> subprocess.CompletedProcess:
  265. return subprocess.run(
  266. [npm, verb], stdin=subprocess.DEVNULL, cwd=str(_sidecar_dir()), capture_output=True, text=True, encoding="utf-8",
  267. errors="replace", check=False, env=env, timeout=_NPM_REINSTALL_TIMEOUT, creationflags=windows_hide_flags())
  268. try:
  269. result = _run("ci")
  270. if result.returncode != 0:
  271. logger.warning("[photon] sidecar `npm ci` failed; falling back to `npm install`")
  272. result = _run("install")
  273. except subprocess.TimeoutExpired: # retried on the next reconnect tick
  274. logger.error("[photon] sidecar dependency reinstall timed out after %ss", _NPM_REINSTALL_TIMEOUT)
  275. return
  276. if result.returncode == 0:
  277. logger.info("[photon] sidecar dependencies reinstalled from lockfile")
  278. else:
  279. logger.error("[photon] sidecar dependency reinstall failed: %s", (result.stderr or result.stdout or "").strip())
  280. def validate_config(cfg: PlatformConfig) -> bool:
  281. extra = cfg.extra or {}
  282. if (extra.get("project_id") or _get_scoped_secret("PHOTON_PROJECT_ID")) and (
  283. extra.get("project_secret") or _get_scoped_secret("PHOTON_PROJECT_SECRET")):
  284. return True
  285. stored_id, stored_sec = load_project_credentials() # auth.json fallback
  286. return bool(stored_id and stored_sec)
  287. def is_connected(cfg: PlatformConfig) -> bool:
  288. return validate_config(cfg)
  289. def _env_enablement() -> Optional[dict]:
  290. """``env_enablement_fn``: seed ``PlatformConfig.extra`` so env-only setups appear in status."""
  291. project_id, project_secret = load_project_credentials()
  292. if not (project_id and project_secret):
  293. return None
  294. return {"project_id": project_id, "project_secret": project_secret,
  295. **_seed_extra_from_env((), home_env="PHOTON_HOME_CHANNEL")}
  296. def _markdown_enabled() -> bool:
  297. """Replies go out as markdown; ``PHOTON_MARKDOWN=false`` is the kill-switch to plain text."""
  298. return _get_scoped_secret("PHOTON_MARKDOWN", "true").strip().lower() not in {"false", "0", "no"}
  299. # Mirrors URL_RE in plugins/platforms/photon/sidecar/send-format.mjs. Keep the
  300. # two in sync: the sidecar owns the builder choice, this owns the payload that
  301. # choice implies.
  302. _SIDECAR_URL_RE = re.compile(r"https?://[^\s)'\"<>]+", re.IGNORECASE)
  303. def _sidecar_payload_text(text: str, send_markdown: bool) -> str:
  304. """The ``/send`` text: verbatim only when the sidecar will really use spectrum-ts' markdown builder.
  305. ``chooseSendFormat`` routes markdown containing a raw URL through the verbatim ``text()`` builder
  306. (the markdown builder's data detection 500s on those), and a plain send has no renderer at all, so
  307. both are stripped here or iMessage shows literal ``**``/fences. Link targets survive as bare URLs:
  308. iMessage auto-links those and nothing else.
  309. """
  310. if send_markdown and not _SIDECAR_URL_RE.search(text or ""):
  311. return text
  312. return strip_markdown(text, keep_link_targets=True)
  313. def _url_only_candidate(text: str) -> Optional[str]:
  314. candidate = (text or "").strip()
  315. if not re.fullmatch(r"https?://\S+", candidate, flags=re.IGNORECASE):
  316. return None
  317. try:
  318. parsed = urlparse(candidate)
  319. except ValueError:
  320. return None
  321. return candidate if parsed.scheme.lower() in {"http", "https"} and parsed.netloc else None
  322. def _richlink_candidate(text: str) -> Optional[str]:
  323. """URL to send via ``richlink()`` — only exact http(s) URL messages; prose with
  324. URLs and Markdown links stay on the text path so labels aren't dropped."""
  325. return _url_only_candidate(text) if _markdown_enabled() else None
  326. def _format_richlink_content(content: dict[str, Any]) -> str:
  327. url, title, summary = (str(content.get(k) or "").strip() for k in ("url", "title", "summary"))
  328. parts = [p for p in (title, summary if summary != title else "", url) if p]
  329. return "\n".join(parts) if parts else "[Photon rich link received with no URL]"
  330. def _group_item_contents(content: dict[str, Any]) -> list[dict[str, Any]]:
  331. """The dict ``content`` of every well-formed item in a ``group`` payload."""
  332. items = (item.get("content") if isinstance(item, dict) else None for item in content.get("items") or [])
  333. return [c for c in items if isinstance(c, dict)]
  334. def _richlink_url_from_content(content: dict[str, Any]) -> Optional[str]:
  335. ctype = content.get("type")
  336. if ctype in ("text", "richlink"):
  337. return _url_only_candidate(content.get("text" if ctype == "text" else "url") or "")
  338. if ctype == "group":
  339. return next((u for u in map(_richlink_url_from_content, _group_item_contents(content)) if u), None)
  340. return None
  341. def _is_richlink_preview_attachment(payload: dict[str, Any]) -> bool:
  342. # Preview art can carry an opaque MIME; the name/id marker is the reliable signal,
  343. # the recent-link window guards real files.
  344. return payload.get("type") == "attachment" and any(
  345. _RICHLINK_PREVIEW_ATTACHMENT_SUFFIX in str(payload.get(k) or "").lower() for k in ("name", "id"))
  346. def _richlink_preview_label(content: dict[str, Any]) -> str:
  347. def _label(c: dict[str, Any]) -> str:
  348. return str(c.get("name") or c.get("id") or "(unnamed)")
  349. if content.get("type") == "attachment":
  350. return _label(content)
  351. if content.get("type") == "group":
  352. return ", ".join(_label(c) for c in _group_item_contents(content)) or "(group)"
  353. return "(unknown)"
  354. def _is_richlink_preview_content(content: dict[str, Any]) -> bool:
  355. """A preview attachment, or a non-empty group made ONLY of preview attachments."""
  356. if _is_richlink_preview_attachment(content):
  357. return True
  358. if content.get("type") != "group":
  359. return False
  360. items = content.get("items") or []
  361. contents = _group_item_contents(content)
  362. return bool(items) and len(contents) == len(items) and all(
  363. _is_richlink_preview_attachment(c) for c in contents)
  364. def _parse_timestamp(ts_str: str) -> datetime:
  365. try:
  366. return datetime.fromisoformat(ts_str) if ts_str else datetime.now(tz=UTC)
  367. except ValueError:
  368. return datetime.now(tz=UTC)
  369. _Normalized = tuple[str, MessageType, list[str], list[str]] # text, type, media_urls, media_types
  370. def _normalize_binary_payload(payload: dict[str, Any]) -> _Normalized:
  371. """Cache an inline attachment/voice payload; fall back to a text marker."""
  372. is_voice = payload.get("type") == "voice"
  373. name = payload.get("name") or ("voice" if is_voice else "(unnamed)")
  374. mime = payload.get("mimeType") or ""
  375. # iMessage voice notes are CAF and may arrive "(unnamed)", so MIME is a signal too.
  376. is_voice = is_voice or name.lower().endswith(".caf") or mime == "audio/x-caf"
  377. mtype = MessageType.VOICE if is_voice else _attachment_message_type(mime)
  378. label = "voice" if is_voice else "attachment"
  379. cached = _cache_inbound_attachment(payload, name, mime, force_audio=is_voice)
  380. if cached:
  381. return f"({label})", mtype, [cached], [mime or ("audio/mp4" if is_voice else "application/octet-stream")]
  382. duration = payload.get("duration")
  383. duration_text = f", duration: {duration}s" if isinstance(duration, (int, float)) else ""
  384. return f"[Photon {label} received: {name} ({mime or 'unknown MIME'}{duration_text})]", mtype, [], []
  385. def _normalize_group_content(content: dict[str, Any]) -> _Normalized:
  386. text_parts: list[str] = []
  387. mtype = MessageType.TEXT
  388. media_urls: list[str] = []
  389. media_types: list[str] = []
  390. for item_content in _group_item_contents(content):
  391. item_type = item_content.get("type")
  392. if item_type in {"attachment", "voice"}:
  393. marker, item_mtype, item_urls, item_types = _normalize_binary_payload(item_content)
  394. if mtype == MessageType.TEXT:
  395. mtype = item_mtype
  396. media_urls.extend(item_urls)
  397. media_types.extend(item_types)
  398. if not item_urls:
  399. text_parts.append(marker)
  400. elif item_type == "text":
  401. text_parts.append(item_content.get("text") or "")
  402. elif item_type == "richlink":
  403. text_parts.append(_format_richlink_content(item_content))
  404. elif item_type:
  405. text_parts.append(f"[Photon content type not handled: {item_type}]")
  406. if media_urls and mtype == MessageType.TEXT:
  407. mtype = MessageType.DOCUMENT
  408. text = "\n".join(part for part in text_parts if part).strip()
  409. return text or ("(attachment)" if media_urls else "[Photon empty group received]"), mtype, media_urls, media_types
  410. _CONTENT_NORMALIZERS: dict[Any, Callable[[dict[str, Any]], _Normalized]] = {
  411. "text": lambda c: (c.get("text") or "", MessageType.TEXT, [], []),
  412. "attachment": _normalize_binary_payload, "voice": _normalize_binary_payload,
  413. "richlink": lambda c: (_format_richlink_content(c), MessageType.TEXT, [], []),
  414. "group": _normalize_group_content,
  415. }
  416. _BINARY_CONTENT_TYPES = {"attachment", "voice", "group"} # may decode/cache media bytes → run off the event loop
  417. def _mention_gate_text(content: dict[str, Any]) -> str:
  418. """The user-typed text of a payload WITHOUT decoding or caching any attachment bytes,
  419. so the group require_mention gate can run before ``_normalize_content`` persists media."""
  420. ctype = content.get("type")
  421. if ctype == "text":
  422. return content.get("text") or ""
  423. if ctype == "richlink":
  424. return _format_richlink_content(content)
  425. if ctype == "group":
  426. return "\n".join(part for part in map(_mention_gate_text, _group_item_contents(content)) if part)
  427. return ""
  428. def _normalize_content(content: dict[str, Any]) -> _Normalized:
  429. """Turn a sidecar ``content`` payload into (text, type, media_urls, media_types)."""
  430. ctype = content.get("type")
  431. normalize = _CONTENT_NORMALIZERS.get(ctype) if isinstance(ctype, str) else None
  432. if normalize is None:
  433. return f"[Photon content type not handled: {ctype}]", MessageType.TEXT, [], []
  434. return normalize(content)
  435. def _sent_text_key(chat_id: Optional[str]) -> Optional[str]:
  436. """DM GUID (``any;-;+1555...``) and bare E.164 address one space; index under the phone."""
  437. return PhotonAdapter._normalize_chat_key(chat_id) if chat_id else None
  438. def _attachment_label(kind: str, name: str) -> str:
  439. return f"[{kind}: {name}]"
  440. async def _record_sent_text_async(chat_id: Optional[str], message_id: Optional[str], text: Optional[str]) -> None:
  441. """Remember what we sent so a later threaded reply to it carries the quoted text. Never raises."""
  442. try:
  443. from gateway import rich_sent_store
  444. await rich_sent_store.record_async(_sent_text_key(chat_id), message_id, text)
  445. except Exception:
  446. logger.debug("[photon] sent-text index record failed", exc_info=True)
  447. def _lookup_sent_text(chat_id: Optional[str], message_id: Optional[str]) -> Optional[str]:
  448. try:
  449. from gateway import rich_sent_store
  450. return rich_sent_store.lookup(_sent_text_key(chat_id), message_id)
  451. except Exception:
  452. logger.debug("[photon] sent-text index lookup failed", exc_info=True)
  453. return None
  454. def _attachment_body(space_id: str, safe_path: str, *, kind: str, name: Optional[str] = None,
  455. mime_type: Optional[str] = None, caption: Optional[str] = None) -> dict[str, Any]:
  456. """``/send-attachment`` body; spectrum-ts infers name/mimeType from the extension,
  457. so optional keys are only sent when Hermes supplied them."""
  458. body: dict[str, Any] = {
  459. "spaceId": space_id, "path": safe_path, "kind": "voice" if kind == "voice" else "attachment"}
  460. body.update({k: v for k, v in (("name", name), ("mimeType", mime_type), ("caption", caption)) if v})
  461. return body
  462. def _guess_mime(path: str) -> Optional[str]:
  463. import mimetypes
  464. return mimetypes.guess_type(path)[0] or None
  465. # -- Adapter -------------------------------------------------------------------
  466. class PhotonAdapter(BasePlatformAdapter):
  467. """Bidirectional bridge to Photon Spectrum via the Node spectrum-ts sidecar."""
  468. MAX_MESSAGE_LENGTH = _MAX_MESSAGE_LENGTH
  469. SUPPORTS_MESSAGE_EDITING = False # no edit API: streaming must not leave a stale cursor (▉)
  470. serial_receive_loop = True # the /inbound NDJSON loop awaits each line before reading the next
  471. def __init__(self, config: PlatformConfig):
  472. super().__init__(config, Platform("photon"))
  473. extra = config.extra or {}
  474. # Project credentials: env wins, then config.extra, then auth.json.
  475. stored_id, stored_sec = load_project_credentials()
  476. self._project_id: str = _get_scoped_secret("PHOTON_PROJECT_ID") or extra.get("project_id") or stored_id or ""
  477. self._project_secret: str = (
  478. _get_scoped_secret("PHOTON_PROJECT_SECRET") or extra.get("project_secret") or stored_sec or "")
  479. self._sidecar_port = _coerce_port(
  480. extra.get("sidecar_port") or _get_scoped_secret("PHOTON_SIDECAR_PORT"), _DEFAULT_SIDECAR_PORT)
  481. self._sidecar_bind = _DEFAULT_SIDECAR_BIND
  482. self._sidecar_token = _get_scoped_secret("PHOTON_SIDECAR_TOKEN") or secrets.token_hex(16)
  483. autostart = str(_get_scoped_secret("PHOTON_SIDECAR_AUTOSTART", "true")).lower()
  484. self._autostart_sidecar = autostart not in ("0", "false", "no")
  485. self._node_bin = _get_scoped_secret("PHOTON_NODE_BIN") or find_node_executable("node")
  486. # Presence watchdog (second layer behind the sidecar's own zombie-stream detection):
  487. # respawns only when the sidecar's HTTP loop hangs; 10-min interval because shared
  488. # lines are quiet for hours. Config key wins, then env; None-aware so 0 disables it.
  489. def _setting(key: str, env: str, default: Any, cast: Callable[[Any], Any]) -> Any:
  490. try:
  491. return cast(_extra_or_secret(extra, key, env, None))
  492. except (TypeError, ValueError):
  493. return default
  494. self._probe_interval = _setting("probe_interval_seconds", "PHOTON_PROBE_INTERVAL_SECONDS", 600.0, float)
  495. self._probe_timeout = _setting("probe_timeout_seconds", "PHOTON_PROBE_TIMEOUT_SECONDS", 10.0, float)
  496. self._probe_max_failures = _setting("probe_max_failures", "PHOTON_PROBE_MAX_FAILURES", 3, int)
  497. self._probe_enabled = self._probe_interval > 0
  498. # Never advertise fences: a URL-bearing message goes out as raw text (literal ```), and the
  499. # markdown path renders a fence as inline Unicode monospace, not a block.
  500. self.supports_code_blocks = False
  501. self._sidecar_proc: Optional[subprocess.Popen] = None
  502. self._http_client: Optional[httpx.AsyncClient] = None
  503. self._respawn_lock: Optional[asyncio.Lock] = None
  504. self._sidecar_supervisor_task = self._inbound_task = self._sidecar_health_task = None
  505. self._watchdog_task: Optional[asyncio.Task] = None
  506. self._inbound_running = self._watchdog_running = False
  507. self._sidecar_health_interval = 15.0
  508. self._probe_failures = 0
  509. self._last_upstream_activity = 0.0 # monotonic; watchdog skips probe if traffic proved liveness
  510. self._dedup = MessageDeduplicator(max_size=_DEDUP_MAX_SIZE, ttl_seconds=_DEDUP_WINDOW_SECONDS) # at-least-once stream
  511. self._sent_message_ids: dict[str, float] = {} # only reactions targeting OUR sends are routed
  512. self._last_inbound_by_chat: dict[str, str] = {} # default target for the react action
  513. self._recent_richlinks_by_chat: dict[str, float] = {} # coalesce preview-art attachments
  514. self._typing_last_sent: dict[str, float] = {}
  515. self._pending_fffc: dict[str, tuple[float, Any]] = {} # chat_key → (timestamp, asyncio.Task)
  516. # Group-chat mention gating (parity with BlueBubbles); DMs are never gated.
  517. require_mention = extra.get("require_mention")
  518. if require_mention is None:
  519. require_mention = _get_scoped_secret("PHOTON_REQUIRE_MENTION")
  520. self.require_mention = str(require_mention).strip().lower() in {"true", "1", "yes", "on"}
  521. self._mention_patterns = self._compile_mention_patterns(
  522. extra["mention_patterns"] if "mention_patterns" in extra
  523. else _get_scoped_secret("PHOTON_MENTION_PATTERNS"))
  524. # -- Group-mention gating (parity with BlueBubbles) ----------------------------
  525. @staticmethod
  526. def _compile_mention_patterns(raw: Any) -> list[re.Pattern]:
  527. """``raw``: list, string (JSON list or comma/newline-separated) or None (defaults)."""
  528. return compile_mention_patterns(
  529. raw, log_prefix="photon", defaults=_DEFAULT_MENTION_PATTERNS, logger_=logger)
  530. def _message_matches_mention_patterns(self, text: str) -> bool:
  531. return bool(text) and any(pattern.search(text) for pattern in self._mention_patterns)
  532. def _clean_mention_text(self, text: str) -> str:
  533. """Strip a leading wake word only (patterns are regexes; never touch later words)."""
  534. stripped = text.lstrip() if text else ""
  535. for match in filter(None, (pattern.match(stripped) for pattern in self._mention_patterns)):
  536. return stripped[match.end():].lstrip(" ,:-") or text
  537. return text
  538. # -- Sidecar HTTP plumbing ------------------------------------------------------
  539. def _sidecar_url(self, path: str) -> str:
  540. return f"http://{self._sidecar_bind}:{self._sidecar_port}{path}"
  541. def _sidecar_headers(self) -> dict[str, str]:
  542. return {"X-Hermes-Sidecar-Token": self._sidecar_token}
  543. # -- Connection lifecycle ------------------------------------------------------
  544. async def connect(self, *, is_reconnect: bool = False) -> bool:
  545. if not HTTPX_AVAILABLE:
  546. self._set_fatal_error("MISSING_DEP", "httpx not installed", retryable=False)
  547. return False
  548. if not self._project_id or not self._project_secret:
  549. self._set_fatal_error(
  550. "MISSING_CREDENTIALS",
  551. "PHOTON_PROJECT_ID and PHOTON_PROJECT_SECRET are required. Run: hermes photon setup",
  552. retryable=False)
  553. return False
  554. client = httpx.AsyncClient(timeout=30.0, trust_env=False)
  555. self._http_client = client
  556. if self._autostart_sidecar: # the sidecar holds the gRPC stream for BOTH directions: required now
  557. try:
  558. await self._start_sidecar()
  559. except Exception as e:
  560. # Typed deterministic failures may be retryable=False (fatal); everything else
  561. # stays retryable, with the gateway's NEEDS_ATTENTION escalation as the backstop.
  562. if isinstance(e, PhotonSidecarStartupError):
  563. self._set_fatal_error(e.code, str(e), retryable=e.retryable)
  564. else:
  565. self._set_fatal_error("SIDECAR_FAILED", f"failed to start Photon sidecar: {e}", retryable=True)
  566. _delete_runtime_record() # no live sidecar — don't mislead standalone senders
  567. await client.aclose()
  568. self._http_client = None
  569. return False
  570. else:
  571. logger.warning("[photon] sidecar autostart disabled — inbound + outbound will fail")
  572. loop = asyncio.get_event_loop()
  573. self._inbound_running = True
  574. self._inbound_task = loop.create_task(self._inbound_loop())
  575. self._sidecar_health_task = loop.create_task(self._monitor_sidecar_health())
  576. self._last_upstream_activity = time.monotonic()
  577. if self._probe_enabled and self._autostart_sidecar:
  578. self._respawn_lock = asyncio.Lock()
  579. self._watchdog_running = True
  580. self._watchdog_task = loop.create_task(self._presence_watchdog())
  581. self._mark_connected()
  582. logger.info("[photon] connected — sidecar on %s:%d, streaming inbound over gRPC",
  583. self._sidecar_bind, self._sidecar_port)
  584. self._wire_plugin_handlers(None) # ctx.register_platform_handler natives
  585. return True
  586. async def disconnect(self) -> None:
  587. self._inbound_running = False
  588. await self._stop_watchdog() # first, so it can't respawn while we tear the sidecar down
  589. task, self._sidecar_health_task = self._sidecar_health_task, None
  590. await cancel_task(task)
  591. task, self._inbound_task = self._inbound_task, None
  592. await cancel_task(task)
  593. for _, fffc_task in list(self._pending_fffc.values()):
  594. if fffc_task and not fffc_task.done():
  595. fffc_task.cancel()
  596. self._pending_fffc.clear()
  597. await self._stop_sidecar()
  598. if self._http_client is not None:
  599. with contextlib.suppress(Exception):
  600. await self._http_client.aclose()
  601. self._http_client = None
  602. self._mark_disconnected()
  603. def _dispatch_fatal_notification(self) -> None:
  604. """Notify the gateway of a fatal error from a detached task. The health/supervisor
  605. tasks must NOT await ``_notify_fatal_error()`` inline: the gateway answers with
  606. ``disconnect()``, which cancels those very tasks (via its own wrapper task, so the
  607. ``current_task()`` guard can't help) — the CancelledError would kill the notifier
  608. mid-handoff: no log, no reconnect. A fresh task can be cancelled freely."""
  609. asyncio.create_task(self._notify_fatal_error_logged())
  610. async def _notify_fatal_error_logged(self) -> None:
  611. try:
  612. await self._notify_fatal_error()
  613. except Exception as exc: # pragma: no cover - defensive
  614. logger.warning("[photon] fatal-error notification failed: %s", exc)
  615. # -- Inbound stream consumer ---------------------------------------------------
  616. async def _inbound_loop(self) -> None:
  617. """Consume the sidecar's ``/inbound`` NDJSON stream, re-opening it if it drops
  618. (the sidecar owns the gRPC reconnect to Photon)."""
  619. client = self._http_client
  620. if client is None:
  621. return
  622. url = self._sidecar_url("/inbound")
  623. headers = self._sidecar_headers()
  624. backoff = 1.0
  625. while self._inbound_running:
  626. try:
  627. async with client.stream("GET", url, headers=headers, timeout=None) as resp:
  628. if resp.status_code != 200:
  629. raise RuntimeError(f"/inbound returned {resp.status_code}")
  630. backoff = 1.0
  631. async for line in _aiter_ndjson_lines(resp):
  632. if not self._inbound_running:
  633. break
  634. line = line.strip()
  635. if not line:
  636. continue # heartbeat
  637. await self._on_inbound_line(line)
  638. except asyncio.CancelledError:
  639. raise
  640. except Exception as e:
  641. if not self._inbound_running:
  642. break
  643. logger.warning("[photon] inbound stream dropped (%s); reconnecting in %.1fs", e, backoff)
  644. await asyncio.sleep(backoff)
  645. backoff = min(backoff * 2, 30.0)
  646. async def _monitor_sidecar_health(self) -> None:
  647. """Promote a degraded upstream stream (per ``/healthz``) into a reconnect, so a
  648. live sidecar HTTP process with a dead gRPC stream isn't a silent outage."""
  649. while self._inbound_running:
  650. await asyncio.sleep(self._sidecar_health_interval)
  651. if not self._inbound_running:
  652. break
  653. try:
  654. data = await self._sidecar_call("/healthz", {})
  655. except asyncio.CancelledError:
  656. raise
  657. except Exception as exc:
  658. logger.debug("[photon] sidecar health check failed: %s", exc)
  659. continue
  660. stream = data.get("stream") if isinstance(data, dict) else None
  661. if not isinstance(stream, dict):
  662. continue
  663. # Loud line for a suspected zombie stream before the sidecar's degraded->exit-75 fires.
  664. staleness = stream.get("staleness")
  665. if isinstance(staleness, dict) and staleness.get("zombieSuspected") is True:
  666. logger.warning("[photon] sidecar reports suspected zombie stream"
  667. " (silentForMs=%s, lastProbeOutcome=%s)",
  668. staleness.get("silentForMs"), staleness.get("lastProbeOutcome"))
  669. if stream.get("ok") is not False:
  670. continue
  671. message = (
  672. f"Photon upstream stream degraded (state={stream.get('state') or 'unknown'}, "
  673. f"degradedForMs={stream.get('degradedForMs')}): {stream.get('lastIssue') or 'unknown stream issue'}")
  674. logger.error("[photon] %s", message)
  675. self._set_fatal_error("UPSTREAM_STREAM_DEGRADED", message, retryable=True)
  676. self._dispatch_fatal_notification()
  677. break
  678. async def _on_inbound_line(self, line: str) -> None:
  679. self._note_upstream_activity() # any inbound line proves the upstream gRPC channel is live
  680. try:
  681. event = json.loads(line)
  682. except json.JSONDecodeError:
  683. logger.debug("[photon] skipping non-JSON inbound line")
  684. return
  685. msg_id = event.get("messageId")
  686. if msg_id and self._dedup.is_duplicate(msg_id):
  687. return
  688. try:
  689. await self._dispatch_inbound(event)
  690. except Exception:
  691. logger.exception("[photon] inbound dispatch failed")
  692. async def _fffc_timeout_handler(self, chat_key: str, message_id: str) -> None:
  693. await asyncio.sleep(_FFFC_WAIT_SECONDS)
  694. if self._pending_fffc.pop(chat_key, None):
  695. logger.warning("[photon] wait for attachment was too long, can't retrieve attachment data "
  696. "(message %s, chat %s)", message_id, chat_key)
  697. def _cancel_pending_fffc(self, chat_key: str) -> bool:
  698. """Pop and cancel a pending U+FFFC timeout; True when a live task was cancelled."""
  699. prev = self._pending_fffc.pop(chat_key, None)
  700. live = bool(prev and prev[1] and not prev[1].done())
  701. if live:
  702. prev[1].cancel()
  703. return live
  704. async def _dispatch_inbound(self, event: dict[str, Any]) -> None:
  705. """Normalize a sidecar inbound event ``{messageId, space: {id, type: dm|group, phone},
  706. sender: {id}, content: {type: text|attachment|voice|reaction|richlink|group|
  707. poll_option|read, ...}, timestamp}`` and dispatch it. Attachment/voice bytes arrive
  708. inline as base64 ``data`` under the sidecar's cap; otherwise metadata only → marker."""
  709. space = event.get("space") or {}
  710. sender = event.get("sender") or {}
  711. content = event.get("content") or {}
  712. space_id = space.get("id") or ""
  713. if not space_id:
  714. logger.warning("[photon] inbound missing space.id")
  715. return
  716. chat_type = "group" if space.get("type") == "group" else "dm"
  717. sender_id = sender.get("id") or space.get("phone") or space_id
  718. timestamp = _parse_timestamp(event.get("timestamp") or "")
  719. message_id = event.get("messageId")
  720. # iMessage threaded reply (spectrum 12.x): unwrap to the inner content so the user's
  721. # words go through the normal ladder, and keep the quoted target as reply context
  722. # (#100663). Malformed envelopes fall through to the unknown-type marker.
  723. reply_ctx: dict[str, Any] = {}
  724. if content.get("type") == "reply" and isinstance(content.get("content"), dict) \
  725. and content["content"].get("type") not in (None, "unknown"):
  726. target_id = content.get("targetMessageId")
  727. target_text = content.get("targetText") or None
  728. # spectrum often can't hydrate the target's text (e.g. our own sends, older
  729. # bubbles): fall back to the local index of what we sent.
  730. stored_text = _lookup_sent_text(space_id, target_id) if target_id and not target_text else None
  731. # Cloud targets carry no direction and _sent_message_ids is in-memory, so after a
  732. # restart an index hit is the only proof the target was ours (only our sends are indexed).
  733. is_own = content.get("targetDirection") == "outbound" or bool(
  734. target_id and target_id in self._sent_message_ids) or stored_text is not None
  735. reply_ctx = {"reply_to_message_id": target_id, "reply_to_text": target_text or stored_text,
  736. "reply_to_is_own_message": is_own}
  737. content = content["content"]
  738. ctype = content.get("type")
  739. def _event(text: str, mtype: MessageType = MessageType.TEXT, **kwargs: Any) -> MessageEvent:
  740. source = self.build_source(chat_id=space_id, chat_name=space_id, chat_type=chat_type,
  741. user_id=sender_id, user_name=sender_id or None, message_id=message_id)
  742. for key, value in reply_ctx.items():
  743. kwargs.setdefault(key, value)
  744. return MessageEvent(text=text, message_type=mtype, source=source, message_id=message_id,
  745. raw_message=event, timestamp=timestamp, **kwargs)
  746. if ctype in {"read", "read_receipt"}: # presence signal, not a user turn (receipts for our sends)
  747. logger.debug("[photon] outbound message read: %s", content.get("targetMessageId") or "unknown")
  748. return
  749. if ctype == "reaction":
  750. # Only tapbacks on messages WE sent are addressed to the bot. Checked before the
  751. # mention gate: a tapback never carries a wake word.
  752. target_id = content.get("targetMessageId")
  753. is_ours = content.get("targetDirection") == "outbound" or (
  754. target_id and target_id in self._sent_message_ids)
  755. if not is_ours:
  756. logger.debug("[photon] ignoring reaction on a message we didn't send")
  757. return
  758. # reply_to_is_own_message holds by construction, so the gateway injects
  759. # `[Replying to your previous message: "..."]` when targetText is present.
  760. await self.handle_message(_event(
  761. f"reaction:added:{content.get('emoji') or ''}", reply_to_message_id=target_id,
  762. reply_to_text=content.get("targetText") or None, reply_to_is_own_message=True))
  763. return
  764. # U+FFFC placeholder: wait for the real attachment. Detected before _record_last_inbound
  765. # so the placeholder isn't the reaction target.
  766. if ctype == "text" and (content.get("text") or "").strip() == "\ufffc":
  767. self._cancel_pending_fffc(space_id)
  768. task = asyncio.create_task(self._fffc_timeout_handler(space_id, message_id or ""))
  769. self._pending_fffc[space_id] = (time.monotonic(), task)
  770. logger.debug("[photon] U+FFFC placeholder received — waiting for attachment")
  771. return
  772. if ctype in {"attachment", "voice"} and self._cancel_pending_fffc(space_id):
  773. logger.debug("[photon] attachment arrived — cancelling U+FFFC timeout")
  774. # Preview art for a just-received URL must not become a second user prompt;
  775. # suppress before recording it as reactable or decoding image bytes.
  776. if self._is_recent_richlink_preview(space_id, content):
  777. logger.info("[photon] suppressing rich-link preview attachment: %s", _richlink_preview_label(content))
  778. return
  779. # Everything past here is a real (reactable) message. Recorded before the mention
  780. # gate: reacting to a non-wake-word group message is valid.
  781. self._record_last_inbound(space_id, message_id)
  782. if ctype == "poll_option":
  783. # Native poll vote: a selection is forwarded as if typed (the gateway's
  784. # pending-clarify intercept resolves it); a deselection is dropped.
  785. if content.get("selected") is False:
  786. logger.debug("[photon] ignoring poll deselection")
  787. return
  788. choice = (content.get("title") or "").strip()
  789. if not choice:
  790. logger.debug("[photon] ignoring poll vote with empty title")
  791. return
  792. await self.handle_message(_event(choice))
  793. return
  794. # Mention gate BEFORE normalising: _normalize_content persists inline attachment
  795. # bytes to the media cache, and a dropped group message must not leave files behind.
  796. gated = chat_type == "group" and self.require_mention
  797. if gated and not self._message_matches_mention_patterns(_mention_gate_text(content)):
  798. logger.debug("[photon] ignoring group message (require_mention=true, no mention pattern matched)")
  799. return
  800. if ctype in _BINARY_CONTENT_TYPES:
  801. # Base64 decode + media-cache write of possibly multi-MB payloads — keep it off the event loop.
  802. text, mtype, media_urls, media_types = await asyncio.to_thread(_normalize_content, content)
  803. else:
  804. text, mtype, media_urls, media_types = _normalize_content(content)
  805. if gated:
  806. text = self._clean_mention_text(text)
  807. self._record_recent_richlink(space_id, _richlink_url_from_content(content) or text)
  808. await self.handle_message(_event(text, mtype, media_urls=media_urls, media_types=media_types))
  809. # -- Sidecar lifecycle ---------------------------------------------------------
  810. @staticmethod
  811. def _quick_stdout(cmd: list[str]) -> Optional[str]:
  812. """stdout of a short shell-out, or None if it failed to run."""
  813. try:
  814. return subprocess.run(
  815. cmd, stdin=subprocess.DEVNULL, capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=5.0,
  816. check=False).stdout
  817. except (OSError, subprocess.TimeoutExpired):
  818. return None
  819. @classmethod
  820. def _find_listener_pids(cls, port: int) -> list[int]:
  821. """PIDs listening on a local TCP port (empty if none/undeterminable)."""
  822. out = cls._quick_stdout(["lsof", "-ti", f"tcp:{port}", "-sTCP:LISTEN"])
  823. return [int(tok) for tok in out.split() if tok.strip().isdigit()] if out is not None else []
  824. @classmethod
  825. def _pid_is_sidecar(cls, pid: int) -> bool:
  826. """True if ``pid``'s command line is a Photon sidecar (any Hermes checkout)."""
  827. out = cls._quick_stdout(["ps", "-p", str(pid), "-o", "command="])
  828. return out is not None and "photon/sidecar/index.mjs" in out
  829. @staticmethod
  830. def _pid_alive(pid: int) -> bool:
  831. try:
  832. os.kill(pid, 0) # windows-footgun: ok — only called from _reap_stale_sidecar which win32-guards early
  833. except OSError:
  834. return False
  835. return True
  836. async def _reap_stale_sidecar(self) -> None:
  837. """Kill an orphaned sidecar squatting our port (a SIGKILLed gateway leaves one whose
  838. token we don't know, so every respawn dies on EADDRINUSE). Listeners are verified
  839. by command line before being signalled."""
  840. if sys.platform == "win32": # lsof/ps; orphaning is a POSIX-only path
  841. return
  842. try:
  843. async with httpx.AsyncClient(timeout=2.0, trust_env=False) as client:
  844. await client.post(self._sidecar_url("/healthz"), headers=self._sidecar_headers())
  845. except httpx.RequestError:
  846. return # nothing listening — the normal case
  847. # Off the loop: lsof + one `ps` per pid can hold it 5+5·N s, on every reconnect.
  848. def _inspect():
  849. found = self._find_listener_pids(self._sidecar_port)
  850. mine = [pid for pid in found if self._pid_is_sidecar(pid)]
  851. return mine, [pid for pid in found if pid not in mine]
  852. stale, foreign = await asyncio.to_thread(_inspect)
  853. fix = "free it or set PHOTON_SIDECAR_PORT to a different port"
  854. if not stale:
  855. raise RuntimeError(f"port {self._sidecar_port} is in use by another process "
  856. f"(pids: {foreign or 'unknown'}, not a Photon sidecar) — {fix}")
  857. def _kill(pid: int, sig: int) -> None:
  858. with contextlib.suppress(OSError):
  859. os.kill(pid, sig) # windows-footgun: ok — unreachable on win32 (early return above)
  860. for pid in stale:
  861. logger.warning("[photon] reaping orphaned sidecar (pid %d) on port %d", pid, self._sidecar_port)
  862. _kill(pid, signal.SIGTERM)
  863. deadline = time.time() + 3.0
  864. while time.time() < deadline and any(self._pid_alive(p) for p in stale):
  865. await asyncio.sleep(0.1)
  866. for pid in stale:
  867. if self._pid_alive(pid):
  868. _kill(pid, signal.SIGKILL) # windows-footgun: ok — unreachable on win32 (early return above)
  869. await asyncio.sleep(0.2) # let the OS release the listening socket
  870. if foreign:
  871. raise RuntimeError(
  872. f"port {self._sidecar_port} is also held by non-sidecar processes (pids: {foreign}) — {fix}")
  873. async def _ensure_sidecar_deps(self) -> None:
  874. """Cold-install or refresh sidecar node_modules before spawn (off the loop)."""
  875. if not sidecar_deps_installed():
  876. # Hosted images have no CLI for `hermes photon setup`: connect bootstraps deps itself.
  877. logger.info("[photon] sidecar deps not installed; installing into %s", _sidecar_dir())
  878. await asyncio.to_thread(_reinstall_sidecar_deps)
  879. if not sidecar_deps_installed():
  880. # Deterministic on immutable images — non-retryable so it doesn't spin silently.
  881. raise PhotonSidecarStartupError(
  882. f"Photon sidecar deps could not be installed into "
  883. f"{_sidecar_dir()} (see log for the npm error). "
  884. f"Run: cd {_sidecar_dir()} && npm ci (or `hermes photon setup`)",
  885. code="SIDECAR_DEPS_MISSING", retryable=False)
  886. # `hermes update` bumps the lockfile without reinstalling node_modules; the sidecar
  887. # would spawn against stale deps and die on every reconnect.
  888. if _sidecar_deps_stale():
  889. logger.warning("[photon] sidecar deps are stale (lockfile newer than install); reinstalling before start")
  890. await asyncio.to_thread(_reinstall_sidecar_deps)
  891. async def _apply_spectrum_patch(self, hide_flags: int) -> None:
  892. """Run the mixed-attachment patch script (best-effort, off the loop: up to 10s, every reconnect)."""
  893. try:
  894. patch = await asyncio.to_thread(
  895. subprocess.run,
  896. [self._node_bin, str(_sidecar_dir() / "patch-spectrum-mixed-attachments.mjs"), str(_sidecar_dir())],
  897. capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=10, check=False,
  898. creationflags=hide_flags, env=with_hermes_node_path())
  899. if patch.returncode != 0:
  900. raise RuntimeError((patch.stderr or patch.stdout or "").strip())
  901. if patch.stderr.strip():
  902. logger.debug("[photon] %s", patch.stderr.strip())
  903. except Exception as exc:
  904. logger.warning("[photon] failed to apply Spectrum mixed attachment patch: %s", exc)
  905. async def _start_sidecar(self) -> None:
  906. if self._node_bin is None:
  907. import pm
  908. try:
  909. await asyncio.to_thread(pm.ensure, "node")
  910. installed = pm.installed_package("node")
  911. if installed is None or installed.binary is None:
  912. raise pm.InstallError("node", "ensured but no selected binary was recorded")
  913. self._node_bin = str(installed.binary)
  914. except pm.InstallError as exc:
  915. raise PhotonSidecarStartupError(str(exc), code="SIDECAR_NODE_MISSING", retryable=False) from exc
  916. await self._ensure_sidecar_deps()
  917. await self._reap_stale_sidecar()
  918. env = with_hermes_node_path()
  919. env.update({
  920. "PHOTON_PROJECT_ID": self._project_id, "PHOTON_PROJECT_SECRET": self._project_secret,
  921. "PHOTON_SIDECAR_PORT": str(self._sidecar_port), "PHOTON_SIDECAR_BIND": self._sidecar_bind,
  922. "PHOTON_SIDECAR_TOKEN": self._sidecar_token,
  923. # Exit on stdin EOF so ANY gateway death (incl. SIGKILL) can't orphan it on the port.
  924. "PHOTON_SIDECAR_WATCH_STDIN": "1"})
  925. from hermes_cli._subprocess_compat import windows_hide_flags # hide child console on Windows
  926. await self._apply_spectrum_patch(windows_hide_flags())
  927. try:
  928. self._sidecar_proc = subprocess.Popen( # noqa: ASYNC220 -- persistent sidecar; callers use the Popen pipes and poll()
  929. [self._node_bin, str(_sidecar_dir() / "index.mjs")],
  930. stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, env=env,
  931. # detached-spawn: ok — exits on stdin EOF (PHOTON_SIDECAR_WATCH_STDIN), so it dies with this process
  932. start_new_session=(sys.platform != "win32"),
  933. # Windows: run the persistent sidecar headless so it does not open
  934. # (or leave) a visible console window. CREATE_NO_WINDOW only (no
  935. # DETACHED_PROCESS) so the stdin/stdout pipes above stay usable.
  936. creationflags=windows_hide_flags(),
  937. )
  938. except FileNotFoundError as exc:
  939. # Deterministic: node isn't resolvable (pm store or PATH).
  940. # Retrying can never fix a missing binary (OOF-153).
  941. raise PhotonSidecarStartupError(
  942. f"node binary not found ({self._node_bin!r}) — install Node.js "
  943. f"18+ or run `hermes pm install`: {exc}",
  944. code="SIDECAR_NODE_MISSING",
  945. retryable=False,
  946. ) from exc
  947. # Pump sidecar stderr/stdout into our logger so users see crashes.
  948. loop = asyncio.get_event_loop()
  949. self._sidecar_supervisor_task = loop.create_task(self._supervise_sidecar(self._sidecar_proc))
  950. deadline = time.time() + 15.0 # wait for /healthz — up to 15s on cold start
  951. last_err: Optional[Exception] = None
  952. async with httpx.AsyncClient(timeout=2.0, trust_env=False) as client:
  953. while time.time() < deadline:
  954. if self._sidecar_proc.poll() is not None:
  955. _delete_runtime_record()
  956. raise RuntimeError(
  957. f"Photon sidecar exited with code {self._sidecar_proc.returncode} before becoming ready")
  958. try:
  959. resp = await client.post(self._sidecar_url("/healthz"), headers=self._sidecar_headers())
  960. if resp.status_code == 200: # let out-of-process senders (cron) reach this sidecar
  961. _write_runtime_record(self._sidecar_port, self._sidecar_token, self._sidecar_proc.pid)
  962. return
  963. except httpx.RequestError as e:
  964. last_err = e
  965. await asyncio.sleep(0.2)
  966. _delete_runtime_record()
  967. raise RuntimeError(f"Photon sidecar did not become ready within 15s: {last_err}")
  968. async def _supervise_sidecar(self, proc: subprocess.Popen) -> None:
  969. """Pump the sidecar's stdout/stderr into our logger."""
  970. if proc.stdout is None: # launched without stdout=PIPE
  971. return
  972. stdout = proc.stdout
  973. loop = asyncio.get_event_loop()
  974. try:
  975. while True:
  976. line = await loop.run_in_executor(None, stdout.readline)
  977. if not line:
  978. break
  979. logger.info("[photon-sidecar] %s", line.decode("utf-8", "replace").rstrip())
  980. except Exception as e: # pragma: no cover - defensive
  981. logger.warning("[photon-sidecar] supervisor exited: %s", e)
  982. # A container/supervisor stop signals the whole process tree, so the sidecar (its own
  983. # session) can die before the gateway's stop flow reaches disconnect(). The runner flips
  984. # ``_stop_requested_by_signal`` in its signal handler, ahead of any stop work (#127047).
  985. runner_stop = getattr(getattr(self, "gateway_runner", None), "_stop_requested_by_signal", False)
  986. if self._inbound_running and not runner_stop:
  987. exit_code = proc.poll()
  988. logger.error("[photon] sidecar exited unexpectedly (code %s) — triggering reconnect", exit_code)
  989. self._set_fatal_error(
  990. "SIDECAR_CRASHED", f"Photon sidecar exited unexpectedly (code {exit_code})", retryable=True)
  991. self._dispatch_fatal_notification()
  992. async def _stop_sidecar(self) -> None:
  993. proc = self._sidecar_proc
  994. if proc is None:
  995. _delete_runtime_record() # never leave a record behind on disconnect
  996. return
  997. try:
  998. if proc.stdin is not None: # closing our stdin end is itself a shutdown signal (EOF watch)
  999. with contextlib.suppress(Exception):
  1000. proc.stdin.close()
  1001. if self._http_client is not None: # polite shutdown first
  1002. with contextlib.suppress(Exception):
  1003. await self._http_client.post(
  1004. self._sidecar_url("/shutdown"), headers=self._sidecar_headers(), timeout=2.0)
  1005. try:
  1006. proc.wait(timeout=3.0)
  1007. except subprocess.TimeoutExpired:
  1008. if sys.platform != "win32":
  1009. try:
  1010. os.killpg(os.getpgid(proc.pid), signal.SIGTERM) # windows-footgun: ok
  1011. except (ProcessLookupError, PermissionError):
  1012. proc.terminate()
  1013. else:
  1014. proc.terminate()
  1015. try:
  1016. proc.wait(timeout=2.0)
  1017. except subprocess.TimeoutExpired:
  1018. proc.kill()
  1019. finally:
  1020. self._sidecar_proc = None
  1021. _delete_runtime_record()
  1022. if self._sidecar_supervisor_task is not None:
  1023. # May run INSIDE the supervisor task's own crash chain (sidecar exit -> fatal
  1024. # notify -> gateway disconnect() -> here). A task cancelling itself raises
  1025. # CancelledError into the fatal handler before the reconnect is queued, leaving
  1026. # Photon permanently dead — so let it finish exiting on its own.
  1027. if self._sidecar_supervisor_task is not asyncio.current_task():
  1028. # _stop_sidecar() is called both from external cleanup (Gateway shutdown, explicit
  1029. # disconnect) AND, indirectly, from WITHIN the supervisor task's own crash-handling
  1030. # chain: _supervise_sidecar() detects the sidecar exit, calls _set_fatal_error() +
  1031. # self._notify_fatal_error(), which the Gateway's fatal-error handler answers by calling
  1032. # adapter.disconnect() -> this same _stop_sidecar(). In that second case,
  1033. # self._sidecar_supervisor_task IS the currently-running task. Cancelling it raises
  1034. # CancelledError into its own call stack (at the next await point in
  1035. # _notify_fatal_error() or here), which aborts the fatal-error handler before the
  1036. # Gateway ever reaches the "queue for background reconnection" step -- Photon then stays
  1037. # permanently dead until a manual restart, since asyncio.CancelledError inherits from
  1038. # BaseException (not Exception) and isn't caught by the handler's `except Exception`
  1039. # guards (issue #73159). A task cannot legally cancel itself anyway (the cancellation
  1040. # would only take effect at its own next await, which is exactly the corruption
  1041. # described above), so skip it here and let the task finish exiting on its own instead.
  1042. self._sidecar_supervisor_task.cancel()
  1043. self._sidecar_supervisor_task = None
  1044. # -- Presence watchdog ---------------------------------------------------------
  1045. def _note_upstream_activity(self) -> None:
  1046. """Record proof the upstream gRPC channel is live (inbound line or good probe)."""
  1047. self._last_upstream_activity = time.monotonic()
  1048. self._probe_failures = 0
  1049. async def _probe_once(self) -> str:
  1050. """One ``/probe`` round-trip → ``"alive"`` (HTTP 200, the only proof of liveness),
  1051. ``"hung"`` (the HTTP call timed out; counts toward respawn) or ``"inconclusive"``
  1052. (503/refused/transport error: never counts — the network may just be down and a
  1053. dead process is the supervisor's job)."""
  1054. client = self._http_client
  1055. if client is None:
  1056. return "inconclusive"
  1057. try:
  1058. resp = await client.post(
  1059. self._sidecar_url("/probe"), headers=self._sidecar_headers(), timeout=self._probe_timeout)
  1060. except asyncio.CancelledError:
  1061. raise
  1062. except Exception as e:
  1063. if _is_timeout_error(e):
  1064. logger.debug("[photon] probe HTTP call hung: %s", e)
  1065. return "hung"
  1066. logger.debug("[photon] probe transport error (inconclusive): %s", e)
  1067. return "inconclusive"
  1068. return "alive" if resp.status_code == 200 else "inconclusive"
  1069. async def _respawn_sidecar(self, reason: str) -> None:
  1070. """Restart the sidecar to recover a dead gRPC stream (a fresh ``Spectrum()``
  1071. re-subscribes; the inbound loop re-opens ``/inbound`` on its own). Locked so
  1072. overlapping triggers can't double-spawn."""
  1073. if self._respawn_lock is None:
  1074. self._respawn_lock = asyncio.Lock()
  1075. lock = self._respawn_lock
  1076. if lock.locked():
  1077. logger.info("[photon] respawn already in progress; skipping")
  1078. return
  1079. async with lock:
  1080. logger.warning("[photon] presence watchdog: %s — respawning sidecar", reason)
  1081. try:
  1082. await self._stop_sidecar()
  1083. except Exception:
  1084. logger.exception("[photon] error stopping sidecar during respawn")
  1085. try:
  1086. await self._start_sidecar()
  1087. except Exception:
  1088. logger.exception("[photon] failed to respawn sidecar; watchdog will retry")
  1089. return
  1090. self._note_upstream_activity() # fresh stream: give it a full interval before probing again
  1091. logger.info("[photon] presence watchdog: sidecar respawned, gRPC stream renewed")
  1092. async def _presence_watchdog(self) -> None:
  1093. """Probe on a long interval, skipping when inbound traffic already proved liveness;
  1094. only *hung* probes count toward respawn (``_probe_max_failures``)."""
  1095. await asyncio.sleep(self._probe_interval) # stagger the first probe (fleet restarts, warm-up)
  1096. while self._watchdog_running:
  1097. try:
  1098. idle = time.monotonic() - self._last_upstream_activity
  1099. if idle < self._probe_interval:
  1100. await asyncio.sleep(self._probe_interval - idle)
  1101. continue
  1102. verdict = await self._probe_once()
  1103. if verdict == "alive":
  1104. self._note_upstream_activity()
  1105. elif verdict == "hung":
  1106. self._probe_failures += 1
  1107. logger.warning("[photon] presence probe hung (%d/%d)",
  1108. self._probe_failures, self._probe_max_failures)
  1109. if self._probe_failures >= self._probe_max_failures:
  1110. await self._respawn_sidecar(f"{self._probe_failures} consecutive hung probes")
  1111. else:
  1112. logger.debug("[photon] presence probe inconclusive; taking no action")
  1113. except asyncio.CancelledError:
  1114. raise
  1115. except Exception:
  1116. logger.exception("[photon] presence watchdog iteration failed")
  1117. await asyncio.sleep(self._probe_interval)
  1118. async def _stop_watchdog(self) -> None:
  1119. self._watchdog_running = False
  1120. task, self._watchdog_task = self._watchdog_task, None
  1121. await cancel_task(task)
  1122. # -- Outbound ------------------------------------------------------------------
  1123. async def send(self, chat_id: str, content: str, reply_to: Optional[str] = None,
  1124. metadata: Optional[dict[str, Any]] = None) -> SendResult:
  1125. return await self._sidecar_send(chat_id, self.format_message(content))
  1126. async def send_clarify(self, chat_id: str, question: str, choices: Optional[list], clarify_id: str,
  1127. session_key: str, metadata: Optional[dict[str, Any]] = None) -> SendResult:
  1128. """Multiple-choice renders as a native poll; the vote comes back as a `poll_option`
  1129. event that _dispatch_inbound turns into plain text, so the clarify is flipped into
  1130. text-capture mode like the base fallback."""
  1131. if not choices: # open-ended: base plain-text behaviour is right
  1132. return await super().send_clarify(chat_id, question, choices, clarify_id, session_key, metadata)
  1133. from tools.clarify_gateway import mark_awaiting_text
  1134. mark_awaiting_text(clarify_id)
  1135. result = await self._sidecar_send_poll(chat_id, question, list(choices))
  1136. if not result.success:
  1137. # Old sidecar without /send-poll or a send error: numbered-text clarify fallback
  1138. # (base also calls mark_awaiting_text; harmless).
  1139. logger.warning("[photon] poll clarify failed (%s); falling back to text list", result.error)
  1140. return await super().send_clarify(chat_id, question, choices, clarify_id, session_key, metadata)
  1141. return result
  1142. # -- Outbound media (parity with BlueBubbles): URL-based helpers cache to a local path
  1143. # first; file-based ones pass the path straight to /send-attachment.
  1144. async def send_image(self, chat_id: str, image_url: str, caption: Optional[str] = None,
  1145. reply_to: Optional[str] = None, metadata: Optional[dict[str, Any]] = None) -> SendResult:
  1146. try:
  1147. from gateway.platforms.base import cache_image_from_url
  1148. local_path = await cache_image_from_url(image_url)
  1149. except Exception: # couldn't fetch — send the URL as text
  1150. return await super().send_image(chat_id, image_url, caption, reply_to)
  1151. return await self._sidecar_send_attachment(chat_id, local_path, caption=caption)
  1152. async def send_image_file(self, chat_id: str, image_path: str, caption: Optional[str] = None,
  1153. reply_to: Optional[str] = None, metadata: Optional[dict[str, Any]] = None,
  1154. **kwargs) -> SendResult:
  1155. return await self._sidecar_send_attachment(chat_id, image_path, caption=caption)
  1156. async def send_voice(self, chat_id: str, audio_path: str, caption: Optional[str] = None,
  1157. reply_to: Optional[str] = None, metadata: Optional[dict[str, Any]] = None,
  1158. **kwargs) -> SendResult:
  1159. return await self._sidecar_send_attachment(chat_id, audio_path, caption=caption, kind="voice")
  1160. async def send_video(self, chat_id: str, video_path: str, caption: Optional[str] = None,
  1161. reply_to: Optional[str] = None, metadata: Optional[dict[str, Any]] = None,
  1162. **kwargs) -> SendResult:
  1163. return await self._sidecar_send_attachment(chat_id, video_path, caption=caption)
  1164. async def send_document(self, chat_id: str, file_path: str, caption: Optional[str] = None,
  1165. file_name: Optional[str] = None, reply_to: Optional[str] = None,
  1166. metadata: Optional[dict[str, Any]] = None, **kwargs) -> SendResult:
  1167. return await self._sidecar_send_attachment(chat_id, file_path, name=file_name, caption=caption)
  1168. # send_animation: base falls back to send_image (iMessage renders GIFs inline as images).
  1169. async def _sidecar_try(self, path: str, body: dict[str, Any], what: str) -> bool:
  1170. """Soft-failing sidecar call: True on success, False (debug-logged) on any error."""
  1171. try:
  1172. await self._sidecar_call(path, body)
  1173. return True
  1174. except Exception as e:
  1175. logger.debug("[photon] %s failed: %s", what, e)
  1176. return False
  1177. async def send_typing(self, chat_id: str, metadata=None) -> None:
  1178. now = time.time()
  1179. if now - self._typing_last_sent.get(chat_id, 0.0) < _TYPING_COOLDOWN_SECONDS:
  1180. return
  1181. self._typing_last_sent[chat_id] = now
  1182. await self._sidecar_try("/typing", {"spaceId": chat_id, "state": "start"}, "send_typing")
  1183. async def stop_typing(self, chat_id: str) -> None:
  1184. self._typing_last_sent.pop(chat_id, None)
  1185. await self._sidecar_try("/typing", {"spaceId": chat_id, "state": "stop"}, "stop_typing")
  1186. # -- Reactions (tapbacks). Lifecycle hooks (👀 while processing, 👍/👎 on completion)
  1187. # are opt-in via PHOTON_REACTIONS — noisy on a personal channel.
  1188. _SENT_IDS_MAX = 1000
  1189. _LAST_INBOUND_CHATS_MAX = 200
  1190. def _record_sent_message(self, message_id: Optional[str]) -> None:
  1191. if message_id:
  1192. bounded_put(self._sent_message_ids, message_id, time.time(), self._SENT_IDS_MAX)
  1193. # A DM space is addressable as the chat GUID (`any;-;+1555...`) inbound events carry, or
  1194. # the bare E.164 phone home-channel config uses; the sidecar's resolveSpace treats them
  1195. # as one space, so normalize to the bare phone (mirrors phoneTargetFromSpaceId in index.mjs).
  1196. _DM_CHAT_GUID_RE = re.compile(r"^any;-;(\+\d{6,})$")
  1197. @classmethod
  1198. def _normalize_chat_key(cls, chat_id: str) -> str:
  1199. match = cls._DM_CHAT_GUID_RE.match(chat_id)
  1200. return match.group(1) if match else chat_id
  1201. def _put_by_chat(self, store: dict[str, Any], chat_id: str, value: Any) -> None:
  1202. bounded_put(store, self._normalize_chat_key(chat_id), value, self._LAST_INBOUND_CHATS_MAX)
  1203. def _record_last_inbound(self, chat_id: Optional[str], message_id: Optional[str]) -> None:
  1204. if chat_id and message_id:
  1205. self._put_by_chat(self._last_inbound_by_chat, chat_id, message_id)
  1206. def _record_recent_richlink(self, chat_id: str, text: str) -> None:
  1207. if chat_id and _url_only_candidate(text):
  1208. self._put_by_chat(self._recent_richlinks_by_chat, chat_id, time.time())
  1209. def _is_recent_richlink_preview(self, chat_id: str, content: dict[str, Any]) -> bool:
  1210. if not chat_id or not _is_richlink_preview_content(content):
  1211. return False
  1212. key = self._normalize_chat_key(chat_id)
  1213. last = self._recent_richlinks_by_chat.get(key)
  1214. if last is None:
  1215. return False
  1216. if time.time() - last > _RICHLINK_PREVIEW_SUPPRESS_SECONDS:
  1217. self._recent_richlinks_by_chat.pop(key, None)
  1218. return False
  1219. return True
  1220. def _reactions_enabled(self) -> bool:
  1221. return _get_scoped_secret("PHOTON_REACTIONS", "false").strip().lower() in {"true", "1", "yes", "on"}
  1222. async def _add_reaction(self, chat_id: str, message_id: str, emoji: str) -> bool:
  1223. """Tapback ``emoji`` onto a message. Soft-fails (False), never raises."""
  1224. return await self._sidecar_try(
  1225. "/react", {"spaceId": chat_id, "messageId": message_id, "emoji": emoji}, "add_reaction")
  1226. async def _remove_reaction(self, chat_id: str, message_id: str) -> bool:
  1227. """Retract our tapback (best-effort: the sidecar's per-message reaction handle is
  1228. lost on restart). Soft-fails (False), never raises."""
  1229. return await self._sidecar_try("/unreact", {"spaceId": chat_id, "messageId": message_id}, "remove_reaction")
  1230. # -- Agent-facing reactions (send_message action="react"): deliberate intents, so NOT
  1231. # gated by PHOTON_REACTIONS.
  1232. async def add_reaction(self, chat_id: str, emoji: str, message_id: Optional[str] = None) -> dict[str, Any]:
  1233. """Tapback ``emoji`` onto a message (default: the chat's latest inbound). iMessage
  1234. maps ❤️👍👎😂‼️❓ to native tapbacks; anything else is a custom-emoji reaction."""
  1235. target = message_id or self._last_inbound_by_chat.get(self._normalize_chat_key(chat_id))
  1236. if not target:
  1237. return {"success": False, "error": "no message to react to — pass message_id (no "
  1238. "inbound message seen in this chat since the gateway started)"}
  1239. if not await self._add_reaction(chat_id, target, emoji):
  1240. return {"success": False, "error": "reaction failed (see gateway debug log)"}
  1241. return {"success": True, "message_id": target}
  1242. async def remove_reaction(self, chat_id: str, message_id: Optional[str] = None) -> dict[str, Any]:
  1243. """Retract our tapback from a message (best-effort)."""
  1244. target = message_id or self._last_inbound_by_chat.get(self._normalize_chat_key(chat_id))
  1245. if not target:
  1246. return {"success": False, "error": "no message to unreact — pass message_id"}
  1247. if not await self._remove_reaction(chat_id, target):
  1248. return {"success": False, "error": "unreact failed (see gateway debug log)"}
  1249. return {"success": True, "message_id": target}
  1250. async def on_processing_start(self, event: MessageEvent) -> None:
  1251. """Tapback 👀 on the triggering message while the agent works."""
  1252. if not self._reactions_enabled():
  1253. return
  1254. chat_id = getattr(event.source, "chat_id", None)
  1255. message_id = getattr(event, "message_id", None)
  1256. if chat_id and message_id:
  1257. await self._add_reaction(chat_id, message_id, "\U0001f440")
  1258. # base.on_processing_complete swaps 👀 for 👍/👎 (remove-then-add keeps the sidecar's
  1259. # reaction-handle slot coherent); CANCELLED leaves it unreacted.
  1260. _OK_EMOJI = "\U0001f44d"
  1261. _FAIL_EMOJI = "\U0001f44e"
  1262. async def get_chat_info(self, chat_id: str) -> dict[str, Any]:
  1263. """Photon's ``space.id`` is opaque; with only the id, infer conservatively."""
  1264. return {"name": chat_id, "type": "dm", "id": chat_id}
  1265. def format_message(self, content: str) -> str:
  1266. # Markdown passes through verbatim (sidecar markdown() builder); PHOTON_MARKDOWN=false strips.
  1267. return content if _markdown_enabled() else strip_markdown(content, keep_link_targets=True)
  1268. @staticmethod
  1269. def _is_retryable_error(error: Optional[str]) -> bool:
  1270. if BasePlatformAdapter._is_retryable_error(error):
  1271. return True
  1272. lowered = (error or "").lower()
  1273. if not lowered or "retryable=false" in lowered or "auth_or_config" in lowered:
  1274. return False
  1275. return any(pat in lowered for pat in _PHOTON_RETRYABLE_PATTERNS)
  1276. @staticmethod
  1277. def _is_permanent_sidecar_failure(result: SendResult) -> bool:
  1278. """``auth_or_config`` / ``target_not_allowed`` can't be fixed by retrying or by the
  1279. plain-text resend — either would just double-send a doomed request.
  1280. See #50971.
  1281. """
  1282. raw = result.raw_response
  1283. return (isinstance(raw, dict) and raw.get("retryable") is False
  1284. and raw.get("error_class") in ("auth_or_config", "target_not_allowed"))
  1285. def _send_retry_is_final(self, result: SendResult) -> bool:
  1286. return self._is_permanent_sidecar_failure(result) # already carries the user-facing explanation
  1287. async def _send_plain_fallback(self, chat_id: str, content: str, *, reply_to: Optional[str], metadata: Any) -> SendResult:
  1288. """No Markdown banner (replies are markdown or already-stripped plain text); bypass
  1289. richlink() so a rich-link outage doesn't strand a sendable URL."""
  1290. return await self._sidecar_send(
  1291. chat_id, self.format_message(content)[: self.MAX_MESSAGE_LENGTH], richlink=False, markdown=False)
  1292. async def _post_send(self, path: str, body: dict[str, Any], *, structured: bool = False,
  1293. sent_text: Optional[str] = None) -> SendResult:
  1294. """POST a send-like body and wrap the outcome as a SendResult. ``structured`` carries
  1295. a ``PhotonSidecarError``'s class/retryability so ``_send_with_retry`` can recognise
  1296. permanent failures. ``sent_text`` is what a later threaded reply to this bubble quotes;
  1297. every outbound path passes through here, so recording here covers them all."""
  1298. try:
  1299. data = await self._sidecar_call(path, body)
  1300. except PhotonSidecarError as e:
  1301. if structured:
  1302. return SendResult(success=False, error=str(e), retryable=e.retryable,
  1303. raw_response={"error_class": e.error_class, "retryable": e.retryable})
  1304. return SendResult(success=False, error=str(e))
  1305. except Exception as e:
  1306. return SendResult(success=False, error=str(e))
  1307. self._record_sent_message(data.get("messageId"))
  1308. if sent_text:
  1309. await _record_sent_text_async(body.get("spaceId"), data.get("messageId"), sent_text)
  1310. return SendResult(success=True, message_id=data.get("messageId"))
  1311. async def _sidecar_send(self, space_id: str, text: str, *, richlink: bool = True,
  1312. markdown: bool = True) -> SendResult:
  1313. sent_text = text
  1314. rich_url = _richlink_candidate(text) if richlink else None
  1315. if rich_url:
  1316. rich_result = await self._post_send("/send-richlink", {"spaceId": space_id, "url": rich_url},
  1317. sent_text=sent_text)
  1318. if rich_result.success:
  1319. return rich_result
  1320. logger.warning("[photon] rich-link send failed, falling back to plain text: %s", rich_result.error)
  1321. markdown = False
  1322. send_markdown = markdown and _markdown_enabled()
  1323. # The format key stays even when the text is stripped: the sidecar owns the builder choice,
  1324. # and an older sidecar without chooseSendFormat must keep rendering natively.
  1325. text = _sidecar_payload_text(text, send_markdown)
  1326. if len(text) > self.MAX_MESSAGE_LENGTH:
  1327. logger.warning("[photon] truncating outbound from %d to %d chars", len(text), self.MAX_MESSAGE_LENGTH)
  1328. text = text[: self.MAX_MESSAGE_LENGTH]
  1329. body: dict[str, Any] = {"spaceId": space_id, "text": text}
  1330. if send_markdown: # key omitted when disabled: pre-`format` sidecars still accept
  1331. body["format"] = "markdown"
  1332. return await self._post_send("/send", body, structured=True, sent_text=sent_text)
  1333. async def _sidecar_send_poll(self, space_id: str, title: str, options: list) -> SendResult:
  1334. """POST a native poll to ``/send-poll`` (degrades to a numbered list elsewhere)."""
  1335. opts = [str(o).strip() for o in (options or []) if str(o).strip()]
  1336. if not title or not title.strip():
  1337. return SendResult(success=False, error="poll title is required")
  1338. if len(opts) < 2:
  1339. return SendResult(success=False, error="poll needs at least two options")
  1340. body = {"spaceId": space_id, "title": title.strip()[: self.MAX_MESSAGE_LENGTH], "options": opts}
  1341. return await self._post_send("/send-poll", body, sent_text=body["title"])
  1342. async def _sidecar_send_attachment(self, space_id: str, path: str, *, name: Optional[str] = None,
  1343. mime_type: Optional[str] = None, caption: Optional[str] = None,
  1344. kind: str = "attachment") -> SendResult:
  1345. """POST a local file to ``/send-attachment``. ``kind="voice"`` sends audio as a voice
  1346. note (downgrades to a plain audio attachment where unsupported)."""
  1347. safe_path = self.validate_media_delivery_path(str(path)) # send_*_file / cron may pass arbitrary strings
  1348. if not safe_path:
  1349. return SendResult(success=False, error=f"unsafe or missing attachment path: {path}")
  1350. body = _attachment_body(
  1351. space_id, safe_path, kind=kind, name=name, mime_type=mime_type or _guess_mime(safe_path), caption=caption)
  1352. label = caption or _attachment_label(kind, name or os.path.basename(safe_path))
  1353. return await self._post_send("/send-attachment", body, structured=True, sent_text=label)
  1354. async def _sidecar_call(self, path: str, body: dict[str, Any]) -> dict[str, Any]:
  1355. if self._http_client is None:
  1356. raise RuntimeError("Photon adapter not connected")
  1357. # Fresh client per call so this is safe from a worker thread with its own loop
  1358. # (send_message_tool via _run_async); the inbound loop keeps using _http_client.
  1359. async with httpx.AsyncClient(timeout=30.0, trust_env=False) as client:
  1360. resp = await client.post(self._sidecar_url(path), json=body, headers=self._sidecar_headers())
  1361. if resp.status_code != 200:
  1362. raise _sidecar_error_from_response(path, resp.status_code, resp.text)
  1363. data = resp.json() or {}
  1364. if not data.get("ok"):
  1365. raise _sidecar_error_from_response(path, resp.status_code, resp.text, data)
  1366. return data
  1367. # -- Inbound media helpers -------------------------------------------------------
  1368. def _attachment_message_type(mime: str) -> MessageType:
  1369. mime = (mime or "").lower()
  1370. for prefix, mtype in (("image/", MessageType.PHOTO), ("video/", MessageType.VIDEO), ("audio/", MessageType.AUDIO)):
  1371. if mime.startswith(prefix):
  1372. return mtype
  1373. return MessageType.DOCUMENT
  1374. # MIME → extension maps for cached inbound bytes (mirror BlueBubbles naming).
  1375. _IMAGE_EXT_BY_MIME = {
  1376. "image/jpeg": ".jpg", "image/png": ".png", "image/gif": ".gif", "image/webp": ".webp",
  1377. "image/heic": ".jpg", "image/heif": ".jpg", "image/tiff": ".jpg"}
  1378. _AUDIO_EXT_BY_MIME = {
  1379. "audio/mp3": ".mp3", "audio/mpeg": ".mp3", "audio/ogg": ".ogg", "audio/wav": ".wav",
  1380. "audio/x-caf": ".caf", "audio/mp4": ".m4a", "audio/aac": ".m4a"}
  1381. def _cache_inbound_attachment(content: dict[str, Any], name: str, mime: str, *,
  1382. force_audio: bool = False) -> Optional[str]:
  1383. """Decode base64-inlined ``content["data"]`` into the shared media cache by MIME; None
  1384. when there are no bytes (over the inline cap) or caching fails → marker."""
  1385. if not content.get("data"):
  1386. return None
  1387. try:
  1388. raw = base64.b64decode(content["data"])
  1389. except (ValueError, TypeError) as exc:
  1390. logger.warning("[photon] failed to decode inbound attachment bytes: %s", exc)
  1391. return None
  1392. from gateway.platforms.base import cache_audio_from_bytes, cache_document_from_bytes, cache_image_from_bytes
  1393. mime = (mime or "").lower()
  1394. suffix = Path(name).suffix if name else "" # prefer the real extension
  1395. try:
  1396. if mime.startswith("image/"):
  1397. ext = suffix or _IMAGE_EXT_BY_MIME.get(mime, ".jpg")
  1398. try:
  1399. return cache_image_from_bytes(raw, ext)
  1400. except ValueError: # unsupported image bytes (e.g. HEIC magic): deliver as a document
  1401. return cache_document_from_bytes(raw, name)
  1402. if force_audio or mime.startswith("audio/"):
  1403. ext = suffix or _AUDIO_EXT_BY_MIME.get(mime, ".m4a" if force_audio else ".mp3")
  1404. return cache_audio_from_bytes(raw, ext)
  1405. return cache_document_from_bytes(raw, name) # video, application/*, everything else
  1406. except Exception as exc:
  1407. logger.warning("[photon] failed to cache inbound attachment %s: %s", name, exc)
  1408. return None
  1409. # -- Standalone (out-of-process) send for cron deliveries when the gateway is not
  1410. # co-resident. Reuses a live sidecar (cron processes cannot spawn one). -----------
  1411. def _standalone_error(resp: Any) -> dict[str, Any]:
  1412. """Structured error dict for a failed standalone call (mirrors
  1413. ``_sidecar_error_from_response``, incl. the canonical target_not_allowed text)."""
  1414. data: Any = {}
  1415. with contextlib.suppress(Exception):
  1416. data = resp.json() or {}
  1417. data = data if isinstance(data, dict) else {}
  1418. error_class = str(data.get("error_class") or "sidecar_error")
  1419. retryable = bool(data.get("retryable"))
  1420. if error_class == "target_not_allowed":
  1421. error = _TARGET_NOT_ALLOWED_MESSAGE
  1422. retryable = False
  1423. elif resp.status_code != 200:
  1424. error = f"sidecar returned {resp.status_code}: {resp.text[:200]}"
  1425. else:
  1426. error = str(data.get("error") or "sidecar reported failure")
  1427. return {**send_error(error), "error_class": error_class, "retryable": retryable}
  1428. def _standalone_token_from_record(port: int) -> tuple[Optional[str], int, str]:
  1429. """``(token, port, error)`` from the runtime record the gateway persists once the
  1430. sidecar passes /healthz — the token otherwise exists only in the gateway env."""
  1431. # See #69960.
  1432. record = _read_runtime_record()
  1433. stale_hint = ""
  1434. if record and record.get("token"):
  1435. if _sidecar_pid_alive(record.get("pid")):
  1436. return str(record["token"]), _coerce_port(record.get("port"), port), ""
  1437. stale_hint = (f" A stale sidecar runtime record was found (pid {record.get('pid')} is not running)"
  1438. " — the gateway appears to be down.")
  1439. return None, port, (
  1440. "Photon standalone send requires a running sidecar. Start the Hermes gateway (which spawns "
  1441. f"the sidecar and records its address in <hermes-home>/{_RUNTIME_RECORD_NAME}), "
  1442. "or set PHOTON_SIDECAR_TOKEN in this process's environment." + stale_hint)
  1443. async def _standalone_send(
  1444. pconfig: PlatformConfig, chat_id: str, message: str, *,
  1445. thread_id: Optional[str] = None,
  1446. media_files: Optional[list] = None,
  1447. force_document: bool = False,
  1448. ) -> dict[str, Any]:
  1449. if not HTTPX_AVAILABLE:
  1450. return send_error("httpx not installed")
  1451. port = _coerce_port(
  1452. (pconfig.extra or {}).get("sidecar_port") or _get_scoped_secret("PHOTON_SIDECAR_PORT"), _DEFAULT_SIDECAR_PORT)
  1453. token = _get_scoped_secret("PHOTON_SIDECAR_TOKEN")
  1454. if not token:
  1455. token, port, error = _standalone_token_from_record(port)
  1456. if not token:
  1457. return send_error(error)
  1458. base = f"http://{_DEFAULT_SIDECAR_BIND}:{port}"
  1459. headers = {"X-Hermes-Sidecar-Token": token}
  1460. last_message_id: Optional[str] = None
  1461. try:
  1462. async with httpx.AsyncClient(timeout=30.0, trust_env=False) as client:
  1463. async def _post(path: str, body: dict[str, Any]) -> tuple[Any, Optional[dict[str, Any]]]:
  1464. """(response, data-if-ok-else-None)."""
  1465. resp = await client.post(f"{base}{path}", json=body, headers=headers)
  1466. if resp.status_code != 200:
  1467. return resp, None
  1468. data = resp.json() or {}
  1469. return resp, (data if data.get("ok") else None)
  1470. if message: # 1. text body first, so it leads the conversation
  1471. rich_url = _richlink_candidate(message)
  1472. data = None
  1473. if rich_url:
  1474. _resp, data = await _post("/send-richlink", {"spaceId": chat_id, "url": rich_url})
  1475. if not data: # no URL-only message, or the rich-link send failed: plain text
  1476. send_markdown = _markdown_enabled() and not rich_url
  1477. send_body: dict[str, Any] = {
  1478. "spaceId": chat_id, "text": _sidecar_payload_text(message, send_markdown)[:_MAX_MESSAGE_LENGTH]}
  1479. if send_markdown:
  1480. send_body["format"] = "markdown"
  1481. resp, data = await _post("/send", send_body)
  1482. if not data:
  1483. return _standalone_error(resp)
  1484. last_message_id = data.get("messageId")
  1485. await _record_sent_text_async(chat_id, last_message_id, message)
  1486. # 2. Each attachment as a separate /send-attachment call; media_files is
  1487. # List[Tuple[path, is_voice]] (filter_media_delivery_paths).
  1488. for media_path, is_voice in media_files or []:
  1489. safe_path = BasePlatformAdapter.validate_media_delivery_path(str(media_path))
  1490. if not safe_path:
  1491. logger.warning("[photon] standalone send skipping unsafe path")
  1492. continue
  1493. att_body = _attachment_body(
  1494. chat_id, safe_path, kind="voice" if is_voice else "attachment", mime_type=_guess_mime(safe_path))
  1495. resp, data = await _post("/send-attachment", att_body)
  1496. if not data:
  1497. return _standalone_error(resp)
  1498. last_message_id = data.get("messageId") or last_message_id
  1499. await _record_sent_text_async(chat_id, data.get("messageId"), _attachment_label(
  1500. "voice" if is_voice else "attachment", os.path.basename(safe_path)))
  1501. return {"success": True, "message_id": last_message_id}
  1502. except Exception as e:
  1503. return send_error(f"Photon standalone send failed: {e}")
  1504. # -- Plugin entry point ----------------------------------------------------------
  1505. _SEND_DM_GUID_RE = re.compile(r"^any;-;\+\d{6,}$") # mirrors PhotonAdapter._DM_CHAT_GUID_RE
  1506. def register(ctx) -> None:
  1507. """Called by the Hermes plugin loader at startup."""
  1508. from . import cli as _cli # local: avoid argparse work at module load
  1509. ctx.register_platform(
  1510. # DM GUIDs are adapter-native ids (mirrors the react handler).
  1511. target_ref_syntax_fn=regex_stripped_parser(_SEND_DM_GUID_RE),
  1512. name="photon", label="iMessage via Photon", adapter_factory=lambda cfg: PhotonAdapter(cfg),
  1513. dashboard_description="Use Hermes through iMessage via Photon's managed Spectrum platform.",
  1514. docs_url="https://hermes-agent.nousresearch.com/docs/user-guide/messaging/photon",
  1515. check_fn=check_requirements, validate_config=validate_config, is_connected=is_connected,
  1516. required_env=["PHOTON_PROJECT_ID", "PHOTON_PROJECT_SECRET"],
  1517. install_hint=(
  1518. "Run: hermes photon setup (logs in via device flow, creates a "
  1519. "Spectrum project, links your phone number, installs the "
  1520. "spectrum-ts sidecar)."),
  1521. setup_fn=_cli.gateway_setup, # surfaces Photon in the unified `hermes gateway setup` wizard
  1522. env_enablement_fn=_env_enablement, cron_deliver_env_var="PHOTON_HOME_CHANNEL",
  1523. standalone_sender_fn=_standalone_send, allowed_users_env="PHOTON_ALLOWED_USERS",
  1524. allow_all_env="PHOTON_ALLOW_ALL_USERS", max_message_length=_MAX_MESSAGE_LENGTH, emoji="📱",
  1525. pii_safe=True, # E.164 phone numbers: redact session descriptions before they reach the LLM
  1526. allow_update_command=True,
  1527. # Grounded in spectrum-ts markdownToIMessageText + sidecar send-format.mjs: headings -> bold, tables ->
  1528. # "a | b" rows, code -> Unicode math-monospace; any message containing a URL is stripped to plain text.
  1529. platform_hint=(
  1530. "You are texting via iMessage (Photon). Write like a person texting: short and conversational, "
  1531. "answer first, no preamble or recap. Markdown mostly does not survive here: any message containing "
  1532. "a link is sent as plain text with all formatting stripped, headings flatten to bold, tables to "
  1533. "pipe-separated lines, and backtick or code-block text turns into Unicode look-alike "
  1534. "glyphs that break when copied. So no headers, tables, code fences or backticks; an occasional "
  1535. "**bold** word is fine in a message without links. Put a command or code snippet on its own line "
  1536. "as plain text so it copies and runs. Write links as bare URLs; a message that is only a URL "
  1537. "sends as a rich preview card. You can send files natively: write MEDIA:/absolute/path/to/file "
  1538. "in your response (images and video appear inline, audio as voice notes, other files as "
  1539. "attachments). Recipient identifiers are E.164 phone numbers; never expose them in responses "
  1540. "unless the user asked."),
  1541. # Permanent-message iMessage inboxes (no edit).
  1542. display_tier="low",
  1543. )
  1544. ctx.register_cli_command(
  1545. name="photon", help="Set up and manage the Photon iMessage integration",
  1546. setup_fn=_cli.register_cli, handler_fn=_cli.dispatch)