adapter.py 97 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812
  1. """Google Chat platform adapter.
  2. Inbound: authenticated HTTP callbacks or a Cloud Pub/Sub pull subscription. Outbound:
  3. Chat REST API (synchronous googleapiclient via ``asyncio.to_thread``). The Pub/Sub
  4. callback runs on a background thread, so ``handle_message`` is scheduled thread-safely
  5. onto the loop and never awaited there. Only MESSAGE events reach the agent; membership
  6. events cache the bot id, card clicks are ACK'd only.
  7. """
  8. from __future__ import annotations
  9. import asyncio
  10. import contextlib
  11. import contextvars
  12. import importlib
  13. import json
  14. import logging
  15. import os
  16. import random
  17. import re
  18. import threading
  19. import time
  20. from pathlib import Path as _Path
  21. from typing import Any, Callable, Dict, List, Optional, Tuple
  22. from urllib.parse import urlparse
  23. from agent.i18n import t
  24. from agent.secret_scope import is_multiplex_active
  25. from gateway.platforms._shared import (
  26. get_scoped_secret as _get_scoped_secret, seed_extra_from_env as _seed_extra_from_env, send_error
  27. )
  28. from .cards import card_spec_to_cards_v2, format_message as _format_message
  29. def _adc_would_borrow_foreign_credentials() -> bool:
  30. """True when ADC would read another profile's SA from the process env under
  31. multiplexing (``google.auth.default()`` consults ``os.environ`` directly)."""
  32. return is_multiplex_active() and bool(
  33. os.environ.get("GOOGLE_CHAT_SERVICE_ACCOUNT_JSON") or os.environ.get("GOOGLE_APPLICATION_CREDENTIALS")
  34. )
  35. # Heavy google imports are deferred to first adapter use (~110ms / ~33MB on every CLI
  36. # start). ``_load_google_modules()`` rebinds these; ``HttpError = Exception`` keeps
  37. # ``except HttpError`` valid meanwhile.
  38. GOOGLE_CHAT_AVAILABLE: bool = False
  39. httplib2 = pubsub_v1 = gax_exceptions = service_account = AuthorizedHttp = build_service = MediaFileUpload = None # type: ignore
  40. HttpError: Any = Exception # type: ignore
  41. _google_modules_loaded: bool = False
  42. # (global name, module, attribute-or-None) rebound by ``_load_google_modules``.
  43. _GOOGLE_IMPORTS = (
  44. ("httplib2", "httplib2", None), ("pubsub_v1", "google.cloud.pubsub_v1", None),
  45. ("gax_exceptions", "google.api_core.exceptions", None), ("service_account", "google.oauth2.service_account", None),
  46. ("AuthorizedHttp", "google_auth_httplib2", "AuthorizedHttp"), ("build_service", "googleapiclient.discovery", "build"),
  47. ("HttpError", "googleapiclient.errors", "HttpError"), ("MediaFileUpload", "googleapiclient.http", "MediaFileUpload"),
  48. )
  49. _GOOGLE_ID_TOKEN_CERTS_TTL_SECONDS = 300
  50. _google_id_token_request: Any = None
  51. _google_id_token_request_lock = threading.Lock()
  52. class _CachedGoogleAuthRequest:
  53. """Caches successful GET responses (Google cert fetches) for ``ttl_seconds``."""
  54. def __init__(self, request: Any, ttl_seconds: int = _GOOGLE_ID_TOKEN_CERTS_TTL_SECONDS) -> None:
  55. self._request, self._ttl_seconds, self._lock = request, ttl_seconds, threading.Lock()
  56. self._cache: dict[tuple[str, str], tuple[float, Any]] = {}
  57. def __call__(self, url: str, method: str = "GET", **kwargs: Any) -> Any:
  58. cache_key = (method.upper(), url)
  59. if cache_key[0] != "GET":
  60. return self._request(url=url, method=method, **kwargs)
  61. now = time.monotonic()
  62. with self._lock:
  63. cached = self._cache.get(cache_key)
  64. if cached and cached[0] > now:
  65. return cached[1]
  66. response = self._request(url=url, method=method, **kwargs)
  67. if getattr(response, "status", None) == 200:
  68. with self._lock:
  69. self._cache[cache_key] = (now + self._ttl_seconds, response)
  70. return response
  71. def _get_google_id_token_request() -> Any:
  72. global _google_id_token_request
  73. with _google_id_token_request_lock:
  74. if _google_id_token_request is None:
  75. try:
  76. from google.auth.transport import requests as google_requests
  77. except ImportError as exc:
  78. raise RuntimeError("google-auth is required for Google Chat HTTP callbacks") from exc
  79. _google_id_token_request = _CachedGoogleAuthRequest(google_requests.Request())
  80. return _google_id_token_request
  81. def _verify_google_id_token(token: str, audience: str) -> dict[str, Any]:
  82. try:
  83. from google.oauth2 import id_token
  84. except ImportError as exc:
  85. raise RuntimeError("google-auth is required for Google Chat HTTP callbacks") from exc
  86. return id_token.verify_oauth2_token(token, _get_google_id_token_request(), audience)
  87. def _load_google_modules() -> bool:
  88. """Lazily import the google stack (idempotent); True when the optional deps exist."""
  89. global GOOGLE_CHAT_AVAILABLE, _google_modules_loaded
  90. if _google_modules_loaded:
  91. return GOOGLE_CHAT_AVAILABLE
  92. _google_modules_loaded = True
  93. try:
  94. loaded = {
  95. name: getattr(importlib.import_module(module), attr) if attr else importlib.import_module(module)
  96. for name, module, attr in _GOOGLE_IMPORTS
  97. }
  98. except ImportError:
  99. GOOGLE_CHAT_AVAILABLE = False
  100. return False
  101. globals().update(loaded)
  102. GOOGLE_CHAT_AVAILABLE = True
  103. return True
  104. from gateway.config import Platform, PlatformConfig
  105. # Register the dynamic enum member at import time so ``Platform.GOOGLE_CHAT``
  106. # resolves before any adapter instance exists.
  107. Platform("google_chat")
  108. from gateway.platforms.helpers import MessageDeduplicator
  109. from gateway.platforms.base import (
  110. gateway_trust_env, BasePlatformAdapter, SendResult,
  111. cache_audio_from_bytes_async, cache_document_from_bytes_async, cache_image_from_bytes_async,
  112. cache_video_from_bytes_async,
  113. )
  114. from gateway.platforms.event import MessageEvent, MessageType, ProcessingOutcome
  115. # Pinned to the legacy module path so operator log filters keep matching.
  116. logger = logging.getLogger("gateway.platforms.google_chat")
  117. _SUBSCRIPTION_PATH_RE = re.compile(r"^projects/(?P<project>[^/]+)/subscriptions/(?P<sub>[^/]+)$")
  118. # chat.bot covers the bot's own messaging ops; it CANNOT call media.upload
  119. # (user OAuth required — see ``oauth.py``).
  120. _CHAT_SCOPES = ["https://www.googleapis.com/auth/chat.bot", "https://www.googleapis.com/auth/pubsub"]
  121. _MAX_TEXT_LENGTH = 4000 # Chat limit is 4096; leave margin.
  122. _RATE_LIMIT_WARN_THRESHOLD = 5
  123. # Bounded outbound retry for transient 429/5xx so a true outage surfaces quickly.
  124. _RETRY_MAX_ATTEMPTS, _RETRY_BASE_DELAY, _RETRY_MAX_DELAY, _RETRY_JITTER = 3, 1.0, 8.0, 0.3
  125. _RETRYABLE_HTTP_STATUSES = frozenset({429, 500, 502, 503, 504})
  126. _TRANSPORT_ERROR_PHRASES = ("timeout", "timed out", "broken pipe", "remote disconnected")
  127. # Left in ``_typing_messages`` after ``send()`` patched the typing card: stops
  128. # ``_keep_typing`` from creating a fresh card and ``stop_typing`` from deleting
  129. # (tombstoning) the response we just patched.
  130. _TYPING_CONSUMED_SENTINEL = "<consumed>"
  131. # SSRF guard: attachment download URIs must target a Google-owned https host
  132. # (else the SA bearer token could be sent to e.g. the GCE metadata service).
  133. _TRUSTED_ATTACHMENT_HOSTS = (
  134. "googleapis.com", "chat.google.com", "drive.google.com", "docs.google.com",
  135. "lh3.googleusercontent.com", "lh4.googleusercontent.com", "lh5.googleusercontent.com", "lh6.googleusercontent.com",
  136. )
  137. _REDACTIONS = (
  138. (re.compile(r"projects/[^/\s]+/subscriptions/[^/\s]+"), "projects/<redacted>/subscriptions/<redacted>"),
  139. (re.compile(r"projects/[^/\s]+/topics/[^/\s]+"), "projects/<redacted>/topics/<redacted>"),
  140. (re.compile(r"[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.iam\.gserviceaccount\.com"), "<sa>@<project>.iam.gserviceaccount.com"),
  141. )
  142. _MIME_MESSAGE_TYPES = (("image/", MessageType.PHOTO), ("audio/", MessageType.AUDIO), ("video/", MessageType.VIDEO))
  143. _MEDIA_CACHERS = (
  144. ("image/", cache_image_from_bytes_async, ".jpg"), ("audio/", cache_audio_from_bytes_async, ".ogg"),
  145. ("video/", cache_video_from_bytes_async, ".mp4"),
  146. )
  147. def _http_status(exc: BaseException) -> Any:
  148. """``resp.status`` of a googleapiclient HttpError, or None."""
  149. return getattr(getattr(exc, "resp", None), "status", None)
  150. def _is_retryable_error(exc: BaseException) -> bool:
  151. """True for transient failures (429, 5xx, transport errors); auth/4xx are permanent."""
  152. status = _http_status(exc)
  153. if isinstance(status, int):
  154. return status in _RETRYABLE_HTTP_STATUSES
  155. # SSL/socket errors carry no HTTP status: match common transport wording.
  156. text = str(exc).lower()
  157. return any(p in text for p in _TRANSPORT_ERROR_PHRASES) or (
  158. "connection" in text and any(w in text for w in ("reset", "refused", "aborted"))
  159. )
  160. def check_google_chat_requirements() -> bool:
  161. """PASSIVE deps probe; must never install. Registry ``check_fn`` uses this via ``_check_for_registry``."""
  162. return _load_google_modules()
  163. def ensure_google_chat_deps() -> bool:
  164. """ACTIVE installer (registry ``ensure_deps_fn``).
  165. PM owns the install; a refusal (lazy installs off, unsupported platform,
  166. network) propagates so the registry logs the reason. Resets the failed-import
  167. cache so ``create_adapter()`` can load modules after install.
  168. """
  169. global _google_modules_loaded, GOOGLE_CHAT_AVAILABLE
  170. if GOOGLE_CHAT_AVAILABLE:
  171. return True
  172. from pm import InstallError, ensure_import
  173. # Request BOTH extras before surfacing a failure: a successful install raises
  174. # InstallError("restart Hermes to activate…") for the first extra, and aborting
  175. # there would leave the second uninstalled — the restart would land back here.
  176. failures: list[InstallError] = []
  177. for extra in ("google", "google-chat"):
  178. try:
  179. ensure_import(extra)
  180. except InstallError as exc:
  181. failures.append(exc)
  182. if failures:
  183. raise failures[0]
  184. _google_modules_loaded = False
  185. return _load_google_modules()
  186. def _is_google_owned_host(url: str) -> bool:
  187. """Return True iff *url* is https and targets a Google-owned domain."""
  188. try:
  189. parsed = urlparse(url)
  190. except Exception:
  191. return False
  192. host = (parsed.hostname or "").lower()
  193. if parsed.scheme != "https" or not host:
  194. return False
  195. return any(host == h or host.endswith("." + h) for h in _TRUSTED_ATTACHMENT_HOSTS)
  196. def _redact_sensitive(text: str) -> str:
  197. """Redact Pub/Sub resource paths and SA emails from user-facing error strings."""
  198. if not text:
  199. return text
  200. for pattern, repl in _REDACTIONS:
  201. text = pattern.sub(repl, text)
  202. return text
  203. def _mime_for_message_type(mime: str) -> MessageType:
  204. """Map a MIME string to a MessageType; non-media falls through to DOCUMENT."""
  205. for prefix, message_type in _MIME_MESSAGE_TYPES:
  206. if mime and mime.startswith(prefix):
  207. return message_type
  208. return MessageType.DOCUMENT
  209. class _SACredentialError(Exception):
  210. """Internal: classified SA-credential load failure (``kind`` + optional cause)."""
  211. def __init__(self, kind: str, detail: Optional[BaseException] = None) -> None:
  212. super().__init__(kind)
  213. self.kind, self.detail = kind, detail
  214. def _load_sa_credentials_from(sa_value: Optional[str]) -> Any:
  215. """Build SA credentials from a path / inline JSON, or fall back to ADC.
  216. Raises ``_SACredentialError`` with kind in {inline_invalid, not_found,
  217. file_invalid, adc_foreign, adc_no_auth, adc_failed}."""
  218. if sa_value:
  219. if sa_value.lstrip().startswith("{"):
  220. try:
  221. info = json.loads(sa_value)
  222. except json.JSONDecodeError as exc:
  223. raise _SACredentialError("inline_invalid", exc) from exc
  224. elif not os.path.exists(sa_value):
  225. raise _SACredentialError("not_found")
  226. else:
  227. try:
  228. with open(sa_value, "r", encoding="utf-8-sig") as fh:
  229. info = json.load(fh)
  230. except json.JSONDecodeError as exc:
  231. raise _SACredentialError("file_invalid", exc) from exc
  232. return service_account.Credentials.from_service_account_info(info, scopes=_CHAT_SCOPES)
  233. # No explicit SA — ADC (Cloud Run / GCE workload identity, or gcloud ADC login).
  234. if _adc_would_borrow_foreign_credentials():
  235. raise _SACredentialError("adc_foreign")
  236. try:
  237. import google.auth as google_auth
  238. except ImportError:
  239. raise _SACredentialError("adc_no_auth")
  240. try:
  241. credentials, _project = google_auth.default(scopes=_CHAT_SCOPES)
  242. except Exception as exc:
  243. raise _SACredentialError("adc_failed", exc) from exc
  244. return credentials
  245. class _ThreadCountStore:
  246. """Persisted per-(chat_id, thread_name) inbound counter driving the DM main-flow vs
  247. side-thread heuristic (0: Chat auto-created the thread for a top-level message; >=1:
  248. user engaged an existing thread). Persisted because a restart that wiped counts would
  249. demote active side-threads to main flow and leak context. Format
  250. ``{"<chat_id>": {"<thread_name>": <int>}}``; missing/corrupt resets to empty."""
  251. def __init__(self, path: _Path):
  252. self._path = path
  253. self._counts: dict[str, dict[str, int]] = {}
  254. def load(self) -> None:
  255. """Load counts from disk; missing file → empty, corrupt JSON → empty + warn."""
  256. self._counts = {}
  257. if not self._path.exists():
  258. return
  259. try:
  260. raw = self._path.read_text(encoding="utf-8-sig")
  261. data = json.loads(raw) if raw.strip() else {}
  262. except (json.JSONDecodeError, OSError) as exc:
  263. fmt = ("[GoogleChat] thread-count store at %s is corrupt; starting fresh: %s" if isinstance(exc, ValueError)
  264. else "[GoogleChat] could not read thread-count store at %s: %s")
  265. logger.warning(fmt, self._path, exc)
  266. return
  267. # Anything off-schema is dropped silently.
  268. for chat_id, threads in (data.items() if isinstance(data, dict) else ()):
  269. if isinstance(chat_id, str) and isinstance(threads, dict):
  270. clean = {t: c for t, c in threads.items() if isinstance(t, str) and isinstance(c, int)}
  271. if clean:
  272. self._counts[chat_id] = clean
  273. def get(self, chat_id: str, thread_name: str) -> int:
  274. return self._counts.get(chat_id, {}).get(thread_name, 0)
  275. def incr(self, chat_id: str, thread_name: str) -> int:
  276. """Increment and write through; returns the PRE-increment value."""
  277. chat_counts = self._counts.setdefault(chat_id, {})
  278. prev = chat_counts.get(thread_name, 0)
  279. chat_counts[thread_name] = prev + 1
  280. self._save()
  281. return prev
  282. def decr(self, chat_id: str, thread_name: str) -> None:
  283. """Undo one :meth:`incr` for an inbound that was not admitted; never below zero."""
  284. chat_counts = self._counts.get(chat_id, {})
  285. if chat_counts.get(thread_name, 0) > 0:
  286. chat_counts[thread_name] -= 1
  287. self._save()
  288. def _save(self) -> None:
  289. """Atomic write; failure is non-fatal (in-memory counts stay consistent)."""
  290. try:
  291. self._path.parent.mkdir(parents=True, exist_ok=True)
  292. tmp = self._path.with_suffix(self._path.suffix + ".tmp")
  293. tmp.write_text(json.dumps(self._counts, separators=(",", ":")), encoding="utf-8")
  294. os.replace(tmp, self._path)
  295. except OSError as exc:
  296. logger.warning("[GoogleChat] could not persist thread-count store to %s: %s", self._path, exc)
  297. _SA_ERROR_MESSAGES = {
  298. "inline_invalid": "Inline SA JSON is not valid JSON: {exc}",
  299. "not_found": "Service Account JSON file not found at configured path.",
  300. "file_invalid": "Service Account JSON file is not valid JSON: {exc}",
  301. "adc_foreign": ("Google Chat ADC skipped for this profile: service-account credentials are set in the process "
  302. "environment but not in this profile's secret scope. Set GOOGLE_CHAT_SERVICE_ACCOUNT_JSON in this "
  303. "profile's .env."),
  304. "adc_no_auth": ("No Service Account credentials configured. Set GOOGLE_CHAT_SERVICE_ACCOUNT_JSON or "
  305. "GOOGLE_APPLICATION_CREDENTIALS, or install google-auth to use Application Default Credentials."),
  306. "adc_failed": ("No Service Account credentials configured and Application Default Credentials are unavailable. Set "
  307. "GOOGLE_CHAT_SERVICE_ACCOUNT_JSON or run ``gcloud auth application-default login``. ADC error: {exc}"),
  308. }
  309. def _thread_body(text: str, thread_id: Optional[str]) -> dict[str, Any]:
  310. """``{"text": ...}`` plus ``thread.name`` when replying into a thread."""
  311. body: dict[str, Any] = {"text": text}
  312. if thread_id:
  313. body["thread"] = {"name": thread_id}
  314. return body
  315. def _create_kwargs(chat_id: str, body: dict[str, Any]) -> dict[str, Any]:
  316. """messages.create kwargs. With ``thread.name`` we MUST pass
  317. ``messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD`` — the default silently
  318. ignores thread.name; FALLBACK (vs OR_FAIL) still delivers when the thread is gone."""
  319. kwargs: dict[str, Any] = {"parent": chat_id, "body": body}
  320. if (body.get("thread") or {}).get("name"):
  321. kwargs["messageReplyOption"] = "REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD"
  322. return kwargs
  323. class GoogleChatAdapter(BasePlatformAdapter):
  324. """Google Chat bot adapter: Pub/Sub pull (or HTTP callbacks) + Chat REST API. Env vars
  325. are documented in gateway/config.py (GOOGLE_CHAT_PROJECT_ID, GOOGLE_CHAT_SUBSCRIPTION_NAME,
  326. GOOGLE_CHAT_SERVICE_ACCOUNT_JSON + optional allowlist/home-channel/flow-control keys)."""
  327. MAX_MESSAGE_LENGTH = _MAX_TEXT_LENGTH
  328. # Pub/Sub supervisor configuration.
  329. _MAX_RECONNECT_ATTEMPTS = 10
  330. _RECONNECT_BASE_DELAY = 2.0
  331. _RECONNECT_MAX_DELAY = 120.0
  332. _LEGACY_USER_IDENTITY = "__legacy__"
  333. def __init__(self, config: PlatformConfig):
  334. # Bundled platform plugins are looked up by enum value (matches Teams, IRC).
  335. super().__init__(config, Platform("google_chat"))
  336. # Load here (not only in connect()) so direct method calls see real
  337. # ``MediaFileUpload`` / ``HttpError`` classes. Idempotent.
  338. _load_google_modules()
  339. self._subscriber = self._chat_api = self._credentials = self._streaming_pull_future = None
  340. self._project_id = self._subscription_path = self._bot_user_id = None # bot id is users/{id}
  341. self._supervisor_task: Optional[asyncio.Task] = None
  342. self._loop: Optional[asyncio.AbstractEventLoop] = None
  343. # The profile scope this adapter was connected under (multiplex: HERMES_HOME override + secret
  344. # scope). Pub/Sub callbacks arrive on the gRPC SubscriberClient's own threads with an EMPTY
  345. # context, and ``run_coroutine_threadsafe`` copies THAT context onto the loop task — so
  346. # ``_dispatch_message`` and everything it reaches (attachment cache, per-user OAuth token
  347. # store, delivery ledger, TTS keys) would resolve the launch profile. Captured in ``connect()``.
  348. self._scope_ctx: Optional[contextvars.Context] = None
  349. # User-authed Chat clients for native ``media.upload`` (bot identity is rejected
  350. # there) keyed by sender email; ``_user_credentials``/``_user_chat_api`` = LEGACY fallback.
  351. self._user_chat_api = self._user_credentials = None
  352. self._user_creds_by_email: dict[str, Any] = {}
  353. self._user_chat_api_by_email: dict[str, Any] = {}
  354. # chat_id → most-recent inbound sender email (drives per-user token lookup).
  355. self._last_sender_by_chat: dict[str, str] = {}
  356. self._dedup = MessageDeduplicator()
  357. self._shutting_down = False
  358. self._typing_messages: dict[str, str] = {}
  359. self._clarify_state, self._rate_limit_hits = {}, {}
  360. # Last inbound thread per space: DMs get a NEW thread per top-level message but users
  361. # see one conversation, so thread_id leaves the source (stable session key) and is cached here.
  362. self._last_inbound_thread: dict[str, str] = {}
  363. from hermes_constants import get_hermes_home as _get_hermes_home
  364. self._thread_count_store = _ThreadCountStore(_get_hermes_home() / "google_chat_thread_counts.json")
  365. # In-flight typing-card creates per chat_id: reserved BEFORE the API call so
  366. # concurrent _keep_typing calls wait instead of duplicating cards.
  367. self._typing_card_inflight: dict[str, asyncio.Event] = {}
  368. # Typing cards that lost a race with send(); patched away at end of turn.
  369. self._orphan_typing_messages: dict[str, list[str]] = {}
  370. # Snapshot profile-scoped settings now: Pub/Sub callbacks run on threads
  371. # where the ContextVar secret scope is unavailable.
  372. extra = self.config.extra
  373. self._max_messages = self._int_setting(extra, "max_messages", "GOOGLE_CHAT_MAX_MESSAGES", 1)
  374. self._max_bytes = self._int_setting(extra, "max_bytes", "GOOGLE_CHAT_MAX_BYTES", 16 * 1024 * 1024)
  375. self._bootstrap_spaces = str(
  376. extra.get("bootstrap_spaces") or _get_scoped_secret("GOOGLE_CHAT_BOOTSTRAP_SPACES", "") or "").strip()
  377. self._debug_raw = bool(extra.get("debug_raw") or _get_scoped_secret("GOOGLE_CHAT_DEBUG_RAW"))
  378. self._http_events_url = self._str_setting(extra, "http_events_url", "GOOGLE_CHAT_HTTP_EVENTS_URL")
  379. self._http_events_audience = self._str_setting(
  380. extra, "http_events_audience", "GOOGLE_CHAT_HTTP_EVENTS_AUDIENCE", self._http_events_url)
  381. self._http_events_service_account_email = self._str_setting(
  382. extra, "http_events_service_account_email", "GOOGLE_CHAT_HTTP_EVENTS_SERVICE_ACCOUNT_EMAIL").lower()
  383. @staticmethod
  384. def _int_setting(extra: dict[str, Any], key: str, env_name: str, default: int) -> int:
  385. try:
  386. return int(extra.get(key) or _get_scoped_secret(env_name, str(default)))
  387. except (ValueError, TypeError):
  388. return default
  389. @staticmethod
  390. def _str_setting(extra: dict[str, Any], key: str, env_name: str, fallback: str = "") -> str:
  391. return (extra.get(key) or _get_scoped_secret(env_name, "") or fallback).strip()
  392. # -- configuration -------------------------------------------------------
  393. def _load_sa_credentials(self) -> Any:
  394. """SA credentials: ``extra['service_account_json']`` → GOOGLE_APPLICATION_CREDENTIALS → ADC.
  395. Priority: 1. Explicit ``extra['service_account_json']`` (path or inline JSON) 2. 3. Application
  396. Default Credentials via ``google.auth.default()`` — works on Cloud Run / GCE / GKE with a workload
  397. identity attached, or locally via ``gcloud auth application-default login``. Lets operators run the
  398. gateway in GCP without managing SA key files. Pattern lifted from PR #14965.
  399. """
  400. sa_path = self.config.extra.get("service_account_json") or _get_scoped_secret("GOOGLE_APPLICATION_CREDENTIALS")
  401. try:
  402. credentials = _load_sa_credentials_from(sa_path)
  403. except _SACredentialError as err:
  404. message = _SA_ERROR_MESSAGES[err.kind].format(exc=err.detail)
  405. if err.kind == "not_found":
  406. raise FileNotFoundError(message)
  407. raise ValueError(message) from err.detail
  408. if not sa_path:
  409. logger.info("[GoogleChat] No SA JSON configured; using Application Default Credentials")
  410. return credentials
  411. def _validate_config(self) -> tuple[str, Optional[str]]:
  412. """Return (project_id, subscription_path); the latter is None for HTTP inbound.
  413. Raises ValueError with a sanitized message on any config problem."""
  414. project_id = (self.config.extra.get("project_id") or "").strip()
  415. subscription = (self.config.extra.get("subscription_name") or "").strip()
  416. http_events_url = (self.config.extra.get("http_events_url") or "").strip()
  417. if subscription:
  418. match = _SUBSCRIPTION_PATH_RE.match(subscription)
  419. if not match:
  420. raise ValueError("GOOGLE_CHAT_SUBSCRIPTION_NAME must match 'projects/<project>/subscriptions/<sub>'.")
  421. subscription_project = match.group("project")
  422. if project_id and subscription_project != project_id:
  423. raise ValueError(
  424. "project_id in GOOGLE_CHAT_PROJECT_ID does not match the project embedded in GOOGLE_CHAT_SUBSCRIPTION_NAME."
  425. )
  426. return project_id or subscription_project, subscription
  427. if http_events_url:
  428. return project_id, None
  429. if not project_id:
  430. raise ValueError("GOOGLE_CHAT_PROJECT_ID (or GOOGLE_CLOUD_PROJECT) is not set.")
  431. raise ValueError(
  432. "GOOGLE_CHAT_SUBSCRIPTION_NAME (or GOOGLE_CHAT_SUBSCRIPTION) is not set. "
  433. "Set GOOGLE_CHAT_HTTP_EVENTS_URL for HTTP callback mode."
  434. )
  435. # -- loop bridge (Pub/Sub thread -> asyncio loop) ------------------------
  436. @staticmethod
  437. def _log_background_failure(future: Any) -> None:
  438. try:
  439. future.result()
  440. except Exception:
  441. logger.exception("[GoogleChat] Background inbound processing failed")
  442. @staticmethod
  443. def _loop_accepts_callbacks(loop: Optional[asyncio.AbstractEventLoop]) -> bool:
  444. return loop is not None and not bool(getattr(loop, "is_closed", lambda: False)())
  445. def _submit_on_loop(self, coro: Any) -> None:
  446. """Schedule a coroutine on the adapter loop from a Pub/Sub callback thread."""
  447. if not self._loop_accepts_callbacks(loop := self._loop):
  448. # Shutdown race: safe to drop, Pub/Sub redelivers on next reconnect.
  449. logger.warning("[GoogleChat] Loop not accepting callbacks; dropping event")
  450. return
  451. try:
  452. from agent.async_utils import safe_schedule_threadsafe
  453. # run_coroutine_threadsafe copies the CALLING thread's context onto the loop task; from the
  454. # gRPC callback thread that is empty. Run the scheduling inside the adapter's connect-time
  455. # scope so the task (and every to_thread/create_task under it) carries the profile.
  456. ctx = self._scope_ctx.copy() if self._scope_ctx is not None else contextvars.copy_context()
  457. future = ctx.run(
  458. safe_schedule_threadsafe, coro, loop, logger=logger,
  459. log_message="[GoogleChat] Failed to schedule background callback", log_level=logging.WARNING,
  460. )
  461. except RuntimeError:
  462. logger.warning("[GoogleChat] Loop closed between check and submit")
  463. return
  464. if future is not None:
  465. future.add_done_callback(self._log_background_failure)
  466. # -- bot identity --------------------------------------------------------
  467. def _bot_id_cache_path(self) -> _Path:
  468. """Resolved at call time so multiplexed profiles don't share one cache file."""
  469. from hermes_constants import get_hermes_home as _get_hermes_home
  470. return _get_hermes_home() / "google_chat_bot_id.json"
  471. def _load_cached_bot_id(self) -> Optional[str]:
  472. try:
  473. return json.loads(self._bot_id_cache_path().read_text(encoding="utf-8-sig")).get("bot_user_id") or None
  474. except (OSError, json.JSONDecodeError):
  475. return None
  476. def _save_cached_bot_id(self, bot_user_id: str) -> None:
  477. try:
  478. path = self._bot_id_cache_path()
  479. path.parent.mkdir(parents=True, exist_ok=True)
  480. path.write_text(json.dumps({"bot_user_id": bot_user_id}), encoding="utf-8")
  481. except OSError:
  482. logger.debug("[GoogleChat] Could not persist bot_user_id cache", exc_info=True)
  483. async def _resolve_bot_user_id(self) -> Optional[str]:
  484. """Resolve ``users/{id}`` via members.list on the home channel, then bootstrap
  485. spaces. None when no space is known (self-filter falls back to ``sender.type == 'BOT'``)."""
  486. candidate_spaces: list[str] = []
  487. if self.config.home_channel and self.config.home_channel.chat_id:
  488. candidate_spaces.append(self.config.home_channel.chat_id)
  489. if self._bootstrap_spaces:
  490. candidate_spaces.extend(s.strip() for s in self._bootstrap_spaces.split(",") if s.strip())
  491. for space in candidate_spaces:
  492. try:
  493. members = await asyncio.to_thread(
  494. lambda s=space: self._chat_api.spaces().members().list(parent=s, pageSize=50)
  495. .execute(http=self._new_authed_http())
  496. )
  497. except HttpError as exc:
  498. logger.debug("[GoogleChat] members.list failed on %s: %s", space, _redact_sensitive(str(exc)))
  499. continue
  500. for member in members.get("memberships", []):
  501. if member.get("member", {}).get("type") == "BOT" and member.get("member", {}).get("name"):
  502. return member["member"]["name"]
  503. return None
  504. # -- connection lifecycle ------------------------------------------------
  505. def _connect_failed(self, log_fmt: str, exc: BaseException, code: str, *, retryable: bool) -> bool:
  506. """Log a redacted connect-time failure, record it as fatal, return False."""
  507. msg = _redact_sensitive(str(exc))
  508. logger.error(log_fmt, msg)
  509. self._set_fatal_error(code=code, message=msg, retryable=retryable)
  510. return False
  511. async def _load_user_oauth(self) -> None:
  512. """Legacy single-user OAuth (per-user tokens load lazily on first send).
  513. Failure is NON-fatal: only attachments degrade to a text notice."""
  514. try:
  515. from .oauth import load_user_credentials as _load_user_creds, build_user_chat_service as _build_user_chat
  516. from .oauth import list_authorized_emails as _list_emails
  517. user_creds = await asyncio.to_thread(_load_user_creds)
  518. if user_creds is not None:
  519. self._user_credentials = user_creds
  520. self._user_chat_api = await asyncio.to_thread(lambda: _build_user_chat(user_creds))
  521. logger.info("[GoogleChat] Legacy user OAuth loaded — fallback attachment delivery enabled")
  522. authorized = await asyncio.to_thread(_list_emails)
  523. if authorized:
  524. logger.info("[GoogleChat] %d per-user OAuth tokens on disk: %s", len(authorized), ", ".join(authorized))
  525. elif user_creds is None:
  526. logger.info(
  527. "[GoogleChat] No user OAuth tokens at setup — file attachments will degrade to text-only fallback. "
  528. "Each user runs /setup-files once in their own DM to enable native attachments."
  529. )
  530. except Exception as exc:
  531. logger.warning(
  532. "[GoogleChat] User OAuth load failed (attachments will degrade to text-only fallback): %s",
  533. _redact_sensitive(str(exc)),
  534. )
  535. self._user_credentials = self._user_chat_api = None
  536. async def _check_subscription(self, subscription_path: str, credentials: Any) -> bool:
  537. """Create the subscriber and verify the subscription exists / SA has access."""
  538. fatals = {
  539. gax_exceptions.NotFound: ("subscription_not_found", "Pub/Sub subscription not found at configured path"),
  540. gax_exceptions.PermissionDenied: (
  541. "subscription_permission", "Service Account lacks roles/pubsub.subscriber on the subscription"),
  542. }
  543. self._subscriber = pubsub_v1.SubscriberClient(credentials=credentials)
  544. try:
  545. await asyncio.to_thread(lambda: self._subscriber.get_subscription(request={"subscription": subscription_path}))
  546. except (gax_exceptions.NotFound, gax_exceptions.PermissionDenied) as exc:
  547. code, message = fatals[type(exc)]
  548. self._set_fatal_error(code=code, message=message, retryable=False)
  549. return False
  550. except Exception as exc:
  551. return self._connect_failed("[GoogleChat] subscription.get failed: %s", exc, "subscription_check", retryable=True)
  552. return True
  553. async def connect(self, *, is_reconnect: bool = False) -> bool:
  554. """Validate config, authenticate, start Pub/Sub pull, resolve bot id."""
  555. # connect() is the gate: everything after sees the real google classes.
  556. if not _load_google_modules():
  557. self._set_fatal_error(code="missing_deps", retryable=False,
  558. message="google-cloud-pubsub / google-api-python-client not installed")
  559. return False
  560. self._loop = asyncio.get_running_loop()
  561. self._scope_ctx = contextvars.copy_context() # the profile scope connect() runs under (see __init__)
  562. try:
  563. project_id, subscription_path = self._validate_config()
  564. credentials = self._load_sa_credentials()
  565. except (ValueError, FileNotFoundError) as exc:
  566. return self._connect_failed("[GoogleChat] Config validation failed: %s", exc, "config_invalid", retryable=False)
  567. self._project_id, self._subscription_path, self._credentials = project_id, subscription_path, credentials
  568. try:
  569. self._chat_api = await asyncio.to_thread(
  570. lambda: build_service("chat", "v1", credentials=credentials, cache_discovery=False))
  571. except Exception as exc:
  572. return self._connect_failed("[GoogleChat] Failed to build Chat API client: %s", exc, "chat_api_init", retryable=False)
  573. await self._load_user_oauth()
  574. try:
  575. await asyncio.to_thread(self._thread_count_store.load)
  576. except Exception:
  577. logger.warning("[GoogleChat] thread-count store load failed (treating all threads as fresh)", exc_info=True)
  578. if subscription_path is not None and not await self._check_subscription(subscription_path, credentials):
  579. return False
  580. # Resolve bot user_id (eager): cache first, then members.list.
  581. self._bot_user_id = self._load_cached_bot_id()
  582. if not self._bot_user_id:
  583. self._bot_user_id = await self._resolve_bot_user_id()
  584. if self._bot_user_id:
  585. self._save_cached_bot_id(self._bot_user_id)
  586. else:
  587. logger.info("[GoogleChat] bot_user_id not yet resolved; will resolve on first addedToSpace or member lookup")
  588. self._supervisor_task = asyncio.create_task(self._run_supervisor()) if subscription_path is not None else None
  589. self._mark_connected()
  590. logger.info(
  591. "[GoogleChat] Connected; project=%s, inbound=%s, subscription=%s, "
  592. "bot_user_id=%s, flow_control(msgs=%s, bytes=%s)",
  593. project_id or "<unset>", "pubsub" if subscription_path is not None else "http",
  594. "<redacted>" if subscription_path else "<none>", self._bot_user_id or "<unresolved>",
  595. self._max_messages, self._max_bytes,
  596. )
  597. # Plugin-registered native handlers (ctx.register_platform_handler).
  598. self._wire_plugin_handlers(None)
  599. return True
  600. async def disconnect(self) -> None:
  601. """Clean shutdown: stop accepting new messages, wait in-flight, close clients."""
  602. self._shutting_down = True
  603. if self._supervisor_task and not self._supervisor_task.done():
  604. self._supervisor_task.cancel()
  605. with contextlib.suppress(asyncio.CancelledError, asyncio.TimeoutError):
  606. await asyncio.wait_for(self._supervisor_task, timeout=5.0)
  607. if (future := self._streaming_pull_future) is not None:
  608. with contextlib.suppress(Exception):
  609. future.cancel()
  610. await asyncio.to_thread(future.result, 10.0)
  611. self._streaming_pull_future = None
  612. if (subscriber := self._subscriber) is not None:
  613. with contextlib.suppress(Exception):
  614. await asyncio.to_thread(subscriber.close)
  615. self._subscriber = None
  616. self._mark_disconnected()
  617. logger.info("[GoogleChat] Disconnected")
  618. async def _run_supervisor(self) -> None:
  619. """Run streaming_pull with exponential backoff + full jitter; fatal after N attempts.
  620. ``subscribe()`` returns a Future that resolves when the stream dies."""
  621. pubsub_fatals = {
  622. gax_exceptions.Unauthenticated: (
  623. "pubsub_auth",
  624. "Pub/Sub authentication failed; check service-account credentials and gateway logs",
  625. ),
  626. gax_exceptions.PermissionDenied: ("pubsub_permission", "SA lacks pubsub.subscriber on the subscription"),
  627. }
  628. attempt = 0
  629. while not self._shutting_down:
  630. flow = pubsub_v1.types.FlowControl(max_messages=self._max_messages, max_bytes=self._max_bytes)
  631. try:
  632. self._streaming_pull_future = future = self._subscriber.subscribe(
  633. self._subscription_path, callback=self._on_pubsub_message, flow_control=flow)
  634. if attempt > 0:
  635. logger.info("[GoogleChat] Pub/Sub stream reconnected after %d attempts", attempt)
  636. attempt = 0
  637. # Blocks until stream dies or cancel(); normal completion = disconnect.
  638. await asyncio.to_thread(future.result)
  639. if self._shutting_down:
  640. return
  641. except asyncio.CancelledError:
  642. return
  643. except (gax_exceptions.Unauthenticated, gax_exceptions.PermissionDenied) as exc:
  644. code, message = pubsub_fatals[type(exc)]
  645. self._set_fatal_error(code=code, message=message, retryable=False)
  646. return
  647. except Exception as exc:
  648. attempt += 1
  649. logger.warning("[GoogleChat] Pub/Sub stream died (attempt %d/%d): %s", attempt,
  650. self._MAX_RECONNECT_ATTEMPTS, _redact_sensitive(str(exc)))
  651. if attempt >= self._MAX_RECONNECT_ATTEMPTS:
  652. self._set_fatal_error(
  653. code="pubsub_reconnect_exhausted", message=f"Pub/Sub reconnect failed {attempt} times; giving up",
  654. retryable=False,
  655. )
  656. return
  657. delay = min(self._RECONNECT_MAX_DELAY, self._RECONNECT_BASE_DELAY * (2 ** (attempt - 1)))
  658. try:
  659. await asyncio.sleep(random.uniform(0, delay))
  660. except asyncio.CancelledError:
  661. return
  662. # -- inbound (Pub/Sub callback runs in a thread) -------------------------
  663. @staticmethod
  664. def _extract_message_payload(envelope: dict[str, Any],
  665. ce_type: str = "") -> Optional[tuple[dict[str, Any], dict[str, Any], str]]:
  666. """Return ``(message, space, format_name)`` or None for unknown / non-MESSAGE
  667. envelopes. Formats: Workspace Add-ons ``{"chat": {"messagePayload": ...}}``; native
  668. ``{"type": "MESSAGE", "message", "space"}``; relay/flat ``{"event_type", "sender_email",
  669. "text", ...}`` (a Chat-shaped ``message`` is synthesized)."""
  670. msg_payload_wrapper = (envelope.get("chat") or {}).get("messagePayload")
  671. if msg_payload_wrapper:
  672. msg = msg_payload_wrapper.get("message") or {}
  673. return msg, msg_payload_wrapper.get("space") or msg.get("space") or {}, "workspace_addons"
  674. if isinstance(envelope.get("message"), dict):
  675. if envelope.get("type", "") != "MESSAGE":
  676. return None
  677. msg = envelope["message"]
  678. return msg, envelope.get("space") or msg.get("space") or {}, "native_chat_api"
  679. if "event_type" in envelope or "sender_email" in envelope:
  680. if envelope.get("event_type", "MESSAGE") != "MESSAGE":
  681. return None
  682. sender_email = (envelope.get("sender_email") or "").strip()
  683. text = envelope.get("text", "") or ""
  684. # Honor the relay's ``sender_type`` so the BOT self-filter fires for
  685. # forwarded bot replies; default HUMAN for backward compatibility.
  686. sender_type = str(envelope.get("sender_type") or "HUMAN").strip().upper()
  687. msg: dict[str, Any] = {
  688. "name": envelope.get("message_name", "") or "",
  689. "sender": {
  690. # No Chat resource name for relay events: a stable surrogate keeps dedup/session ids deterministic.
  691. "name": "users/relay-" + (sender_email or "unknown").replace("@", "_at_").replace(".", "_"),
  692. "email": sender_email, "displayName": envelope.get("sender_display_name") or sender_email or "Unknown",
  693. "type": sender_type if sender_type in {"HUMAN", "BOT"} else "HUMAN",
  694. },
  695. "text": text, "argumentText": text,
  696. }
  697. if envelope.get("thread_name"):
  698. msg["thread"] = {"name": envelope["thread_name"]}
  699. space = {"name": envelope.get("space_name", "") or "", "spaceType": envelope.get("space_type", "SPACE")}
  700. return msg, space, "relay_flat"
  701. return None
  702. def _prepare_inbound(self, envelope: dict[str, Any],
  703. ce_type: Optional[str] = None) -> Optional[tuple[dict[str, Any], dict[str, Any]]]:
  704. """Extract + self-filter + dedup an inbound envelope. Returns ``(msg_with_space,
  705. enriched_envelope)`` for ``_dispatch_message``, or None when the event must be
  706. dropped. Debug logs only on the Pub/Sub path (``ce_type`` given)."""
  707. extracted = self._extract_message_payload(envelope, ce_type or "")
  708. if extracted is None:
  709. if ce_type is not None:
  710. logger.debug(
  711. "[GoogleChat] Envelope did not match a known message format; ce-type=%s, keys=%s",
  712. ce_type, list(envelope.keys()),
  713. )
  714. return None
  715. msg, space, _fmt = extracted
  716. # Self-filter: drop bot-sourced messages (own replies and other bots).
  717. if (msg.get("sender") or {}).get("type") == "BOT":
  718. return None
  719. # Dedup guard — Pub/Sub is at-least-once.
  720. msg_name = msg.get("name") or ""
  721. if msg_name and self._dedup.is_duplicate(msg_name):
  722. if ce_type is not None:
  723. logger.debug("[GoogleChat] Dedup drop for %s", msg_name)
  724. return None
  725. # Give both dicts a top-level "space" so the dispatch side has one shape.
  726. msg_with_space, enriched_env = dict(msg), dict(envelope)
  727. for d in (msg_with_space, enriched_env):
  728. if "space" not in d and space:
  729. d["space"] = space
  730. return msg_with_space, enriched_env
  731. def _on_pubsub_message(self, message: Any) -> None:
  732. """Pub/Sub callback — parse envelope and dispatch to the asyncio loop.
  733. Runs in a SubscriberClient worker thread: never block, never raise (that
  734. triggers nack + infinite redelivery). Event type comes from ``ce-type``. The body runs under
  735. the adapter's profile scope (a per-callback copy: a Context cannot be entered concurrently) so
  736. ``_save_cached_bot_id`` and the loop hand-off resolve the served profile, not the launch one."""
  737. ctx = self._scope_ctx.copy() if self._scope_ctx is not None else contextvars.copy_context()
  738. ctx.run(self._handle_pubsub_message, message)
  739. def _handle_pubsub_message(self, message: Any) -> None:
  740. if self._shutting_down:
  741. message.nack()
  742. return
  743. try:
  744. envelope = json.loads(message.data.decode("utf-8"))
  745. except Exception:
  746. logger.exception("[GoogleChat] Could not parse Pub/Sub envelope")
  747. message.ack()
  748. return
  749. ce_type = dict(getattr(message, "attributes", {}) or {}).get("ce-type") or ""
  750. logger.debug("[GoogleChat] Envelope keys=%s, ce-type=%s", list(envelope.keys()), ce_type)
  751. if self._debug_raw:
  752. # Contains message text + sender email: redact and gate at DEBUG.
  753. try:
  754. from agent.redact import redact_sensitive_text
  755. dump = redact_sensitive_text(json.dumps(envelope))
  756. except Exception:
  757. dump = "<redact filter unavailable>"
  758. logger.debug("[GoogleChat] RAW envelope (redacted): %s", dump[:2000])
  759. try:
  760. if "membership" in ce_type or "MEMBERSHIP" in ce_type:
  761. mpl = (envelope.get("chat") or {}).get("membershipPayload") or {}
  762. space = mpl.get("space") or {}
  763. if "created" in ce_type:
  764. # ADDED_TO_SPACE for this bot — resolve self user_id.
  765. member = (mpl.get("membership") or {}).get("member") or {}
  766. if member.get("type") == "BOT" and not self._bot_user_id and member.get("name"):
  767. self._bot_user_id = member["name"]
  768. self._save_cached_bot_id(member["name"])
  769. logger.info("[GoogleChat] ADDED_TO_SPACE %s", space.get("name", "?"))
  770. else:
  771. logger.info("[GoogleChat] REMOVED_FROM_SPACE %s", space.get("name", "?"))
  772. elif "widget" in ce_type or "card" in ce_type.lower():
  773. logger.info("[GoogleChat] Card/widget event ack'd (v2 feature, deferred)")
  774. else:
  775. prepared = self._prepare_inbound(envelope, ce_type)
  776. if prepared is not None:
  777. self._submit_on_loop(self._dispatch_message(*prepared))
  778. message.ack()
  779. except Exception:
  780. logger.exception("[GoogleChat] Error in _on_pubsub_message")
  781. with contextlib.suppress(Exception):
  782. message.ack()
  783. async def dispatch_http_event(self, envelope: dict[str, Any]) -> dict[str, Any]:
  784. from gateway.parked_route_refusal import ParkedRouteRefused, retryable_ingress
  785. prepared = self._prepare_inbound(envelope)
  786. if prepared is None:
  787. return {}
  788. # The callback answers after this dispatch, so the delivery is not acknowledged yet: a route
  789. # to a parked profile is answered retryably (Google redelivers a non-2xx), not refused in chat.
  790. with retryable_ingress() as scope:
  791. await self._dispatch_message(*prepared)
  792. if scope.refused:
  793. self._release_unadmitted(*prepared)
  794. raise ParkedRouteRefused()
  795. return {}
  796. def _release_unadmitted(self, msg: dict[str, Any], envelope: dict[str, Any]) -> None:
  797. """Undo what ingress recorded for a delivery that was not admitted (its dedup claim and DM
  798. thread count), so the platform's redelivery is admitted and read as the first delivery."""
  799. self._dedup.discard(msg.get("name") or "")
  800. space_name = (envelope.get("space") or msg.get("space") or {}).get("name") or ""
  801. thread_name = (msg.get("thread") or {}).get("name") or ""
  802. if space_name and thread_name:
  803. self._thread_count_store.decr(space_name, thread_name)
  804. def verify_http_event_request(self, auth_header: str) -> tuple[bool, str]:
  805. if not self._http_events_audience or not self._http_events_service_account_email:
  806. return False, "google_chat_http_events_not_configured"
  807. token = auth_header[7:].strip() if auth_header.startswith("Bearer ") else ""
  808. if not token:
  809. return False, "missing_google_bearer"
  810. try:
  811. claims = _verify_google_id_token(token, self._http_events_audience)
  812. except Exception as exc:
  813. logger.warning("[GoogleChat] HTTP event bearer verification failed: %s", _redact_sensitive(str(exc)))
  814. return False, "invalid_google_bearer"
  815. expected = {item.strip().lower() for item in self._http_events_service_account_email.split(",") if item.strip()}
  816. if str(claims.get("email") or "").strip().lower() not in expected:
  817. return False, "unexpected_google_bearer_identity"
  818. return True, ""
  819. async def _dispatch_message(self, msg: dict[str, Any], envelope: dict[str, Any]) -> None:
  820. """Translate a Chat message to a MessageEvent and hand off.
  821. ``/setup-files`` is intercepted BEFORE the agent sees it (bot-local OAuth flow)."""
  822. try:
  823. event = await self._build_message_event(msg, envelope)
  824. if event is None:
  825. return
  826. text = (event.text or "").strip()
  827. # The sender email (user_id_alt) is the per-user OAuth token key.
  828. if text.startswith("/setup-files") and event.source is not None and await self._handle_setup_files_command(
  829. chat_id=event.source.chat_id, thread_id=event.source.thread_id, raw_text=text,
  830. sender_email=event.source.user_id_alt or None,
  831. ):
  832. return
  833. await self.handle_message(event)
  834. except Exception:
  835. logger.exception("[GoogleChat] _dispatch_message failed")
  836. async def _handle_setup_files_command(self, chat_id: str, thread_id: Optional[str], raw_text: str,
  837. sender_email: Optional[str] = None) -> bool:
  838. """In-chat OAuth setup flow; see ``setup_files.handle_setup_files_command``."""
  839. from .setup_files import handle_setup_files_command
  840. return await handle_setup_files_command(self, chat_id, thread_id, raw_text, sender_email)
  841. async def _build_message_event(self, msg: dict[str, Any], envelope: dict[str, Any]) -> Optional[MessageEvent]:
  842. """Parse a Chat API message into a hermes MessageEvent."""
  843. space = envelope.get("space") or msg.get("space") or {}
  844. space_name = space.get("name") or "" # "spaces/XXX"
  845. space_type = (space.get("type") or space.get("spaceType") or "").upper()
  846. thread_name = (msg.get("thread") or {}).get("name") or None
  847. sender = msg.get("sender") or {}
  848. sender_name = sender.get("name") or ""
  849. sender_email = sender.get("email") or ""
  850. # Cache the asker's email per space so _send_file picks the right per-user
  851. # OAuth token (lower-cased to match the sanitized token-file lookup).
  852. if sender_email and space_name:
  853. self._last_sender_by_chat[space_name] = sender_email.strip().lower()
  854. chat_type = "dm" if space_type in {"DIRECT_MESSAGE", "DM"} else "group"
  855. text = (msg.get("argumentText") or msg.get("text") or "").strip()
  856. # Slash command: emit MessageType.COMMAND with normalized text.
  857. slash = msg.get("slashCommand") or {}
  858. if slash:
  859. command_id = str(slash.get("commandId") or "")
  860. if command_id and not text.startswith("/"):
  861. text = f"/cmd_{command_id} {text}".strip()
  862. media_urls: list[str] = []
  863. media_types: list[str] = []
  864. message_type = MessageType.TEXT
  865. for att in msg.get("attachment") or []:
  866. try:
  867. local_path, mime = await self._download_attachment(att)
  868. except Exception:
  869. logger.exception("[GoogleChat] attachment download failed")
  870. continue
  871. if not local_path:
  872. continue
  873. media_urls.append(local_path)
  874. media_types.append(mime or "application/octet-stream")
  875. # Prefer the first-seen type for MessageType if no text present.
  876. if message_type == MessageType.TEXT and not text:
  877. message_type = _mime_for_message_type(mime or "")
  878. if slash:
  879. message_type = MessageType.COMMAND
  880. # PRE-increment count (persisted) drives the main-flow-vs-side-thread heuristic.
  881. prev_thread_count = self._thread_count_store.incr(space_name, thread_name) if thread_name and space_name else 0
  882. # DMs: prev_count == 0 → Chat auto-created this thread for a top-level message: share one
  883. # DM session, reply top-level (thread.name would render an expandable thread); >= 1 → user
  884. # engaged an existing thread: isolate + reply in-thread. Groups: always isolate + in-thread.
  885. if chat_type == "dm":
  886. is_side_thread = prev_thread_count > 0
  887. session_thread_id = thread_name if is_side_thread else None
  888. # Outbound cache only for side-threads so main-flow replies land top-level.
  889. if thread_name and space_name and is_side_thread:
  890. self._last_inbound_thread[space_name] = thread_name
  891. elif space_name:
  892. self._last_inbound_thread.pop(space_name, None)
  893. else:
  894. session_thread_id = thread_name
  895. if thread_name and space_name:
  896. self._last_inbound_thread[space_name] = thread_name
  897. source = self.build_source(
  898. chat_id=space_name, chat_name=space.get("displayName") or space.get("name") or "", chat_type=chat_type,
  899. # Email is the canonical id (allowlists use emails); the ``users/{id}``
  900. # resource name moves to user_id_alt.
  901. user_id=(sender_email or sender_name), user_name=sender.get("displayName") or sender_email or sender_name,
  902. thread_id=session_thread_id, user_id_alt=(sender_name or None), message_id=msg.get("name") or None,
  903. )
  904. return MessageEvent(
  905. text=text, message_type=message_type, source=source, raw_message=msg, message_id=msg.get("name") or None,
  906. media_urls=media_urls, media_types=media_types,
  907. )
  908. async def _download_attachment(self, attachment: dict[str, Any]) -> tuple[Optional[str], Optional[str]]:
  909. """Download an inbound attachment to the local cache; return (path, mime). Bot SA
  910. path is ``media.download`` via ``attachmentDataRef.resourceName``; Drive-picker shares
  911. without one need user OAuth (skipped); ``downloadUri`` is a last resort (usually 401s)."""
  912. mime = attachment.get("contentType") or ""
  913. name = attachment.get("name") or ""
  914. resource_name = (attachment.get("attachmentDataRef") or {}).get("resourceName") or ""
  915. download_uri = attachment.get("downloadUri") or ""
  916. # Chat tags BOTH drag-and-drop uploads AND Drive-picker shares as DRIVE_FILE;
  917. # only the former carry a resourceName the bot path can use.
  918. if (attachment.get("source") or "") == "DRIVE_FILE" and not resource_name:
  919. logger.info("[GoogleChat] Skipping Drive-picker attachment (no resourceName, would need user-OAuth Drive scope)")
  920. return None, mime
  921. data: Optional[bytes] = None
  922. if resource_name:
  923. def _fetch_media() -> bytes:
  924. req = self._chat_api.media().download_media(resourceName=resource_name)
  925. from googleapiclient.http import MediaIoBaseDownload
  926. import io
  927. buf = io.BytesIO()
  928. downloader, done = MediaIoBaseDownload(buf, req), False
  929. while not done:
  930. _status, done = downloader.next_chunk()
  931. return buf.getvalue()
  932. try:
  933. data = await asyncio.to_thread(_fetch_media)
  934. except HttpError as exc:
  935. logger.warning("[GoogleChat] media.download_media failed: %s", _redact_sensitive(str(exc)))
  936. if data is None and download_uri:
  937. if not _is_google_owned_host(download_uri):
  938. logger.warning("[GoogleChat] Rejecting attachment fetch: non-Google host")
  939. return None, mime
  940. def _fetch_uri() -> bytes:
  941. import google.auth.transport.requests as gar
  942. resp = gar.AuthorizedSession(self._credentials).get(download_uri, timeout=30)
  943. resp.raise_for_status()
  944. return resp.content
  945. try:
  946. data = await asyncio.to_thread(_fetch_uri)
  947. except Exception as exc:
  948. logger.warning(
  949. "[GoogleChat] downloadUri fetch failed (SA tokens often lack access here; this is expected for "
  950. "user-uploaded content): %s", _redact_sensitive(str(exc)),
  951. )
  952. return None, mime
  953. if data is None:
  954. return None, mime
  955. # cache_* helpers take ``ext`` for media and a positional filename for docs.
  956. filename = name.split("/")[-1] if name else "attachment"
  957. ext = "." + filename.rsplit(".", 1)[-1].lower() if "." in filename else ""
  958. for prefix, cache_fn, default_ext in _MEDIA_CACHERS:
  959. if mime.startswith(prefix):
  960. return await cache_fn(data, ext=ext or default_ext), mime
  961. return await cache_document_from_bytes_async(data, filename), mime
  962. # -- outbound ------------------------------------------------------------
  963. def _note_rate_limit(self, chat_id: str) -> int:
  964. self._rate_limit_hits[chat_id] = self._rate_limit_hits.get(chat_id, 0) + 1
  965. return self._rate_limit_hits[chat_id]
  966. async def send(self, chat_id: str, content: str, reply_to: Optional[str] = None,
  967. metadata: Optional[dict[str, Any]] = None) -> SendResult:
  968. """Send a text message; ``metadata`` may carry ``thread_id``. A tracked typing card is
  969. patched in place (delete would leave a "Message deleted" tombstone) with the first
  970. chunk, further chunks are new messages; ``_keep_typing`` is paused meanwhile."""
  971. thread_id = self._resolve_thread_id(reply_to, metadata, chat_id=chat_id)
  972. self.pause_typing_for_chat(chat_id)
  973. try:
  974. # Format BEFORE chunking so the size limit applies to the rendered form.
  975. chunks = self._chunk_text(self.format_message(content))
  976. if not chunks:
  977. return SendResult(success=False, error="empty message")
  978. last_result: Optional[SendResult] = None
  979. typing_msg_name = self._typing_messages.pop(chat_id, None)
  980. if typing_msg_name == _TYPING_CONSUMED_SENTINEL:
  981. typing_msg_name = None
  982. patched_typing = False
  983. for idx, chunk in enumerate(chunks):
  984. # Only set thread on the create path; patch inherits.
  985. body = _thread_body(chunk, thread_id if (idx > 0 or not typing_msg_name) else None)
  986. try:
  987. if idx == 0 and typing_msg_name:
  988. last_result = await self._patch_message(typing_msg_name, body)
  989. patched_typing = True
  990. else:
  991. last_result = await self._create_message(chat_id, body)
  992. except HttpError as exc:
  993. status = _http_status(exc)
  994. if status == 403:
  995. self._set_fatal_error(
  996. code="chat_forbidden", message="Bot lacks access (removed from space or perms revoked)",
  997. retryable=False,
  998. )
  999. return SendResult(success=False, error=str(exc))
  1000. if status == 404:
  1001. # Typing card deleted under us: fall back to a fresh message.
  1002. if idx == 0 and typing_msg_name:
  1003. logger.info("[GoogleChat] Typing card disappeared; creating new message")
  1004. typing_msg_name = None
  1005. last_result = await self._create_message(chat_id, body)
  1006. continue
  1007. logger.info("[GoogleChat] send target 404; skipping")
  1008. return SendResult(success=False, error="target not found")
  1009. if status == 429:
  1010. hits = self._note_rate_limit(chat_id)
  1011. if hits >= _RATE_LIMIT_WARN_THRESHOLD:
  1012. logger.warning("[GoogleChat] Rate limit hit %d times on chat; throttling", hits)
  1013. raise
  1014. if last_result is None:
  1015. return SendResult(success=False, error="empty message")
  1016. # Sentinel keeps a trailing _keep_typing tick from posting a fresh marker that
  1017. # stop_typing would then delete and tombstone. Cleared in on_processing_complete.
  1018. if patched_typing:
  1019. self._typing_messages[chat_id] = _TYPING_CONSUMED_SENTINEL
  1020. return last_result
  1021. finally:
  1022. self.resume_typing_for_chat(chat_id)
  1023. async def send_card(self, chat_id: str, card: dict[str, Any], metadata: Optional[dict[str, Any]] = None) -> SendResult:
  1024. body: dict[str, Any] = {"cardsV2": [card]}
  1025. thread_id = self._resolve_thread_id(None, metadata, chat_id=chat_id)
  1026. if thread_id:
  1027. body["thread"] = {"name": thread_id}
  1028. try:
  1029. result = await self._create_message(chat_id, body)
  1030. result.raw_response = result.raw_response or {"cardsV2": body["cardsV2"]}
  1031. return result
  1032. except HttpError as exc:
  1033. return SendResult(
  1034. success=False, error=_redact_sensitive(str(exc)), retryable=_http_status(exc) in _RETRYABLE_HTTP_STATUSES)
  1035. except Exception as exc:
  1036. logger.debug("[GoogleChat] send_card failed", exc_info=True)
  1037. return SendResult(success=False, error=_redact_sensitive(str(exc)), retryable=_is_retryable_error(exc))
  1038. async def send_clarify(
  1039. self, chat_id: str, question: str, choices: Optional[list], clarify_id: str, session_key: str,
  1040. metadata: Optional[dict[str, Any]] = None,
  1041. ) -> SendResult:
  1042. if not choices:
  1043. return await super().send_clarify(chat_id, question, choices, clarify_id, session_key, metadata)
  1044. def _button(text: str, choice: str) -> dict[str, Any]:
  1045. return {"text": text, "action": "hermes_clarify", "parameters": {"clarify_id": clarify_id, "choice": choice}}
  1046. buttons: list[dict[str, Any]] = []
  1047. for choice in choices:
  1048. choice_text = str(choice).strip()
  1049. if choice_text:
  1050. buttons.append(_button(choice_text if len(choice_text) <= 80 else choice_text[:77] + "...", choice_text))
  1051. buttons.append(_button(t("platform.google_chat.clarify.other_button"), "__other__"))
  1052. card = card_spec_to_cards_v2({
  1053. "card_id": f"clarify-{clarify_id}", "header": {"title": t("platform.google_chat.clarify.header")},
  1054. "sections": [{"widgets": [{"type": "text", "text": t("platform.google_chat.clarify.question", question=question)},
  1055. {"type": "buttons", "buttons": buttons}]}],
  1056. })
  1057. result = await self.send_card(chat_id, card, metadata=metadata)
  1058. if result.success:
  1059. self._clarify_state[clarify_id] = session_key
  1060. return result
  1061. return await super().send_clarify(chat_id, question, choices, clarify_id, session_key, metadata)
  1062. async def edit_message(self, chat_id: str, message_id: str, content: str, *, finalize: bool = False) -> SendResult:
  1063. """Edit via ``messages.patch`` (required by the tool-progress / token-streaming
  1064. pipeline). ``finalize`` is unused: Chat's patch has no streaming lifecycle.
  1065. 404/403 are non-success so the gateway falls back to ``send()``."""
  1066. if not message_id:
  1067. return SendResult(success=False, error="missing message_id")
  1068. if len(content) > _MAX_TEXT_LENGTH:
  1069. content = content[: _MAX_TEXT_LENGTH - 1] + "…"
  1070. try:
  1071. return await self._patch_message(message_id, {"text": content})
  1072. except HttpError as exc:
  1073. if _http_status(exc) == 429:
  1074. self._note_rate_limit(chat_id)
  1075. return SendResult(success=False, error=_redact_sensitive(str(exc)))
  1076. except Exception as exc:
  1077. logger.debug("[GoogleChat] edit_message failed", exc_info=True)
  1078. return SendResult(success=False, error=str(exc))
  1079. async def delete_message(self, chat_id: str, message_id: str) -> bool:
  1080. """Delete a message. Prefer ``edit_message`` — deletion leaves a "Message
  1081. deleted by its author" tombstone; kept for stream-consumer fallback paths."""
  1082. if not message_id:
  1083. return False
  1084. try:
  1085. await asyncio.to_thread(
  1086. lambda: self._chat_api.spaces().messages().delete(name=message_id).execute(http=self._new_authed_http()))
  1087. return True
  1088. except HttpError as exc:
  1089. if _http_status(exc) not in {403, 404}:
  1090. logger.debug("[GoogleChat] delete_message failed: %s", _redact_sensitive(str(exc)))
  1091. except Exception:
  1092. logger.debug("[GoogleChat] delete_message failed", exc_info=True)
  1093. return False
  1094. async def _patch_message(self, message_name: str, body: dict[str, Any]) -> SendResult:
  1095. """Update a message's text (and optionally cards) in-place."""
  1096. update_mask = ",".join(k for k in ("text", "cardsV2") if k in body) or "text"
  1097. patch_body = {k: v for k, v in body.items() if k != "thread"} # thread is immutable
  1098. resp = await asyncio.to_thread(
  1099. lambda: self._chat_api.spaces().messages().patch(name=message_name, updateMask=update_mask, body=patch_body)
  1100. .execute(http=self._new_authed_http())
  1101. )
  1102. return SendResult(success=True, message_id=resp.get("name", message_name))
  1103. def _chunk_text(self, text: str) -> list[str]:
  1104. chunks: list[str] = []
  1105. remaining = text
  1106. while remaining:
  1107. if len(remaining) <= _MAX_TEXT_LENGTH:
  1108. chunks.append(remaining)
  1109. break
  1110. # Split on a newline near the cutoff when one exists past the midpoint.
  1111. cut = remaining.rfind("\n", 0, _MAX_TEXT_LENGTH)
  1112. if cut < _MAX_TEXT_LENGTH // 2:
  1113. cut = _MAX_TEXT_LENGTH
  1114. chunks.append(remaining[:cut])
  1115. remaining = remaining[cut:].lstrip()
  1116. return chunks
  1117. @classmethod
  1118. def format_message(cls, content: str) -> str:
  1119. """Convert standard Markdown to Google Chat's dialect (see ``cards.format_message``).
  1120. Pattern lifted from PR #14965.
  1121. """
  1122. return _format_message(content)
  1123. def _resolve_thread_id(self, reply_to: Optional[str], metadata: Optional[dict[str, Any]],
  1124. chat_id: Optional[str] = None) -> Optional[str]:
  1125. """Thread to reply under, or None: ``metadata['thread_id']`` → ``thread_name`` /
  1126. ``thread_ts`` aliases → ``reply_to`` when already a ``spaces/X/threads/Y`` name →
  1127. ``_last_inbound_thread[chat_id]`` (else DM replies land top-level). Cron deliveries
  1128. (``job_id`` in metadata) skip the last fallback so output is not buried in a stale thread."""
  1129. if metadata:
  1130. for key in ("thread_id", "thread_name", "thread_ts"):
  1131. if metadata.get(key):
  1132. return str(metadata[key])
  1133. if reply_to and "/threads/" in reply_to and "/messages/" not in reply_to:
  1134. return reply_to
  1135. if metadata and metadata.get("job_id"):
  1136. return None
  1137. return (self._last_inbound_thread.get(chat_id) or None) if chat_id else None
  1138. def _new_authed_http(self) -> Any:
  1139. """Fresh AuthorizedHttp per call: httplib2 shares SSL state, so the discovery
  1140. client is not thread-safe across ``asyncio.to_thread`` workers."""
  1141. return AuthorizedHttp(self._credentials, http=httplib2.Http(timeout=30))
  1142. async def _call_with_retry(self, sync_fn: Callable[[], Any], *, op_name: str = "chat-api-call") -> Any:
  1143. """Run ``sync_fn`` in a thread with bounded retry + jittered backoff; only
  1144. transient failures are retried, permanent ones bubble up on the first attempt.
  1145. Pattern lifted from PR #14965.
  1146. """
  1147. delay = _RETRY_BASE_DELAY
  1148. for attempt in range(1, _RETRY_MAX_ATTEMPTS + 1):
  1149. try:
  1150. return await asyncio.to_thread(sync_fn)
  1151. except Exception as exc:
  1152. if not _is_retryable_error(exc) or attempt >= _RETRY_MAX_ATTEMPTS:
  1153. raise
  1154. wait = min(delay + delay * _RETRY_JITTER * random.random(), _RETRY_MAX_DELAY + _RETRY_JITTER)
  1155. logger.warning(
  1156. "[GoogleChat] %s attempt %d/%d failed (%s); retrying in %.2fs",
  1157. op_name, attempt, _RETRY_MAX_ATTEMPTS, _redact_sensitive(str(exc)), wait,
  1158. )
  1159. await asyncio.sleep(wait)
  1160. delay = min(delay * 2, _RETRY_MAX_DELAY)
  1161. def _track_outbound_thread(self, chat_id: str, resp: dict[str, Any]) -> None:
  1162. """Count the outbound destination thread so a later user "Reply in thread" on
  1163. the bot's message resolves as a known side-thread instead of main flow."""
  1164. resp_thread = (resp.get("thread") or {}).get("name") or ""
  1165. if chat_id and resp_thread:
  1166. try:
  1167. self._thread_count_store.incr(chat_id, resp_thread)
  1168. except Exception:
  1169. logger.debug("[GoogleChat] outbound thread-count incr failed", exc_info=True)
  1170. async def _create_message(self, chat_id: str, body: dict[str, Any]) -> SendResult:
  1171. """POST spaces/{space}/messages via REST (with retry), returning SendResult."""
  1172. kwargs = _create_kwargs(chat_id, body)
  1173. resp = await self._call_with_retry(
  1174. lambda: self._chat_api.spaces().messages().create(**kwargs).execute(http=self._new_authed_http()),
  1175. op_name="messages.create",
  1176. )
  1177. self._track_outbound_thread(chat_id, resp)
  1178. return SendResult(success=True, message_id=resp.get("name"))
  1179. async def send_typing(self, chat_id: str, metadata: Any = None) -> None:
  1180. """Post a visible 'Hermes is thinking…' marker (Chat has no typing API); ``send()``
  1181. PATCHes it with the reply, ``on_processing_complete`` reaps it otherwise. Created in
  1182. the user's thread (patch cannot move it). ``_keep_typing`` wraps this in
  1183. ``wait_for(timeout=1.5)``: a cancelled create would still land an unrecorded card and
  1184. the next tick would create a second, so the slot is reserved with an in-flight Event
  1185. and the create runs in a shielded task that records the msg_id regardless."""
  1186. # Already have a card (real msg_id, sentinel, or in-flight) — bail.
  1187. if chat_id in self._typing_messages:
  1188. return
  1189. if chat_id in self._typing_card_inflight:
  1190. # Bounded wait for the running create so "the card is up when we return".
  1191. with contextlib.suppress(asyncio.TimeoutError, KeyError):
  1192. await asyncio.wait_for(self._typing_card_inflight[chat_id].wait(), timeout=5.0)
  1193. return
  1194. thread_id = self._resolve_thread_id(reply_to=None, metadata=metadata, chat_id=chat_id)
  1195. body = _thread_body(getattr(self.config, "typing_status_text", None) or t("platform.google_chat.typing.thinking"), thread_id)
  1196. self._typing_card_inflight[chat_id] = completed = asyncio.Event()
  1197. async def _create_and_record() -> None:
  1198. try:
  1199. result = await self._create_message(chat_id, body)
  1200. if result.success and result.message_id:
  1201. if chat_id not in self._typing_messages:
  1202. self._typing_messages[chat_id] = result.message_id
  1203. else:
  1204. # send() or another create claimed the slot first: orphan;
  1205. # on_processing_complete cleans it up.
  1206. self._orphan_typing_messages.setdefault(chat_id, []).append(result.message_id)
  1207. except Exception:
  1208. logger.debug("[GoogleChat] send_typing background create failed", exc_info=True)
  1209. finally:
  1210. self._typing_card_inflight.pop(chat_id, None)
  1211. completed.set()
  1212. # The shielded task keeps running if our awaiter is cancelled.
  1213. await asyncio.shield(asyncio.create_task(_create_and_record()))
  1214. async def stop_typing(self, chat_id: str) -> None:
  1215. """NO-OP for a live card: upstream calls ``stop_typing`` BEFORE ``send()`` patches it
  1216. (deleting would tombstone). Only the SENTINEL is popped so the next turn starts clean;
  1217. stranded cards are reaped by ``on_processing_complete``."""
  1218. if self._typing_messages.get(chat_id) == _TYPING_CONSUMED_SENTINEL:
  1219. self._typing_messages.pop(chat_id, None)
  1220. async def _patch_quietly(self, message_name: str, text: str, log_msg: str, *log_args: Any) -> None:
  1221. try:
  1222. await self._patch_message(message_name, {"text": text})
  1223. except Exception:
  1224. logger.debug(log_msg, *log_args, exc_info=True)
  1225. async def on_processing_complete(self, event: MessageEvent, outcome: ProcessingOutcome) -> None:
  1226. """Reap typing card(s) after the turn: pop the SENTINEL on success; on
  1227. failure/cancel patch a still-tracked card to a final label (no tombstone);
  1228. patch orphan cards (background creates that lost a race with send()) to "·"."""
  1229. if event.source is None:
  1230. return
  1231. chat_id = event.source.chat_id
  1232. try:
  1233. current = self._typing_messages.pop(chat_id, None)
  1234. if current and current != _TYPING_CONSUMED_SENTINEL:
  1235. label = t("platform.google_chat.typing.interrupted" if outcome == ProcessingOutcome.CANCELLED
  1236. else "platform.google_chat.typing.no_reply")
  1237. await self._patch_quietly(current, label, "[GoogleChat] on_processing_complete patch fallback failed")
  1238. for orphan_id in self._orphan_typing_messages.pop(chat_id, []):
  1239. await self._patch_quietly(orphan_id, "·", "[GoogleChat] orphan typing-card patch failed: %s", orphan_id)
  1240. except Exception:
  1241. logger.debug("[GoogleChat] cleanup in on_processing_complete failed", exc_info=True)
  1242. # -- attachments ---------------------------------------------------------
  1243. async def _consume_typing_card_with_text(self, chat_id: str, text: str) -> Optional[SendResult]:
  1244. """Patch the tracked typing card with ``text`` (no tombstone); None when there is no
  1245. real card (caller creates a message) — the SENTINEL stays so ``_keep_typing`` doesn't
  1246. post a fresh card during a subsequent attachment send. Raises transient HttpErrors."""
  1247. current = self._typing_messages.get(chat_id)
  1248. if not current or current == _TYPING_CONSUMED_SENTINEL:
  1249. return None
  1250. self._typing_messages.pop(chat_id, None)
  1251. try:
  1252. result = await self._patch_message(current, {"text": text})
  1253. self._typing_messages[chat_id] = _TYPING_CONSUMED_SENTINEL
  1254. return result
  1255. except HttpError as exc:
  1256. if _http_status(exc) == 404:
  1257. return None # card disappeared — caller creates a new message
  1258. raise
  1259. async def send_image(
  1260. self, chat_id: str, image_url: str, caption: Optional[str] = None, reply_to: Optional[str] = None,
  1261. metadata: Optional[dict[str, Any]] = None,
  1262. ) -> SendResult:
  1263. """Send an inline image via URL (no upload); patches the typing card when tracked."""
  1264. thread_id = self._resolve_thread_id(reply_to, metadata, chat_id=chat_id)
  1265. text = "\n".join(([caption] if caption else []) + [image_url])
  1266. try:
  1267. patched = await self._consume_typing_card_with_text(chat_id, text)
  1268. if patched is not None:
  1269. return patched
  1270. return await self._create_message(chat_id, _thread_body(text, thread_id))
  1271. except HttpError as exc:
  1272. return SendResult(success=False, error=_redact_sensitive(str(exc)))
  1273. async def _send_file_reply(
  1274. self, chat_id: str, path: str, caption: Optional[str], reply_to: Optional[str], kwargs: dict[str, Any],
  1275. mime_hint: Optional[str], override_filename: Optional[str] = None,
  1276. ) -> SendResult:
  1277. thread_id = self._resolve_thread_id(reply_to, kwargs.get("metadata"), chat_id=chat_id)
  1278. return await self._send_file(
  1279. chat_id, path, caption, mime_hint=mime_hint, thread_id=thread_id, override_filename=override_filename)
  1280. async def send_image_file(self, chat_id: str, image_path: str, caption: Optional[str] = None,
  1281. reply_to: Optional[str] = None, **kwargs: Any) -> SendResult:
  1282. return await self._send_file_reply(chat_id, image_path, caption, reply_to, kwargs, "image/*")
  1283. async def send_document(
  1284. self, chat_id: str, file_path: str, caption: Optional[str] = None, file_name: Optional[str] = None,
  1285. reply_to: Optional[str] = None, **kwargs: Any,
  1286. ) -> SendResult:
  1287. return await self._send_file_reply(chat_id, file_path, caption, reply_to, kwargs, None, file_name)
  1288. async def send_voice(self, chat_id: str, audio_path: str, caption: Optional[str] = None,
  1289. reply_to: Optional[str] = None, **kwargs: Any) -> SendResult:
  1290. return await self._send_file_reply(chat_id, audio_path, caption, reply_to, kwargs, "audio/ogg")
  1291. async def send_video(self, chat_id: str, video_path: str, caption: Optional[str] = None,
  1292. reply_to: Optional[str] = None, **kwargs: Any) -> SendResult:
  1293. return await self._send_file_reply(chat_id, video_path, caption, reply_to, kwargs, "video/mp4")
  1294. async def send_animation(
  1295. self, chat_id: str, animation_url: str, caption: Optional[str] = None, reply_to: Optional[str] = None,
  1296. metadata: Optional[dict[str, Any]] = None,
  1297. ) -> SendResult:
  1298. """Google Chat has no native animation type; fall back to send_image."""
  1299. return await self.send_image(chat_id, animation_url, caption=caption, reply_to=reply_to, metadata=metadata)
  1300. # -- native attachment delivery via user OAuth: media.upload hard-rejects SA
  1301. # auth, so the user grants chat.messages.create ONCE via ``/setup-files`` and
  1302. # the bot uploads AS the user (see ``oauth.py``). --------------------------
  1303. @staticmethod
  1304. async def _refresh_or_none(creds: Any, email: Optional[str], log_msg: str) -> Optional[Any]:
  1305. """``oauth.refresh_or_none`` in a thread; a raise is logged at DEBUG and treated as None."""
  1306. from .oauth import refresh_or_none as _refresh
  1307. try:
  1308. return await asyncio.to_thread(_refresh, creds, email)
  1309. except Exception:
  1310. logger.debug(log_msg, exc_info=True)
  1311. return None
  1312. async def _load_per_user_chat_api(self, email: str) -> Optional[Any]:
  1313. """Get (or build + cache) a user-authed Chat client for ``email``.
  1314. Cache hit → refresh creds (evict on failure so the next request goes back
  1315. through disk / the text-notice fallback). Miss → load token, build, cache."""
  1316. from .oauth import load_user_credentials as _load, build_user_chat_service as _build
  1317. cached_api = self._user_chat_api_by_email.get(email)
  1318. cached_creds = self._user_creds_by_email.get(email)
  1319. if cached_api is not None and cached_creds is not None:
  1320. refreshed = await self._refresh_or_none(cached_creds, email, "[GoogleChat] cached per-user refresh raised")
  1321. if refreshed is None:
  1322. self._invalidate_user_creds(email)
  1323. return None
  1324. self._user_creds_by_email[email] = refreshed
  1325. return cached_api
  1326. try:
  1327. creds = await asyncio.to_thread(_load, email)
  1328. if creds is None:
  1329. return None
  1330. api = await asyncio.to_thread(lambda: _build(creds))
  1331. except Exception:
  1332. logger.debug("[GoogleChat] per-user creds load/build failed for %s", email, exc_info=True)
  1333. return None
  1334. self._user_creds_by_email[email] = creds
  1335. self._user_chat_api_by_email[email] = api
  1336. return api
  1337. async def _acquire_user_chat_api(self, sender_email: Optional[str]) -> tuple[Optional[Any], Optional[str]]:
  1338. """User-authed Chat client for an outbound attachment: per-user token for
  1339. ``sender_email`` → legacy single-user fallback → ``(None, None)`` (caller posts the
  1340. setup notice). The identity label (email / ``"__legacy__"``) selects the slot to evict."""
  1341. if sender_email:
  1342. api = await self._load_per_user_chat_api(sender_email)
  1343. if api is not None:
  1344. return api, sender_email
  1345. if self._user_chat_api is not None:
  1346. refreshed = await self._refresh_or_none(self._user_credentials, None, "[GoogleChat] legacy creds refresh raised")
  1347. if refreshed is None:
  1348. logger.warning("[GoogleChat] legacy user-OAuth refresh returned None — evicting fallback creds")
  1349. self._invalidate_user_creds(self._LEGACY_USER_IDENTITY)
  1350. return None, None
  1351. self._user_credentials = refreshed
  1352. return self._user_chat_api, self._LEGACY_USER_IDENTITY
  1353. return None, None
  1354. def _invalidate_user_creds(self, identity: Optional[str]) -> None:
  1355. """Drop creds for ``identity`` (email or ``__legacy__``) after an auth failure."""
  1356. if not identity:
  1357. return
  1358. if identity == self._LEGACY_USER_IDENTITY:
  1359. self._user_credentials = self._user_chat_api = None
  1360. return
  1361. self._user_creds_by_email.pop(identity, None)
  1362. self._user_chat_api_by_email.pop(identity, None)
  1363. async def _send_file(
  1364. self, chat_id: str, path: str, caption: Optional[str], mime_hint: Optional[str],
  1365. thread_id: Optional[str] = None, override_filename: Optional[str] = None,
  1366. ) -> SendResult:
  1367. """Native attachment: user-authed ``media.upload`` then ``messages.create`` with the
  1368. latest inbound sender's token (legacy token as fallback; text notice when neither).
  1369. ``messages.patch`` cannot add attachments, so the typing card is patched with the
  1370. caption (or a single space) to retire it without a tombstone."""
  1371. if not os.path.exists(path):
  1372. return SendResult(success=False, error=f"file not found: {path}")
  1373. filename = override_filename or os.path.basename(path) or "upload.bin"
  1374. mime = mime_hint or "application/octet-stream"
  1375. chat_api, identity = await self._acquire_user_chat_api(self._last_sender_by_chat.get(chat_id))
  1376. if chat_api is None:
  1377. return await self._post_attachment_fallback(chat_id, path, filename, caption, thread_id)
  1378. try:
  1379. await self._consume_typing_card_with_text(chat_id, caption or " ")
  1380. except Exception:
  1381. logger.debug("[GoogleChat] _send_file pre-patch typing-card failed", exc_info=True)
  1382. try:
  1383. upload_resp = await asyncio.to_thread(lambda: chat_api.media().upload(
  1384. parent=chat_id, body={"filename": filename},
  1385. media_body=MediaFileUpload(path, mimetype=mime, resumable=False),
  1386. ).execute())
  1387. except HttpError as exc:
  1388. status = _http_status(exc)
  1389. if status in {401, 403}:
  1390. logger.warning(
  1391. "[GoogleChat] media.upload auth failure for identity=%s (token revoked or scope missing) — falling "
  1392. "back to text notice. Status=%s", identity, status,
  1393. )
  1394. self._invalidate_user_creds(identity)
  1395. return await self._post_attachment_fallback(chat_id, path, filename, caption, thread_id)
  1396. return SendResult(success=False, error=_redact_sensitive(str(exc)))
  1397. attachment_ref = upload_resp.get("attachmentDataRef")
  1398. if not attachment_ref:
  1399. return SendResult(success=False, error="upload returned no attachmentDataRef")
  1400. body: dict[str, Any] = {"attachment": [{"attachmentDataRef": attachment_ref}]}
  1401. body.update({k: v for k, v in (("text", caption), ("thread", {"name": thread_id} if thread_id else None)) if v})
  1402. # The attachmentDataRef is bound to the uploading principal, so this create
  1403. # also needs user auth.
  1404. create_kwargs = _create_kwargs(chat_id, body)
  1405. try:
  1406. resp = await asyncio.to_thread(lambda: chat_api.spaces().messages().create(**create_kwargs).execute())
  1407. self._track_outbound_thread(chat_id, resp)
  1408. return SendResult(success=True, message_id=resp.get("name"))
  1409. except HttpError as exc:
  1410. return SendResult(success=False, error=_redact_sensitive(str(exc)))
  1411. async def _post_attachment_fallback(self, chat_id: str, path: str, filename: str, caption: Optional[str],
  1412. thread_id: Optional[str]) -> SendResult:
  1413. """Post the ``/setup-files`` notice (plus host path) when native delivery is
  1414. unavailable. Always returns ``success=False``."""
  1415. notice = "\n".join([
  1416. t("platform.google_chat.attachment_fallback.header", filename=filename),
  1417. t("platform.google_chat.attachment_fallback.explain"),
  1418. t("platform.google_chat.attachment_fallback.activate"),
  1419. t("platform.google_chat.attachment_fallback.host_path", path=path),
  1420. ])
  1421. body = self.warning_text(f"{caption}\n{notice}" if caption else notice, caption or "")
  1422. try:
  1423. if body:
  1424. await self._create_message(chat_id, _thread_body(body, thread_id))
  1425. except Exception:
  1426. logger.debug("[GoogleChat] attachment fallback notice send failed", exc_info=True)
  1427. return SendResult(
  1428. success=False, error="google_chat: native attachment requires user OAuth — run /setup-files in chat")
  1429. async def get_chat_info(self, chat_id: str) -> dict[str, Any]:
  1430. """Return {name, type, chat_id} for a space."""
  1431. try:
  1432. info = await asyncio.to_thread(
  1433. lambda: self._chat_api.spaces().get(name=chat_id).execute(http=self._new_authed_http()))
  1434. except HttpError as exc:
  1435. logger.debug("[GoogleChat] get_chat_info failed: %s", _redact_sensitive(str(exc)))
  1436. return {"name": chat_id, "type": "group", "chat_id": chat_id}
  1437. space_type = (info.get("spaceType") or info.get("type") or "").upper()
  1438. return {
  1439. "name": info.get("displayName") or chat_id,
  1440. "type": "dm" if space_type in {"DIRECT_MESSAGE", "DM"} else "group",
  1441. "chat_id": chat_id,
  1442. }
  1443. # -- plugin entry point -----------------------------------------------------
  1444. def _validate_config(config: PlatformConfig) -> bool:
  1445. """Plugin-side config gate for HTTP callback or Pub/Sub inbound modes."""
  1446. extra = getattr(config, "extra", {}) or {}
  1447. return bool(extra.get("http_events_url") or (extra.get("project_id") and extra.get("subscription_name")))
  1448. def _env_inbound_settings() -> tuple[Optional[str], Optional[str], Optional[str]]:
  1449. """(project, subscription, http_events_url) from the scoped env, with legacy fallbacks."""
  1450. project = _get_scoped_secret("GOOGLE_CHAT_PROJECT_ID") or _get_scoped_secret("GOOGLE_CLOUD_PROJECT")
  1451. subscription = _get_scoped_secret("GOOGLE_CHAT_SUBSCRIPTION_NAME") or _get_scoped_secret("GOOGLE_CHAT_SUBSCRIPTION")
  1452. return project, subscription, _get_scoped_secret("GOOGLE_CHAT_HTTP_EVENTS_URL")
  1453. def _env_inbound_configured() -> bool:
  1454. project, subscription, http_events_url = _env_inbound_settings()
  1455. return bool(http_events_url or (project and subscription))
  1456. def _check_for_registry() -> bool:
  1457. """``check_fn`` for the registry pass: deps installed AND minimum inbound env set,
  1458. so an unconfigured user never sees ``google_chat`` auto-enabled."""
  1459. return check_google_chat_requirements() and _env_inbound_configured()
  1460. def _is_connected(config: PlatformConfig) -> bool:
  1461. """``GatewayConfig.get_connected_platforms()`` polls this."""
  1462. return bool(getattr(config, "enabled", False)) and _validate_config(config)
  1463. _ENV_SEED_KEYS = ( # (env var, extra key, conv) for seed_extra_from_env
  1464. ("GOOGLE_CHAT_HTTP_EVENTS_AUDIENCE", "http_events_audience", None),
  1465. ("GOOGLE_CHAT_HTTP_EVENTS_SERVICE_ACCOUNT_EMAIL", "http_events_service_account_email", None),
  1466. ("GOOGLE_CHAT_MAX_MESSAGES", "max_messages", None), ("GOOGLE_CHAT_MAX_BYTES", "max_bytes", None),
  1467. ("GOOGLE_CHAT_BOOTSTRAP_SPACES", "bootstrap_spaces", None), ("GOOGLE_CHAT_DEBUG_RAW", "debug_raw", None),
  1468. )
  1469. def _env_enablement() -> Optional[dict[str, Any]]:
  1470. """``env_enablement_fn``: seed ``PlatformConfig.extra`` from the profile's env before the adapter exists
  1471. (so ``gateway status`` reflects env-only config); ``None`` when the minimum inbound settings are absent."""
  1472. if not _env_inbound_configured():
  1473. return None
  1474. project, subscription, http_events_url = _env_inbound_settings()
  1475. values = [("project_id", project), ("subscription_name", subscription), ("http_events_url", http_events_url),
  1476. ("service_account_json", _get_scoped_secret("GOOGLE_CHAT_SERVICE_ACCOUNT_JSON")
  1477. or _get_scoped_secret("GOOGLE_APPLICATION_CREDENTIALS"))]
  1478. seed = {extra_name: value for extra_name, value in values if value}
  1479. seed.update(_seed_extra_from_env(_ENV_SEED_KEYS, home_env="GOOGLE_CHAT_HOME_CHANNEL"))
  1480. return seed
  1481. _SETUP_WALKTHROUGH = """Google Chat needs a GCP project, a Pub/Sub topic + subscription,
  1482. and a Service Account with Pub/Sub Subscriber on the subscription.
  1483. Walkthrough:
  1484. 1. Create or select a GCP project; enable Google Chat API + Cloud Pub/Sub API.
  1485. 2. Create a Service Account (no project-level IAM role needed).
  1486. 3. Create a Pub/Sub topic (e.g. hermes-chat-events) and a Pull subscription.
  1487. 4. On the TOPIC: add chat-api-push@system.gserviceaccount.com as Pub/Sub Publisher.
  1488. 5. On the SUBSCRIPTION: grant your Service Account Pub/Sub Subscriber.
  1489. 6. Download the Service Account JSON key.
  1490. 7. Google Chat API console → Configuration: connection = Cloud Pub/Sub,
  1491. point at the topic, enable 1:1 + group, restrict visibility.
  1492. 8. Install the bot in a space (fires ADDED_TO_SPACE and resolves its user_id).
  1493. Full guide: website/docs/user-guide/messaging/google_chat.md
  1494. """
  1495. def interactive_setup() -> None:
  1496. """``hermes setup`` wizard: print GCP instructions, prompt for env vars, persist to ``~/.hermes/.env``."""
  1497. from hermes_cli.cli_output import print_info, print_success, print_warning, prompt, prompt_yes_no
  1498. from hermes_cli.config import get_env_value, save_env_value
  1499. from hermes_cli.setup_platforms import declines_reconfigure
  1500. if declines_reconfigure("Google Chat", "Reconfigure Google Chat?", "GOOGLE_CHAT_SUBSCRIPTION_NAME"):
  1501. return
  1502. for line in _SETUP_WALKTHROUGH.splitlines():
  1503. print_info(line)
  1504. for question, env_name, required_label, password in (
  1505. ("GCP project ID (e.g. my-project)", "GOOGLE_CHAT_PROJECT_ID", "Project ID", False),
  1506. ("Pub/Sub subscription (projects/<proj>/subscriptions/<sub>)", "GOOGLE_CHAT_SUBSCRIPTION_NAME", "Subscription", False),
  1507. ("Path to Service Account JSON (or inline JSON)", "GOOGLE_CHAT_SERVICE_ACCOUNT_JSON", None, True),
  1508. ):
  1509. value = prompt(question, default=get_env_value(env_name) or "", password=password)
  1510. if not value:
  1511. if required_label is None:
  1512. continue
  1513. print_warning(f"{required_label} is required — skipping Google Chat setup")
  1514. return
  1515. save_env_value(env_name, value.strip())
  1516. if prompt_yes_no("Restrict access to specific users? (recommended)", True):
  1517. allowed = prompt("Allowed user emails (comma-separated)", default=get_env_value("GOOGLE_CHAT_ALLOWED_USERS") or "")
  1518. if allowed:
  1519. save_env_value("GOOGLE_CHAT_ALLOWED_USERS", allowed.replace(" ", ""))
  1520. print_success("Allowlist configured")
  1521. else:
  1522. save_env_value("GOOGLE_CHAT_ALLOWED_USERS", "")
  1523. else:
  1524. save_env_value("GOOGLE_CHAT_ALLOW_ALL_USERS", "true")
  1525. print_warning("⚠️ Open access — anyone who can DM the bot can command it.")
  1526. home = prompt(
  1527. "Home space for cron/notification delivery (e.g. spaces/AAAA, or empty)",
  1528. default=get_env_value("GOOGLE_CHAT_HOME_CHANNEL") or "",
  1529. )
  1530. if home:
  1531. save_env_value("GOOGLE_CHAT_HOME_CHANNEL", home.strip())
  1532. print()
  1533. print_success("Google Chat configuration saved to ~/.hermes/.env")
  1534. print_info("Restart the gateway: hermes gateway restart")
  1535. # Strict resource-name patterns: anything outside Chat's documented character set
  1536. # is a tampered id trying to break out of the REST URL path.
  1537. _GCHAT_CHAT_ID_RE = re.compile(r"^(?:spaces|users)/[A-Za-z0-9_-]+$")
  1538. _GCHAT_THREAD_ID_RE = re.compile(r"^spaces/[A-Za-z0-9_-]+/threads/[A-Za-z0-9_-]+$")
  1539. # Detail suffixes for ``_standalone_error`` keyed by ``_SACredentialError.kind``.
  1540. _STANDALONE_SA_ERRORS = {
  1541. "inline_invalid": "inline SA JSON is invalid: {exc}",
  1542. "not_found": "SA JSON file not found at {path}",
  1543. "file_invalid": "SA JSON file is invalid: {exc}",
  1544. "adc_foreign": ("ADC skipped for this profile: service-account credentials are set in the process environment but "
  1545. "not in this profile's secret scope"),
  1546. "adc_no_auth": "no SA credentials configured and google-auth is not installed for ADC fallback",
  1547. "adc_failed": "no SA credentials configured and Application Default Credentials are unavailable: {exc}",
  1548. }
  1549. def _standalone_error(detail: str) -> dict[str, Any]:
  1550. return send_error(f"Google Chat standalone send: {detail}")
  1551. async def _standalone_send(
  1552. pconfig, chat_id: str, message: str, *, thread_id: Optional[str] = None,
  1553. media_files: Optional[list[str]] = None, force_document: bool = False,
  1554. ) -> dict[str, Any]:
  1555. """POST one Chat message via REST without the SDK (``send_message_tool`` when the
  1556. gateway runner is not in-process, e.g. ``hermes cron``). Needs SA credentials and a
  1557. validated space name; ``media_files`` / ``force_document`` are signature parity only."""
  1558. if not chat_id:
  1559. return _standalone_error("chat_id (space resource) is required")
  1560. if not _GCHAT_CHAT_ID_RE.match(chat_id):
  1561. return _standalone_error(
  1562. f"chat_id {chat_id!r} must match 'spaces/<id>' or 'users/<id>' with only [A-Za-z0-9_-] in the id")
  1563. if thread_id is not None and not _GCHAT_THREAD_ID_RE.match(thread_id):
  1564. return _standalone_error(f"thread_id {thread_id!r} must match 'spaces/<id>/threads/<id>'")
  1565. extra = getattr(pconfig, "extra", {}) or {}
  1566. sa_value = (
  1567. extra.get("service_account_json") or _get_scoped_secret("GOOGLE_CHAT_SERVICE_ACCOUNT_JSON")
  1568. or _get_scoped_secret("GOOGLE_APPLICATION_CREDENTIALS")
  1569. )
  1570. if service_account is None:
  1571. return _standalone_error("google-auth not installed")
  1572. try:
  1573. from google.auth.transport.requests import Request as _GoogleAuthRequest
  1574. except Exception as e:
  1575. return _standalone_error(f"google-auth import failed: {e}")
  1576. try:
  1577. creds = _load_sa_credentials_from(sa_value)
  1578. except _SACredentialError as err:
  1579. return _standalone_error(_STANDALONE_SA_ERRORS[err.kind].format(exc=err.detail, path=sa_value))
  1580. except Exception as e:
  1581. return _standalone_error(f"credential load failed: {e}")
  1582. # Bound the synchronous token refresh so a hung STS endpoint can't stall cron.
  1583. try:
  1584. await asyncio.wait_for(asyncio.to_thread(creds.refresh, _GoogleAuthRequest()), timeout=10.0)
  1585. except TimeoutError:
  1586. return _standalone_error("token refresh timed out")
  1587. except Exception as e:
  1588. return _standalone_error(f"token refresh failed: {e}")
  1589. token = getattr(creds, "token", None)
  1590. if not token:
  1591. return _standalone_error("refreshed credentials have no token")
  1592. try:
  1593. import aiohttp as _aiohttp
  1594. except ImportError:
  1595. return _standalone_error("aiohttp not installed")
  1596. try:
  1597. async with _aiohttp.ClientSession(timeout=_aiohttp.ClientTimeout(total=30.0), trust_env=gateway_trust_env()) as session:
  1598. async with session.post(
  1599. f"https://chat.googleapis.com/v1/{chat_id}/messages", json=_thread_body(message, thread_id),
  1600. headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
  1601. ) as resp:
  1602. if resp.status >= 400:
  1603. return _standalone_error(f"API returned {resp.status}: {(await resp.text())[:300]}")
  1604. payload = await resp.json()
  1605. return {"success": True, "message_id": payload.get("name")}
  1606. except Exception as e:
  1607. logger.debug("Google Chat standalone send raised", exc_info=True)
  1608. return send_error(f"Google Chat standalone send failed: {e}")
  1609. def register(ctx) -> None:
  1610. """Plugin entry point: registers the ``google_chat`` adapter with the platform registry."""
  1611. ctx.register_platform(
  1612. name="google_chat",
  1613. dashboard_description="Connect Hermes to Google Chat via Cloud Pub/Sub.",
  1614. docs_url="https://hermes-agent.nousresearch.com/docs/user-guide/messaging/google_chat",
  1615. label="Google Chat",
  1616. adapter_factory=lambda cfg: GoogleChatAdapter(cfg),
  1617. check_fn=_check_for_registry,
  1618. ensure_deps_fn=ensure_google_chat_deps,
  1619. validate_config=_validate_config,
  1620. is_connected=_is_connected,
  1621. required_env=["GOOGLE_CHAT_SERVICE_ACCOUNT_JSON"],
  1622. install_hint="Run `hermes setup` to install Google Chat support.",
  1623. setup_fn=interactive_setup,
  1624. env_enablement_fn=_env_enablement,
  1625. cron_deliver_env_var="GOOGLE_CHAT_HOME_CHANNEL",
  1626. standalone_sender_fn=_standalone_send,
  1627. allowed_users_env="GOOGLE_CHAT_ALLOWED_USERS",
  1628. allow_all_env="GOOGLE_CHAT_ALLOW_ALL_USERS",
  1629. # Chat caps text at 4096; margin for typing-marker patches and edit overhead.
  1630. max_message_length=4000,
  1631. emoji="💬",
  1632. allow_update_command=True,
  1633. platform_hint=(
  1634. "You are on Google Chat. Limited markdown subset is rendered: *bold*, _italic_, ~strike~, `code`. "
  1635. "No headings or lists. Message size limit: 4000 characters; longer responses are split across multiple "
  1636. "messages. You are in a space (DM or group). Images render inline; audio, video, and document attachments "
  1637. "render as download cards (no native voice/video UI). To send files, include MEDIA:/absolute/path/to/file "
  1638. "in your response. Native file attachments require the user to run /setup-files once in their own DM — "
  1639. "until they do, file requests fall back to a text notice with the host path. Do NOT generate interactive "
  1640. "Card v2 buttons — Google Chat interactivity is not yet supported by this gateway; ask for typed "
  1641. "confirmations instead. While you are generating a response, a 'Hermes is thinking…' marker message "
  1642. "appears in the space and is deleted once your response is ready. You do NOT have access to Google "
  1643. "Chat-specific APIs — you cannot search space history, list space members, or manage spaces. Do not "
  1644. "promise to perform these actions; explain that you can only read messages sent directly to you and "
  1645. "respond in the same space/thread."
  1646. ),
  1647. )