adapter.py 27 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587
  1. """Raft channel platform adapter.
  2. Runs a local wake endpoint, spawns ``raft agent bridge`` as a child process, and injects
  3. content-free wake hints into the normal gateway session pipeline (token/port auto-generated
  4. if unset). The bridge owns Raft message cursors/bodies; the agent uses the Raft CLI.
  5. """
  6. from __future__ import annotations
  7. from collections import deque
  8. from datetime import datetime, timezone, UTC
  9. import functools
  10. import hmac
  11. import json
  12. import logging
  13. import os
  14. import re
  15. import secrets
  16. import shutil
  17. import socket
  18. import subprocess
  19. import sys
  20. import threading
  21. import time
  22. import uuid
  23. import weakref
  24. from pathlib import Path as _Path
  25. from typing import Any, Deque, Dict, List, Optional
  26. try:
  27. from aiohttp import web
  28. AIOHTTP_AVAILABLE = True
  29. except ImportError:
  30. AIOHTTP_AVAILABLE = False
  31. web = None # type: ignore[assignment]
  32. sys.path.insert(0, str(_Path(__file__).resolve().parents[3]))
  33. from gateway.config import Platform, PlatformConfig
  34. from gateway.platforms.base import BasePlatformAdapter, SendResult, merge_pending_message_event
  35. from gateway.platforms.event import MessageEvent, MessageType
  36. from gateway.platforms._shared import coerce_port, profile_scoped as _profile_scoped
  37. from hermes_cli.process_identity import release_process_group_once_empty, spawn_owned
  38. logger = logging.getLogger(__name__)
  39. DEFAULT_HOST = "127.0.0.1"
  40. DEFAULT_PORT = 0
  41. DEFAULT_PATH = "/wake"
  42. DEFAULT_RUNTIME_SESSION = "default"
  43. DEFAULT_MAX_BODY_BYTES = 16_384
  44. DEFAULT_ACTIVITY_QUEUE_CAP = 500
  45. ACTIVITY_CONTENT_CAP = 4096
  46. ACTIVITY_EVENT_SCHEMA = "raft-activity.v1"
  47. ACTIVITY_DRAIN_SCHEMA = "raft-activity-drain.v1"
  48. BRIDGE_TOKEN_HEADER = "x-raft-bridge-token"
  49. _WAKE_ID_KEYS = ("eventId", "attemptId", "messageId", "delivery_id", "wake_id", "id")
  50. _WAKE_PROMPT = (
  51. "Raft wake hint received. New Raft messages may be pending. "
  52. "If you have not read the Raft manual in this session, run "
  53. "`raft manual get raft-cli-overview` before using Raft commands.")
  54. _CONTENT_FIELD_NAMES = {"body", "content", "message", "messages", "preview", "snippet", "text"}
  55. _SAFE_SCALAR_RE = re.compile(r"^[a-zA-Z0-9._:@/ -]+$")
  56. _MAX_SCALAR_LENGTH = 120
  57. _ACTIVITY_ALLOWED_FIELDS = set(
  58. "schema eventId sessionId hookEventName status occurredAt toolName toolInput toolOutput "
  59. "toolInputTruncated toolOutputTruncated truncated errorClass durationMs".split())
  60. _ACTIVE_ADAPTERS: weakref.WeakSet[RaftAdapter] = weakref.WeakSet()
  61. _ACTIVE_ADAPTERS_LOCK = threading.Lock()
  62. _RAFT_CONTEXT_LOCK = threading.Lock()
  63. _RAFT_SESSION_IDS: set[str] = set()
  64. _RAFT_TURN_IDS: set[str] = set()
  65. _RAFT_PROMPT_TURN_IDS: set[str] = set()
  66. def _resolve_raft_profile() -> str:
  67. """Scope-aware ``RAFT_PROFILE``: a secondary multiplex profile configures Raft only via its own ``.env``
  68. (secret scope) — ``os.environ`` would return the DEFAULT profile's value. Unscoped ``get_secret()`` raises."""
  69. if _profile_scoped():
  70. try:
  71. from agent.secret_scope import get_secret
  72. return (get_secret("RAFT_PROFILE") or "").strip()
  73. except Exception:
  74. return ""
  75. return os.environ.get("RAFT_PROFILE", "").strip()
  76. def check_raft_requirements() -> bool:
  77. """Passive ``check_fn`` probe: intentionally silent — it runs on every
  78. ``load_gateway_config()``; ``create_adapter()`` warns when an adapter is requested."""
  79. return bool(AIOHTTP_AVAILABLE and shutil.which("raft"))
  80. def _has_content_field(value: Any) -> bool:
  81. if isinstance(value, dict):
  82. return any(str(k).strip().lower() in _CONTENT_FIELD_NAMES or _has_content_field(v) for k, v in value.items())
  83. return isinstance(value, list) and any(_has_content_field(item) for item in value)
  84. def _safe_scalar(value: Any, default: Optional[str] = None) -> Optional[str]:
  85. ok = isinstance(value, str) and 0 < len(value) <= _MAX_SCALAR_LENGTH and _SAFE_SCALAR_RE.match(value)
  86. return value if ok else default
  87. def _content_string(value: Any) -> Optional[tuple[str, bool]]:
  88. if value is None:
  89. return None
  90. try:
  91. text = value if isinstance(value, str) else json.dumps(value, ensure_ascii=False, sort_keys=True)
  92. except Exception:
  93. return None
  94. return (text[:ACTIVITY_CONTENT_CAP], len(text) > ACTIVITY_CONTENT_CAP) if text else None
  95. def _duration_ms(value: Any) -> Optional[int]:
  96. if not isinstance(value, (int, float)) or isinstance(value, bool) or int(value) < 0:
  97. return None
  98. return int(value)
  99. def _make_activity_event(*, hook_event_name: str, session_id: Any, status: str = "ok", tool_name: Any = None,
  100. tool_input: Any = None, tool_output: Any = None, error_class: Any = None,
  101. duration_ms: Any = None) -> dict[str, Any]:
  102. event: dict[str, Any] = {"schema": ACTIVITY_EVENT_SCHEMA, "eventId": f"hermes-{uuid.uuid4()}",
  103. "sessionId": _safe_scalar(session_id, "unknown") or "unknown",
  104. "hookEventName": hook_event_name, "status": "error" if status == "error" else "ok",
  105. "occurredAt": datetime.now(UTC).isoformat().replace("+00:00", "Z")}
  106. for key, raw in (("toolName", tool_name), ("errorClass", error_class)):
  107. if safe := _safe_scalar(raw):
  108. event[key] = safe
  109. if (safe_duration_ms := _duration_ms(duration_ms)) is not None:
  110. event["durationMs"] = safe_duration_ms
  111. for key, raw in (("toolInput", tool_input), ("toolOutput", tool_output)):
  112. if content := _content_string(raw):
  113. event[key], was_truncated = content
  114. if was_truncated:
  115. event[f"{key}Truncated"] = event["truncated"] = True
  116. return event
  117. _OPTIONAL_FIELD_RULES = ( # checked in this order; first failure wins
  118. (("toolName", "errorClass"), _safe_scalar, "a safe string"),
  119. (("durationMs",), lambda v: _duration_ms(v) is not None, "a non-negative number"),
  120. (("truncated", "toolInputTruncated", "toolOutputTruncated"), lambda v: isinstance(v, bool), "a boolean"))
  121. def _validate_activity_event(value: Any) -> dict[str, Any]:
  122. if not isinstance(value, dict):
  123. raise ValueError("activity event must be an object")
  124. if value.get("schema") != ACTIVITY_EVENT_SCHEMA:
  125. raise ValueError("unsupported activity event schema")
  126. if unknown := set(value) - _ACTIVITY_ALLOWED_FIELDS:
  127. raise ValueError(f"activity event field {min(unknown)} is not allowed")
  128. for key in ("eventId", "sessionId", "hookEventName", "occurredAt"):
  129. if not _safe_scalar(value.get(key)):
  130. raise ValueError(f"activity event {key} must be a safe non-empty string")
  131. if value.get("status") not in {"ok", "error"}:
  132. raise ValueError("activity event status must be ok|error")
  133. for keys, ok, what in _OPTIONAL_FIELD_RULES: # optional fields: None passes, anything else must satisfy ``ok``
  134. for key in keys:
  135. if value.get(key) is not None and not ok(value.get(key)):
  136. raise ValueError(f"activity event {key} must be {what}")
  137. event = dict(value)
  138. if event.get("durationMs") is not None:
  139. event["durationMs"] = _duration_ms(event["durationMs"])
  140. for key in ("toolInput", "toolOutput"):
  141. content = event.get(key)
  142. if content is not None and not isinstance(content, str):
  143. raise ValueError(f"activity event {key} must be a string")
  144. if content is not None and len(content) > ACTIVITY_CONTENT_CAP:
  145. event[key] = content[:ACTIVITY_CONTENT_CAP]
  146. event["truncated"] = event[f"{key}Truncated"] = True
  147. return event
  148. class ActivityQueue:
  149. """Bounded at-most-once queue for Raft external activity telemetry."""
  150. def __init__(self, cap: int = DEFAULT_ACTIVITY_QUEUE_CAP):
  151. self._cap = max(1, int(cap or DEFAULT_ACTIVITY_QUEUE_CAP))
  152. self._events: deque[dict[str, Any]] = deque()
  153. self._dropped_since_drain = 0
  154. self._lock = threading.Lock()
  155. def push(self, event: dict[str, Any]) -> None:
  156. validated = _validate_activity_event(event)
  157. with self._lock:
  158. self._events.append(validated)
  159. while len(self._events) > self._cap:
  160. self._events.popleft()
  161. self._dropped_since_drain += 1
  162. def drain(self, max_events: int = 200) -> dict[str, Any]:
  163. limit = max(1, int(max_events or 200))
  164. with self._lock:
  165. events = [self._events.popleft() for _ in range(min(limit, len(self._events)))]
  166. dropped, self._dropped_since_drain = self._dropped_since_drain, 0
  167. return {"schema": ACTIVITY_DRAIN_SCHEMA, "events": events, "dropped": dropped}
  168. @property
  169. def size(self) -> int:
  170. with self._lock:
  171. return len(self._events)
  172. def _forget_raft_context(session_id: Any, turn_id: Any = None, *, forget_session: bool = False) -> None:
  173. safe_session_id, safe_turn_id = _safe_scalar(session_id), _safe_scalar(turn_id)
  174. with _RAFT_CONTEXT_LOCK:
  175. if safe_turn_id:
  176. _RAFT_TURN_IDS.discard(safe_turn_id)
  177. _RAFT_PROMPT_TURN_IDS.discard(safe_turn_id)
  178. if forget_session and safe_session_id:
  179. _RAFT_SESSION_IDS.discard(safe_session_id)
  180. def _is_raft_context(**kwargs: Any) -> bool:
  181. """True for Raft hook payloads; an explicit platform="raft" also learns the session/turn ids."""
  182. platform = kwargs.get("platform")
  183. safe_session_id, safe_turn_id = _safe_scalar(kwargs.get("session_id")), _safe_scalar(kwargs.get("turn_id"))
  184. with _RAFT_CONTEXT_LOCK:
  185. if str(getattr(platform, "value", platform) or "") == "raft":
  186. if safe_session_id:
  187. _RAFT_SESSION_IDS.add(safe_session_id)
  188. if safe_turn_id:
  189. _RAFT_TURN_IDS.add(safe_turn_id)
  190. return True
  191. return bool((safe_turn_id and safe_turn_id in _RAFT_TURN_IDS)
  192. or (safe_session_id and safe_session_id in _RAFT_SESSION_IDS))
  193. def _emit(hook_event_name: str, kwargs: dict[str, Any], **fields: Any) -> None:
  194. """Build an activity event for the hook's session and fan it out to every live adapter."""
  195. event = _make_activity_event(hook_event_name=hook_event_name, session_id=kwargs.get("session_id"), **fields)
  196. with _ACTIVE_ADAPTERS_LOCK:
  197. adapters = list(_ACTIVE_ADAPTERS)
  198. for adapter in adapters:
  199. adapter.report_activity(event)
  200. def _raft_hook(fn):
  201. """Run the hook body only for Raft sessions."""
  202. @functools.wraps(fn)
  203. def wrapper(**kwargs: Any) -> None:
  204. if _is_raft_context(**kwargs):
  205. fn(**kwargs)
  206. return wrapper
  207. @_raft_hook
  208. def _on_session_start(**kwargs: Any) -> None:
  209. try:
  210. from tools.env_passthrough import register_env_passthrough
  211. register_env_passthrough(["RAFT_PROFILE"])
  212. except Exception:
  213. logger.debug("[raft] failed to register RAFT_PROFILE env passthrough", exc_info=True)
  214. _emit("SessionStart", kwargs)
  215. @_raft_hook
  216. def _on_pre_llm_call(**kwargs: Any) -> None:
  217. if safe_turn_id := _safe_scalar(kwargs.get("turn_id")):
  218. with _RAFT_CONTEXT_LOCK:
  219. if safe_turn_id in _RAFT_PROMPT_TURN_IDS:
  220. return
  221. _RAFT_PROMPT_TURN_IDS.add(safe_turn_id)
  222. _emit("UserPromptSubmit", kwargs)
  223. @_raft_hook
  224. def _on_pre_tool_call(**kwargs: Any) -> None:
  225. _emit("PreToolUse", kwargs, tool_name=kwargs.get("tool_name"), tool_input=kwargs.get("args"))
  226. @_raft_hook
  227. def _on_post_tool_call(**kwargs: Any) -> None:
  228. status = "error" if kwargs.get("status") in {"error", "blocked"} or kwargs.get("error_type") else "ok"
  229. _emit("PostToolUseFailure" if status == "error" else "PostToolUse", kwargs, status=status,
  230. tool_name=kwargs.get("tool_name"), tool_input=kwargs.get("args"),
  231. tool_output=kwargs.get("error_message") or kwargs.get("result"),
  232. error_class=kwargs.get("error_type") or ("tool_failure" if status == "error" else None),
  233. duration_ms=kwargs.get("duration_ms"))
  234. @_raft_hook
  235. def _on_post_llm_call(**kwargs: Any) -> None:
  236. _emit("Stop", kwargs)
  237. @_raft_hook
  238. def _on_session_end(**kwargs: Any) -> None:
  239. if kwargs.get("interrupted") or kwargs.get("completed") is False:
  240. _emit("Stop", kwargs, status="error", error_class="interrupted" if kwargs.get("interrupted") else "incomplete")
  241. _forget_raft_context(kwargs.get("session_id"), kwargs.get("turn_id"))
  242. @_raft_hook
  243. def _on_session_finalize(**kwargs: Any) -> None:
  244. _emit("SessionEnd", kwargs)
  245. _forget_raft_context(kwargs.get("session_id"), kwargs.get("turn_id"), forget_session=True)
  246. def _error_response(error: str, status: int) -> web.Response:
  247. return web.json_response({"ok": False, "error": error}, status=status)
  248. class RaftAdapter(BasePlatformAdapter):
  249. """Local HTTP endpoint for Raft channel bridge delivery."""
  250. def __init__(self, config: PlatformConfig):
  251. super().__init__(config, Platform("raft"))
  252. extra = config.extra or {}
  253. self._host: str = str(extra.get("host", DEFAULT_HOST))
  254. self._port: int = int(extra.get("port", DEFAULT_PORT))
  255. path = str(extra.get("path", DEFAULT_PATH) or DEFAULT_PATH).strip() or DEFAULT_PATH
  256. self._path: str = path if path.startswith("/") else f"/{path}"
  257. # `or ""`: a null YAML value must reach connect()'s auto-generated token, not become "None".
  258. self._bridge_token: str = str(extra.get("bridge_token") or "").strip()
  259. self._runtime_session: str = str(extra.get("runtime_session", DEFAULT_RUNTIME_SESSION) or DEFAULT_RUNTIME_SESSION)
  260. self._max_body_bytes: int = int(extra.get("max_body_bytes", DEFAULT_MAX_BODY_BYTES))
  261. self._runner = None
  262. self._bridge_process: Optional[subprocess.Popen] = None
  263. self._activity_queue = ActivityQueue()
  264. async def connect(self, *, is_reconnect: bool = False) -> bool:
  265. if not self._bridge_token:
  266. self._bridge_token = secrets.token_hex(32)
  267. logger.info("[raft] Auto-generated bridge token")
  268. # client_max_size makes aiohttp enforce the cap on every read path, including
  269. # chunked bodies with no Content-Length (mirrors gateway/platforms/webhook.py).
  270. app = web.Application(client_max_size=self._max_body_bytes)
  271. app.router.add_get("/health", self._handle_health)
  272. app.router.add_post(self._path, self._handle_wake)
  273. app.router.add_post("/activity", self._handle_activity)
  274. app.router.add_get("/activity/drain", self._handle_activity_drain)
  275. if self._port:
  276. try:
  277. with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
  278. sock.settimeout(1)
  279. sock.connect(("127.0.0.1", self._port))
  280. logger.error("[raft] Port %d already in use. Set platforms.raft.extra.port in config", self._port)
  281. return False
  282. except (ConnectionRefusedError, OSError):
  283. pass
  284. self._runner = web.AppRunner(app)
  285. await self._runner.setup()
  286. site = web.TCPSite(self._runner, self._host, self._port)
  287. await site.start()
  288. bound_port = self._port
  289. if bound_port == 0 and site._server and site._server.sockets:
  290. bound_port = site._server.sockets[0].getsockname()[1]
  291. self._mark_connected()
  292. with _ACTIVE_ADAPTERS_LOCK:
  293. _ACTIVE_ADAPTERS.add(self)
  294. logger.info("[raft] Raft channel listening on %s:%d%s", self._host, bound_port, self._path)
  295. self._spawn_bridge(bound_port)
  296. self._wire_plugin_handlers(None) # plugin-registered native handlers
  297. return True
  298. async def disconnect(self) -> None:
  299. self._stop_bridge()
  300. if self._runner:
  301. await self._runner.cleanup()
  302. self._runner = None
  303. with _ACTIVE_ADAPTERS_LOCK:
  304. _ACTIVE_ADAPTERS.discard(self)
  305. self._mark_disconnected()
  306. logger.info("[raft] Disconnected")
  307. def _spawn_bridge(self, port: int) -> None:
  308. if not (raft_bin := shutil.which("raft")):
  309. logger.warning("[raft] raft CLI not found in PATH; bridge not spawned — wake-only polling mode")
  310. return
  311. if not (profile := _resolve_raft_profile()):
  312. logger.warning("[raft] RAFT_PROFILE not set; bridge not spawned")
  313. return
  314. endpoint = f"http://{self._host}:{port}{self._path}"
  315. cmd: list[str] = [raft_bin, "--profile", profile, "agent", "bridge", "--wake-adapter", "wake-channel",
  316. "--wake-channel-endpoint", endpoint]
  317. from tools.environments.local import hermes_subprocess_env
  318. # The raft CLI needs its own profile and channel token, never Hermes' credentials.
  319. env = {**hermes_subprocess_env(), "RAFT_PROFILE": profile, "RAFT_CHANNEL_TOKEN": self._bridge_token}
  320. env["HOME"] = env["HERMES_REAL_HOME"] # the raft CLI's own login lives under the user's HOME
  321. try:
  322. # Owned: the bridge dies with this gateway however it dies (a SIGKILLed or OOM-killed
  323. # gateway used to leave `raft agent bridge` polling Raft for a channel nobody serves).
  324. self._bridge_process = spawn_owned(cmd, purpose="raft-bridge", env=env, stdin=subprocess.DEVNULL)
  325. logger.info("[raft] Spawned bridge pid=%d profile=%s endpoint=%s", self._bridge_process.pid, profile, endpoint)
  326. except Exception:
  327. logger.exception("[raft] Failed to spawn bridge")
  328. def _stop_bridge(self) -> None:
  329. proc, self._bridge_process = self._bridge_process, None
  330. if proc is None:
  331. return
  332. try:
  333. proc.terminate()
  334. proc.wait(timeout=5)
  335. logger.info("[raft] Bridge process terminated (pid=%d)", proc.pid)
  336. except subprocess.TimeoutExpired:
  337. proc.kill()
  338. logger.warning("[raft] Bridge process killed after timeout (pid=%d)", proc.pid)
  339. except Exception:
  340. logger.exception("[raft] Error stopping bridge")
  341. if proc.poll() is not None:
  342. # Stopped by us; a bridge we failed to stop stays covered by the owner-death supervisor.
  343. # timeout=0: disconnect() runs this on the event loop, which must not sleep on a child
  344. # the TERM to the leader alone left in its group.
  345. release_process_group_once_empty(proc.pid, proc=proc, timeout=0)
  346. async def send(self, chat_id: str, content: str, reply_to: Optional[str] = None,
  347. metadata: Optional[dict[str, Any]] = None) -> SendResult:
  348. logger.debug("[raft] adapter send is a no-op; agent delivers via raft CLI")
  349. return SendResult(success=True)
  350. async def get_chat_info(self, chat_id: str) -> dict[str, Any]:
  351. return {"name": f"raft/{chat_id}", "type": "raft"}
  352. async def _handle_health(self, request: web.Request) -> web.Response:
  353. activity = {"queueSize": self._activity_queue.size, "endpoint": "/activity", "drainEndpoint": "/activity/drain"}
  354. return web.json_response(
  355. {"status": "ok", "platform": "raft", "runtimeSession": self._runtime_session, "activity": activity})
  356. def _authorized(self, request: web.Request) -> bool:
  357. token = request.headers.get(BRIDGE_TOKEN_HEADER, "")
  358. # Compare as bytes: compare_digest raises TypeError on a non-ASCII str header.
  359. return bool(self._bridge_token and token) and hmac.compare_digest(token.encode(), self._bridge_token.encode())
  360. async def _read_bridge_body(self, request: web.Request, *, text: bool) -> tuple[Any, Optional[web.Response]]:
  361. """Auth + size-capped body read for wake/activity -> ``(body, None)`` or ``(None, error)``.
  362. ``text=True``: ``request.text()``, utf-8 length check, exception text in the 400 body; else raw bytes."""
  363. if not self._authorized(request):
  364. return None, _error_response("unauthorized", 401)
  365. if (request.content_length or 0) > self._max_body_bytes:
  366. return None, _error_response("payload_too_large", 413)
  367. try:
  368. body = await (request.text() if text else request.read())
  369. except web.HTTPRequestEntityTooLarge:
  370. # client_max_size tripped — chunked or lying Content-Length. Same 413 as above.
  371. return None, _error_response("payload_too_large", 413)
  372. except Exception as exc:
  373. return None, _error_response(str(exc) if text else "bad_request", 400)
  374. # Defense in depth: cap the actual bytes read even if the server-level limit was bypassed.
  375. if (len(body.encode("utf-8")) if text else len(body)) > self._max_body_bytes:
  376. return None, _error_response("payload_too_large", 413)
  377. return body, None
  378. async def _handle_wake(self, request: web.Request) -> web.Response:
  379. raw_body, error = await self._read_bridge_body(request, text=False)
  380. if error is not None:
  381. return error
  382. try:
  383. payload = json.loads(raw_body) if raw_body.strip() else {}
  384. except json.JSONDecodeError:
  385. return _error_response("invalid_json", 400)
  386. if not isinstance(payload, dict):
  387. return _error_response("invalid_payload", 400)
  388. # No payload["schema"] gate: the bridge owns schema evolution; Hermes only checks content-free.
  389. if _has_content_field(payload):
  390. return _error_response("content_not_allowed", 400)
  391. not_ready = {"ok": False, "error": "not_ready", "runtimeSession": self._runtime_session}
  392. if not self._message_handler:
  393. logger.warning("[raft] Wake received before gateway message handler was attached")
  394. return web.json_response(not_ready, status=503)
  395. delivery_id = str(
  396. next((payload.get(k) for k in _WAKE_ID_KEYS if payload.get(k)), None)
  397. or f"raft-wake-{int(time.time() * 1000)}")
  398. source = self.build_source(chat_id=self._runtime_session, chat_name="Raft channel", chat_type="dm",
  399. user_id="raft-bridge", user_name="Raft Bridge")
  400. event = MessageEvent(text=_WAKE_PROMPT, message_type=MessageType.TEXT, source=source,
  401. raw_message=payload, message_id=delivery_id, internal=True)
  402. try:
  403. await self.handle_message(event)
  404. except Exception:
  405. logger.exception("[raft] Failed to inject wake event")
  406. return web.json_response(not_ready, status=503)
  407. return web.json_response({"ok": True, "runtimeSession": self._runtime_session}, status=202)
  408. async def _handle_activity(self, request: web.Request) -> web.Response:
  409. raw_text, error = await self._read_bridge_body(request, text=True)
  410. if error is not None:
  411. return error
  412. try:
  413. self._activity_queue.push(json.loads(raw_text))
  414. except json.JSONDecodeError:
  415. return _error_response("invalid_json", 400)
  416. except Exception as exc:
  417. return _error_response(str(exc), 400)
  418. return web.json_response({"ok": True}, status=202)
  419. async def _handle_activity_drain(self, request: web.Request) -> web.Response:
  420. if not self._authorized(request):
  421. return _error_response("unauthorized", 401)
  422. max_events = coerce_port(request.query.get("max", "200"), 200) # int-or-default
  423. return web.json_response(self._activity_queue.drain(max_events))
  424. async def handle_message(self, event: MessageEvent) -> None:
  425. """Accept Raft wake hints without interrupting an active Hermes turn."""
  426. if event.internal:
  427. # Durable gateway wakes need the base session fence and admission receipt.
  428. await super().handle_message(event)
  429. return
  430. if not self._message_handler:
  431. return
  432. session_key = self._event_session_key(event)
  433. if session_key in self._active_sessions:
  434. logger.debug("[raft] Wake queued for busy session %s", session_key)
  435. merge_pending_message_event(self._pending_messages, session_key, event)
  436. return
  437. await super().handle_message(event)
  438. def report_activity(self, event: dict[str, Any]) -> None:
  439. try:
  440. self._activity_queue.push(event)
  441. except Exception:
  442. logger.debug("[raft] activity event dropped during validation", exc_info=True)
  443. def _is_connected(config: PlatformConfig) -> bool:
  444. extra = config.extra or {}
  445. return bool(extra.get("enabled") or extra.get("bridge_token"))
  446. def _env_enablement() -> Optional[dict]:
  447. """Auto-enable during gateway config load when the scope-aware RAFT_PROFILE is set.
  448. Auto-enables when RAFT_PROFILE is set (the adapter needs it anyway). Scope-aware: consults the active
  449. profile's own RAFT_PROFILE (env, or a secondary profile's own .env via the secret scope) instead of the
  450. default profile's bridged env value (mirrors the Buzz/SimpleX fix for 98738) — see
  451. ``_resolve_raft_profile``. See #98738.
  452. """
  453. return {"enabled": True} if _resolve_raft_profile() else None
  454. def interactive_setup() -> None:
  455. """``hermes gateway setup`` flow: persists ``RAFT_PROFILE`` to the Hermes env file.
  456. CLI helpers are lazy-imported so the plugin stays importable in gateway runtime and tests."""
  457. from hermes_cli.cli_output import print_header, print_info, print_success, print_warning, prompt
  458. from hermes_cli.config import get_env_value, save_env_value
  459. from hermes_cli.setup_platforms import declines_reconfigure
  460. print_header("Raft")
  461. existing_profile = get_env_value("RAFT_PROFILE")
  462. if declines_reconfigure("Raft", "Reconfigure Raft?", "RAFT_PROFILE"):
  463. print_info(f"Keeping RAFT_PROFILE={existing_profile}.")
  464. return
  465. for line in ("Connect Hermes to Raft as an external agent.", "Create the External Agent in Raft first, then run:",
  466. " raft agent login --server <server-url> --agent <agent-id> --profile-slug <slug>"):
  467. print_info(line)
  468. print()
  469. profile = prompt("Raft profile slug", default=existing_profile or "")
  470. if not profile:
  471. print_warning("Raft profile slug is required; skipping Raft setup")
  472. return
  473. save_env_value("RAFT_PROFILE", profile.strip())
  474. print()
  475. print_success("Raft configuration saved")
  476. print_info("Restart the gateway for changes to take effect: hermes gateway restart")
  477. def register(ctx) -> None:
  478. """Plugin entry point — called by the Hermes plugin system."""
  479. ctx.register_platform(
  480. name="raft",
  481. dashboard_description="Join a Raft workspace as an external agent.",
  482. docs_url="https://hermes-agent.nousresearch.com/docs/user-guide/messaging/raft",
  483. label="Raft",
  484. adapter_factory=RaftAdapter,
  485. check_fn=check_raft_requirements,
  486. is_connected=_is_connected,
  487. required_env=["RAFT_PROFILE"],
  488. install_hint="Install the Raft CLI from https://raft.build",
  489. setup_fn=interactive_setup,
  490. env_enablement_fn=_env_enablement,
  491. emoji="🔔",
  492. # Scope-aware: register() runs inside _profile_runtime_scope for a secondary multiplex
  493. # profile, so this resolves that profile's own RAFT_PROFILE (see _resolve_raft_profile).
  494. platform_hint=(
  495. "You are connected to Raft via an external-agent channel. "
  496. "Run `raft --profile {profile} profile show` to confirm which agent profile is active. "
  497. "Run `raft --profile {profile} manual get raft-cli-overview` to learn available Raft commands. "
  498. "Always pass `--profile {profile}` to every raft CLI call."
  499. ).format(profile=_resolve_raft_profile() or "your-agent-profile"))
  500. for hook_name, callback in (("on_session_start", _on_session_start), ("pre_llm_call", _on_pre_llm_call),
  501. ("pre_tool_call", _on_pre_tool_call), ("post_tool_call", _on_post_tool_call),
  502. ("post_llm_call", _on_post_llm_call), ("on_session_end", _on_session_end),
  503. ("on_session_finalize", _on_session_finalize)):
  504. ctx.register_hook(hook_name, callback)