group_plugin_api.py 62 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616161716181619162016211622162316241625162616271628162916301631163216331634163516361637163816391640164116421643164416451646164716481649165016511652165316541655165616571658165916601661166216631664166516661667166816691670167116721673167416751676167716781679168016811682168316841685168616871688168916901691169216931694169516961697169816991700170117021703170417051706170717081709171017111712171317141715171617171718171917201721172217231724172517261727172817291730173117321733173417351736173717381739174017411742174317441745174617471748174917501751175217531754175517561757175817591760176117621763176417651766176717681769
  1. """Authenticated REST adapter for the authoritative Yaoyao Group store."""
  2. from __future__ import annotations
  3. import asyncio
  4. import base64
  5. import hashlib
  6. import importlib
  7. import inspect
  8. import json
  9. import logging
  10. import os
  11. import re
  12. import sqlite3
  13. import sys
  14. import threading
  15. from collections.abc import Callable
  16. from contextlib import asynccontextmanager
  17. from importlib.machinery import ModuleSpec
  18. from pathlib import Path
  19. from types import ModuleType
  20. from typing import Annotated, Any
  21. from urllib.error import HTTPError, URLError
  22. from urllib.parse import urlencode
  23. from urllib.request import Request as URLRequest, build_opener, ProxyHandler
  24. from uuid import UUID, uuid4
  25. from fastapi import APIRouter, File, Query, Request, UploadFile, WebSocket
  26. from fastapi import Path as APIPath
  27. from fastapi.exceptions import RequestValidationError
  28. from fastapi.responses import JSONResponse, StreamingResponse
  29. from fastapi.routing import APIRoute
  30. logger = logging.getLogger(__name__)
  31. _PLUGIN_NAME = "yaoyao"
  32. _agent_name_resolver: Callable[[str], str] = lambda _profile: ""
  33. _MAX_GROUP_UPLOAD_FILES = 8
  34. _MAX_GROUP_UPLOAD_FILE_BYTES = 25 * 1_024 * 1_024
  35. _MAX_GROUP_UPLOAD_REQUEST_BYTES = 50 * 1_024 * 1_024
  36. _GROUP_UPLOAD_CHUNK_BYTES = 1_024 * 1_024
  37. _DASHBOARD_DIR = Path(__file__).resolve().parent
  38. _LOCAL_PACKAGE = (
  39. "_hermes_yaoyao_group_"
  40. + hashlib.sha256(str(_DASHBOARD_DIR).encode("utf-8")).hexdigest()[:24]
  41. )
  42. def _log_runtime_failure(message: str, error: BaseException) -> None:
  43. """Log lifecycle context and type without attacker-controlled exception text."""
  44. logger.error("%s [errorType=%s]", message, type(error).__name__)
  45. def _plugin_runtime_enabled() -> bool:
  46. """Mirror the core HTTP plugin gate for the group WebSocket channel."""
  47. try:
  48. from hermes_cli import web_server
  49. from hermes_cli.plugins_cmd import _get_disabled_set, _get_enabled_set
  50. enabled_set = _get_enabled_set()
  51. disabled_set = _get_disabled_set()
  52. plugin = next(
  53. (
  54. candidate
  55. for candidate in web_server._get_dashboard_plugins()
  56. if candidate.get("name") == _PLUGIN_NAME
  57. ),
  58. None,
  59. )
  60. except Exception:
  61. return False
  62. if plugin is None:
  63. return False
  64. source = plugin.get("source")
  65. if source == "bundled":
  66. return _PLUGIN_NAME not in disabled_set
  67. if source == "user":
  68. return _PLUGIN_NAME in enabled_set and _PLUGIN_NAME not in disabled_set
  69. return False
  70. def _ensure_local_package() -> ModuleType:
  71. """Return the stable private package assigned to this resolved directory."""
  72. package = ModuleType(_LOCAL_PACKAGE)
  73. package.__package__ = _LOCAL_PACKAGE
  74. package.__path__ = [str(_DASHBOARD_DIR)]
  75. package_spec = ModuleSpec(_LOCAL_PACKAGE, loader=None, is_package=True)
  76. package_spec.submodule_search_locations = [str(_DASHBOARD_DIR)]
  77. package.__spec__ = package_spec
  78. shared = sys.modules.setdefault(_LOCAL_PACKAGE, package)
  79. paths = getattr(shared, "__path__", None)
  80. if (
  81. not isinstance(shared, ModuleType)
  82. or not paths
  83. or Path(paths[0]).resolve() != _DASHBOARD_DIR
  84. ):
  85. raise ImportError("Yaoyao Group private package identity is invalid")
  86. return shared
  87. _package = _ensure_local_package()
  88. _protocol = importlib.import_module(f"{_LOCAL_PACKAGE}.group_protocol")
  89. _store_module = importlib.import_module(f"{_LOCAL_PACKAGE}.group_store")
  90. _stream_module = importlib.import_module(f"{_LOCAL_PACKAGE}.group_stream")
  91. _node_worker_module = importlib.import_module(
  92. f"{_LOCAL_PACKAGE}.group_node_worker"
  93. )
  94. _node_registry_module = importlib.import_module(
  95. f"{_LOCAL_PACKAGE}.group_node_registry"
  96. )
  97. PROTOCOL_VERSION = _protocol.PROTOCOL_VERSION
  98. EVENT_TYPES = _protocol.EVENT_TYPES
  99. MAX_MESSAGE_PAGE_SIZE = _protocol.MAX_MESSAGE_PAGE_SIZE
  100. limits_payload = _protocol.limits_payload
  101. normalize_interaction_id = _protocol.normalize_interaction_id
  102. AddAgentRequest = _protocol.AddAgentRequest
  103. ApprovalRequest = _protocol.ApprovalRequest
  104. ClarificationRequest = _protocol.ClarificationRequest
  105. CreateRoomRequest = _protocol.CreateRoomRequest
  106. RequestIDRequest = _protocol.RequestIDRequest
  107. SendMessageRequest = _protocol.SendMessageRequest
  108. UpdateAgentRequest = _protocol.UpdateAgentRequest
  109. UpdateRoomRequest = _protocol.UpdateRoomRequest
  110. UpdateTopicRequest = _protocol.UpdateTopicRequest
  111. MarkTopicReadRequest = _protocol.MarkTopicReadRequest
  112. NodeWorkerOpenRequest = _node_worker_module.NodeWorkerOpenRequest
  113. NodeWorkerPromptRequest = _node_worker_module.NodeWorkerPromptRequest
  114. NodeWorkerApprovalRequest = _node_worker_module.NodeWorkerApprovalRequest
  115. NodeWorkerClarificationRequest = _node_worker_module.NodeWorkerClarificationRequest
  116. NodeGatewayWorker = _node_worker_module.NodeGatewayWorker
  117. PairedNodeRegistry = _node_registry_module.PairedNodeRegistry
  118. GroupStore = _store_module.GroupStore
  119. GroupStoreError = _store_module.GroupStoreError
  120. GroupNotFoundError = _store_module.GroupNotFoundError
  121. GroupConflictError = _store_module.GroupConflictError
  122. IdempotencyConflict = _store_module.IdempotencyConflict
  123. class GroupAPIError(RuntimeError):
  124. """A stable public REST failure independent of internal exception text."""
  125. def __init__(
  126. self,
  127. code: str,
  128. message: str,
  129. status_code: int,
  130. details: dict[str, object] | None = None,
  131. ) -> None:
  132. super().__init__(message)
  133. self.code = code
  134. self.message = message
  135. self.status_code = status_code
  136. self.details = details or {}
  137. class RuntimeUnavailableError(GroupAPIError):
  138. def __init__(self) -> None:
  139. super().__init__(
  140. "runtime_unavailable",
  141. "Group runtime is unavailable",
  142. 503,
  143. )
  144. class GroupInvalidRequest(GroupAPIError):
  145. """A trusted Store or protocol input validator rejected the request."""
  146. def __init__(self, message: str) -> None:
  147. super().__init__("invalid_request", message, 400)
  148. class GroupStorageAPIError(GroupAPIError):
  149. """A raw SQLite failure hidden behind the public storage boundary."""
  150. def __init__(self) -> None:
  151. super().__init__("storage_error", "Group storage failed", 500)
  152. class GroupInternalAPIError(GroupAPIError):
  153. """An unexpected implementation failure safe for public serialization."""
  154. def __init__(self) -> None:
  155. super().__init__("internal_error", "Internal server error", 500)
  156. def _group_upload_root() -> Path:
  157. store_path = getattr(_store_instance(), "path", None)
  158. if not isinstance(store_path, Path):
  159. raise GroupStorageAPIError()
  160. return store_path.parent / "group-uploads"
  161. def _safe_upload_name(value: str | None) -> str:
  162. candidate = (value or "attachment").replace("\\", "/").rsplit("/", 1)[-1]
  163. cleaned = "".join(
  164. character
  165. for character in candidate
  166. if ord(character) >= 32 and ord(character) != 127
  167. ).strip()[:240]
  168. return cleaned or "attachment"
  169. def _safe_upload_extension(name: str) -> str:
  170. suffix = Path(name).suffix.lower()
  171. return suffix if re.fullmatch(r"\.[a-z0-9]{1,10}", suffix) else ""
  172. async def _persist_group_uploads(
  173. room_id: str,
  174. files: list[UploadFile],
  175. *,
  176. root: Path | None = None,
  177. ) -> list[dict[str, object]]:
  178. if not files:
  179. raise GroupInvalidRequest("At least one attachment is required")
  180. if len(files) > _MAX_GROUP_UPLOAD_FILES:
  181. raise GroupAPIError(
  182. "too_many_uploads",
  183. f"At most {_MAX_GROUP_UPLOAD_FILES} attachments are allowed",
  184. 413,
  185. )
  186. upload_root = (root or _group_upload_root()).resolve()
  187. room_root = upload_root / room_id
  188. created: list[Path] = []
  189. temporary: list[Path] = []
  190. total_bytes = 0
  191. result: list[dict[str, object]] = []
  192. try:
  193. room_root.mkdir(mode=0o700, parents=True, exist_ok=True)
  194. os.chmod(upload_root, 0o700)
  195. os.chmod(room_root, 0o700)
  196. for source in files:
  197. identifier = str(uuid4())
  198. name = _safe_upload_name(source.filename)
  199. destination = room_root / f"{identifier}{_safe_upload_extension(name)}"
  200. partial = room_root / f".{identifier}.part"
  201. temporary.append(partial)
  202. file_bytes = 0
  203. with partial.open("xb") as output:
  204. os.chmod(partial, 0o600)
  205. while True:
  206. chunk = await source.read(_GROUP_UPLOAD_CHUNK_BYTES)
  207. if not chunk:
  208. break
  209. file_bytes += len(chunk)
  210. total_bytes += len(chunk)
  211. if file_bytes > _MAX_GROUP_UPLOAD_FILE_BYTES:
  212. raise GroupAPIError(
  213. "upload_too_large",
  214. f"{name} exceeds 25 MiB",
  215. 413,
  216. )
  217. if total_bytes > _MAX_GROUP_UPLOAD_REQUEST_BYTES:
  218. raise GroupAPIError(
  219. "upload_request_too_large",
  220. "Combined attachments exceed 50 MiB",
  221. 413,
  222. )
  223. output.write(chunk)
  224. partial.replace(destination)
  225. temporary.remove(partial)
  226. os.chmod(destination, 0o600)
  227. created.append(destination)
  228. media_type = (source.content_type or "application/octet-stream").strip()
  229. result.append(
  230. {
  231. "id": identifier,
  232. "name": name,
  233. "path": str(destination),
  234. "mimeType": media_type or "application/octet-stream",
  235. "size": file_bytes,
  236. }
  237. )
  238. return result
  239. except GroupAPIError:
  240. for path in [*temporary, *created]:
  241. path.unlink(missing_ok=True)
  242. raise
  243. except (OSError, ValueError) as error:
  244. for path in [*temporary, *created]:
  245. path.unlink(missing_ok=True)
  246. _log_runtime_failure("Failed to persist a group attachment", error)
  247. raise GroupStorageAPIError() from error
  248. finally:
  249. for source in files:
  250. await source.close()
  251. def _error_response(error: GroupAPIError) -> JSONResponse:
  252. return JSONResponse(
  253. status_code=error.status_code,
  254. content={
  255. "detail": {
  256. "code": error.code,
  257. "message": error.message,
  258. "details": error.details,
  259. }
  260. },
  261. )
  262. def _validation_details(error: RequestValidationError) -> dict[str, object]:
  263. errors = [
  264. {
  265. "location": list(item.get("loc", ())),
  266. "message": item.get("msg", "Invalid value"),
  267. "type": item.get("type", "validation_error"),
  268. }
  269. for item in error.errors()
  270. ]
  271. return {"errors": errors}
  272. def _public_error(error: Exception) -> GroupAPIError:
  273. if isinstance(error, GroupAPIError):
  274. return error
  275. if isinstance(error, RequestValidationError):
  276. return GroupAPIError(
  277. "validation_error",
  278. "Request validation failed",
  279. 422,
  280. _validation_details(error),
  281. )
  282. if isinstance(error, IdempotencyConflict):
  283. return GroupAPIError("idempotency_conflict", str(error), 409)
  284. if isinstance(error, GroupNotFoundError):
  285. return GroupAPIError("not_found", str(error), 404)
  286. if isinstance(error, GroupConflictError):
  287. return GroupAPIError("conflict", str(error), 409)
  288. if isinstance(error, GroupStoreError):
  289. return GroupStorageAPIError()
  290. if isinstance(error, sqlite3.Error):
  291. return GroupStorageAPIError()
  292. return GroupInternalAPIError()
  293. class GroupAPIRoute(APIRoute):
  294. """Apply the plugin error envelope to validation and endpoint failures."""
  295. def get_route_handler(self) -> Callable[[Request], Any]:
  296. original = super().get_route_handler()
  297. async def wrapped(request: Request):
  298. try:
  299. return await original(request)
  300. except Exception as error:
  301. public = _public_error(error)
  302. return _error_response(public)
  303. return wrapped
  304. class _UnavailableRuntime:
  305. async def wake(self) -> None:
  306. """A missing orchestrator is harmless until Task 8 binds one."""
  307. async def create_room(self, **_: object) -> dict[str, object]:
  308. raise _package._yaoyao_group_runtime_unavailable_error()
  309. async def update_room(self, **_: object) -> dict[str, object]:
  310. raise _package._yaoyao_group_runtime_unavailable_error()
  311. async def archive_room(self, **_: object) -> dict[str, object]:
  312. raise _package._yaoyao_group_runtime_unavailable_error()
  313. async def restore_room(self, **_: object) -> dict[str, object]:
  314. raise _package._yaoyao_group_runtime_unavailable_error()
  315. async def archive_topic(self, **_: object) -> dict[str, object]:
  316. raise _package._yaoyao_group_runtime_unavailable_error()
  317. async def restore_topic(self, **_: object) -> dict[str, object]:
  318. raise _package._yaoyao_group_runtime_unavailable_error()
  319. async def add_agent(self, **_: object) -> dict[str, object]:
  320. raise _package._yaoyao_group_runtime_unavailable_error()
  321. async def update_agent(self, **_: object) -> dict[str, object]:
  322. raise _package._yaoyao_group_runtime_unavailable_error()
  323. async def delete_agent(self, **_: object) -> dict[str, object]:
  324. raise _package._yaoyao_group_runtime_unavailable_error()
  325. async def send_message(self, **_: object) -> dict[str, object]:
  326. raise _package._yaoyao_group_runtime_unavailable_error()
  327. async def interrupt_agent(self, **_: object) -> dict[str, object]:
  328. raise _package._yaoyao_group_runtime_unavailable_error()
  329. async def respond_approval(self, **_: object) -> dict[str, object]:
  330. raise _package._yaoyao_group_runtime_unavailable_error()
  331. async def respond_clarification(self, **_: object) -> dict[str, object]:
  332. raise _package._yaoyao_group_runtime_unavailable_error()
  333. def _default_orchestrator_factory(store: object) -> object:
  334. """Construct the runtime lazily so importing the plugin has no side effects."""
  335. module = importlib.import_module(f"{_LOCAL_PACKAGE}.group_orchestrator")
  336. return module.GroupOrchestrator(store, work_enabled=_plugin_runtime_enabled)
  337. class _RuntimeManager:
  338. """Own exactly one orchestrator for one nested Router lifespan generation."""
  339. def __init__(self) -> None:
  340. self._lock: asyncio.Lock | None = None
  341. self._leases = 0
  342. self._orchestrator: object | None = None
  343. self._accepting = False
  344. self._starting = False
  345. self._releasing = False
  346. self._generation = 0
  347. self._inflight = 0
  348. self._inflight_zero: asyncio.Event | None = None
  349. self._start_done: asyncio.Event | None = None
  350. self._release_done: asyncio.Event | None = None
  351. self._release_task: asyncio.Task[None] | None = None
  352. def _current_lock(self) -> asyncio.Lock:
  353. if self._lock is None:
  354. self._lock = asyncio.Lock()
  355. return self._lock
  356. async def acquire(self) -> None:
  357. lock = self._current_lock()
  358. while True:
  359. async with lock:
  360. if self._releasing:
  361. wait_for = self._release_done
  362. elif self._starting:
  363. wait_for = self._start_done
  364. elif self._leases:
  365. self._leases += 1
  366. return
  367. else:
  368. wait_for = None
  369. self._generation += 1
  370. generation = self._generation
  371. self._leases = 1
  372. self._starting = True
  373. self._accepting = False
  374. self._inflight = 0
  375. self._inflight_zero = asyncio.Event()
  376. self._inflight_zero.set()
  377. self._start_done = asyncio.Event()
  378. if _package._yaoyao_group_runtime_override:
  379. self._starting = False
  380. self._accepting = True
  381. self._start_done.set()
  382. return
  383. if wait_for is not None:
  384. await wait_for.wait()
  385. continue
  386. break
  387. orchestrator: object | None = None
  388. try:
  389. store = _store_instance()
  390. factory = _package._yaoyao_group_orchestrator_factory
  391. def adopt(created: object) -> None:
  392. nonlocal orchestrator
  393. orchestrator = created
  394. await self._run_owned_start_worker(factory, store, adopt=adopt)
  395. start = getattr(orchestrator, "start")
  396. await self._run_owned_start(start(), cancel_worker=True)
  397. except asyncio.CancelledError as start_cancellation:
  398. cleanup_cancellation: asyncio.CancelledError | None = None
  399. try:
  400. await self._cleanup_failed_start(orchestrator)
  401. except asyncio.CancelledError as error:
  402. cleanup_cancellation = error
  403. finally:
  404. async with lock:
  405. if self._generation == generation and self._starting:
  406. self._leases = 0
  407. self._starting = False
  408. self._reset_generation()
  409. if self._start_done is not None:
  410. self._start_done.set()
  411. self._start_done = None
  412. raise cleanup_cancellation or start_cancellation
  413. except BaseException as error: # noqa: BLE001 - isolate plugin startup
  414. cleanup_cancellation = None
  415. try:
  416. await self._cleanup_failed_start(orchestrator)
  417. except asyncio.CancelledError as cancelled:
  418. cleanup_cancellation = cancelled
  419. async with lock:
  420. _log_runtime_failure("YaoYao group runtime startup failed", error)
  421. if self._generation == generation and self._starting:
  422. if cleanup_cancellation is not None:
  423. self._leases = 0
  424. self._reset_generation()
  425. else:
  426. self._starting = False
  427. if self._start_done is not None:
  428. self._start_done.set()
  429. self._start_done = None
  430. if cleanup_cancellation is not None:
  431. raise cleanup_cancellation
  432. return
  433. async with lock:
  434. if self._generation != generation or not self._starting:
  435. await self._cleanup_failed_start(orchestrator)
  436. return
  437. self._orchestrator = orchestrator
  438. with _package._yaoyao_group_store_lock:
  439. if _package._yaoyao_group_store is store:
  440. _package._yaoyao_group_store_ready = True
  441. _publish_runtime(orchestrator)
  442. self._starting = False
  443. self._accepting = True
  444. if self._start_done is not None:
  445. self._start_done.set()
  446. self._start_done = None
  447. async def release(self) -> None:
  448. lock = self._current_lock()
  449. cancellation: asyncio.CancelledError | None = None
  450. while True:
  451. try:
  452. await lock.acquire()
  453. break
  454. except asyncio.CancelledError as error:
  455. if cancellation is None:
  456. cancellation = error
  457. if not self._discard_current_cancellation():
  458. raise
  459. release_task: asyncio.Task[None] | None = None
  460. try:
  461. if self._releasing:
  462. release_task = self._release_task
  463. elif self._leases:
  464. self._leases -= 1
  465. if self._leases == 0:
  466. self._releasing = True
  467. self._accepting = False
  468. self._release_done = asyncio.Event()
  469. generation = self._generation
  470. orchestrator = self._orchestrator
  471. release_done = self._release_done
  472. if not _package._yaoyao_group_runtime_override:
  473. _publish_runtime(_UnavailableRuntime())
  474. release_task = asyncio.create_task(
  475. self._release_generation(
  476. generation=generation,
  477. orchestrator=orchestrator,
  478. inflight_zero=self._inflight_zero,
  479. release_done=release_done,
  480. ),
  481. name=f"yaoyao-group-release-{generation}",
  482. )
  483. self._release_task = release_task
  484. finally:
  485. lock.release()
  486. if release_task is not None:
  487. try:
  488. await self._wait_for_owned_task(release_task)
  489. except BaseException:
  490. if cancellation is not None:
  491. raise cancellation
  492. raise
  493. if cancellation is not None:
  494. raise cancellation
  495. async def _release_generation(
  496. self,
  497. *,
  498. generation: int,
  499. orchestrator: object | None,
  500. inflight_zero: asyncio.Event | None,
  501. release_done: asyncio.Event,
  502. ) -> None:
  503. try:
  504. await self._wait_for_inflight_release(inflight_zero)
  505. if orchestrator is not None:
  506. await self._shutdown_owned_runtime(orchestrator, generation)
  507. except BaseException as error: # noqa: BLE001 - host shutdown must continue
  508. _log_runtime_failure("YaoYao group runtime shutdown failed", error)
  509. finally:
  510. await self._finish_owned_release(
  511. generation=generation,
  512. orchestrator=orchestrator,
  513. release_done=release_done,
  514. )
  515. @staticmethod
  516. async def _wait_for_owned_task(task: asyncio.Task[object]) -> object:
  517. """Return only after a manager-owned task, preserving caller cancellation."""
  518. cancellation: asyncio.CancelledError | None = None
  519. while not task.done():
  520. try:
  521. await asyncio.shield(task)
  522. except asyncio.CancelledError as error:
  523. if task.done():
  524. break
  525. if cancellation is None:
  526. cancellation = error
  527. try:
  528. result = task.result()
  529. except BaseException:
  530. if cancellation is not None:
  531. raise cancellation
  532. raise
  533. if cancellation is not None:
  534. raise cancellation
  535. return result
  536. @staticmethod
  537. def _discard_current_cancellation() -> bool:
  538. """Clear cancellation counts only for cleanup tasks that intentionally persist."""
  539. task = asyncio.current_task()
  540. cancelling = getattr(task, "cancelling", None)
  541. uncancel = getattr(task, "uncancel", None)
  542. if not callable(cancelling) or not callable(uncancel):
  543. return False
  544. had_cancellation = bool(cancelling())
  545. while cancelling():
  546. uncancel()
  547. return had_cancellation
  548. async def _wait_for_inflight_release(
  549. self, inflight_zero: asyncio.Event | None
  550. ) -> None:
  551. if inflight_zero is None:
  552. return
  553. while not inflight_zero.is_set():
  554. try:
  555. await inflight_zero.wait()
  556. except asyncio.CancelledError:
  557. if not self._discard_current_cancellation():
  558. raise
  559. async def _shutdown_owned_runtime(
  560. self, orchestrator: object, generation: int
  561. ) -> None:
  562. """Shield shutdown from release cancellation, including loop teardown."""
  563. shutdown_task = asyncio.create_task(
  564. self._run_owned_shutdown(orchestrator),
  565. name=f"yaoyao-group-runtime-shutdown-{generation}",
  566. )
  567. while not shutdown_task.done():
  568. try:
  569. await asyncio.shield(shutdown_task)
  570. except asyncio.CancelledError:
  571. self._discard_current_cancellation()
  572. shutdown_task.result()
  573. async def _run_owned_shutdown(self, orchestrator: object) -> None:
  574. while True:
  575. try:
  576. await getattr(orchestrator, "shutdown")()
  577. return
  578. except asyncio.CancelledError:
  579. if not self._discard_current_cancellation():
  580. raise
  581. async def _finish_owned_release(
  582. self,
  583. *,
  584. generation: int,
  585. orchestrator: object | None,
  586. release_done: asyncio.Event,
  587. ) -> None:
  588. lock = self._current_lock()
  589. while True:
  590. try:
  591. await lock.acquire()
  592. break
  593. except asyncio.CancelledError:
  594. if not self._discard_current_cancellation():
  595. raise
  596. try:
  597. if (
  598. self._generation == generation
  599. and self._orchestrator is orchestrator
  600. and self._releasing
  601. ):
  602. self._orchestrator = None
  603. self._releasing = False
  604. self._inflight = 0
  605. self._inflight_zero = None
  606. self._release_task = None
  607. self._reset_generation()
  608. if self._release_done is release_done:
  609. self._release_done = None
  610. finally:
  611. release_done.set()
  612. lock.release()
  613. async def dispatch(self, method: str, **kwargs: object) -> object:
  614. """Lease one published runtime through the complete request callback."""
  615. runtime = await self._begin_operation(require_runtime=True)
  616. async def invoke() -> object:
  617. callback = getattr(runtime, method)
  618. is_async = inspect.iscoroutinefunction(
  619. callback
  620. ) or inspect.iscoroutinefunction(getattr(callback, "__call__", None))
  621. if is_async:
  622. result = callback(**kwargs)
  623. else:
  624. result = await asyncio.to_thread(callback, **kwargs)
  625. if inspect.isawaitable(result):
  626. return await result
  627. return result
  628. return await self._run_owned_operation(
  629. invoke(), name=f"yaoyao-group-dispatch-{method}"
  630. )
  631. async def dispatch_store(
  632. self,
  633. method: str,
  634. *args: object,
  635. **kwargs: object,
  636. ) -> object:
  637. """Lease the complete blocking Store read through its worker return."""
  638. await self._begin_operation(require_runtime=False)
  639. return await self._run_owned_operation(
  640. asyncio.to_thread(_invoke_store, method, *args, **kwargs),
  641. name=f"yaoyao-group-store-{method}",
  642. )
  643. async def _begin_operation(self, *, require_runtime: bool) -> object | None:
  644. lock = self._current_lock()
  645. async with lock:
  646. override = bool(_package._yaoyao_group_runtime_override)
  647. if self._starting or self._releasing or not self._accepting:
  648. raise _package._yaoyao_group_runtime_unavailable_error()
  649. runtime = _package._yaoyao_group_runtime if override else self._orchestrator
  650. if require_runtime and (
  651. runtime is None or isinstance(runtime, _UnavailableRuntime)
  652. ):
  653. raise _package._yaoyao_group_runtime_unavailable_error()
  654. self._inflight += 1
  655. if self._inflight_zero is None:
  656. self._inflight_zero = asyncio.Event()
  657. self._inflight_zero.clear()
  658. return runtime
  659. async def _run_owned_operation(self, operation: object, *, name: str) -> object:
  660. if not inspect.isawaitable(operation):
  661. raise TypeError("leased operation must be awaitable")
  662. owned_task = asyncio.create_task(operation, name=name)
  663. def finished(done: asyncio.Task[object]) -> None:
  664. try:
  665. if not done.cancelled():
  666. done.exception()
  667. except asyncio.CancelledError:
  668. pass
  669. self._inflight -= 1
  670. if self._inflight == 0 and self._inflight_zero is not None:
  671. self._inflight_zero.set()
  672. owned_task.add_done_callback(finished)
  673. return await asyncio.shield(owned_task)
  674. async def stream_store(
  675. self, websocket: WebSocket, stream: Callable[..., object]
  676. ) -> object:
  677. """Lease a complete stream; closing invalidates its Store provider."""
  678. await self._begin_operation(require_runtime=False)
  679. generation = self._generation
  680. async def invoke() -> object:
  681. try:
  682. result = stream(
  683. websocket, lambda: self.store_for_generation(generation)
  684. )
  685. if inspect.isawaitable(result):
  686. return await result
  687. return result
  688. except RuntimeUnavailableError:
  689. await websocket.close(code=1013, reason="Group runtime is unavailable")
  690. return None
  691. return await self._run_owned_operation(
  692. invoke(), name=f"yaoyao-group-stream-{generation}"
  693. )
  694. def store_for_generation(self, generation: int) -> object:
  695. """Resolve Store only while a WebSocket still belongs to this generation."""
  696. if (
  697. generation != self._generation
  698. or self._starting
  699. or self._releasing
  700. or not self._accepting
  701. ):
  702. raise _package._yaoyao_group_runtime_unavailable_error()
  703. return _initialized_store()
  704. @staticmethod
  705. async def _cleanup_failed_start(orchestrator: object | None) -> None:
  706. if orchestrator is None:
  707. return
  708. try:
  709. await _RuntimeManager._run_owned_start(getattr(orchestrator, "shutdown")())
  710. except asyncio.CancelledError:
  711. raise
  712. except BaseException as error: # noqa: BLE001 - preserve startup isolation
  713. _log_runtime_failure("YaoYao group partial runtime cleanup failed", error)
  714. @staticmethod
  715. async def _run_owned_start(
  716. operation: object, *, cancel_worker: bool = False
  717. ) -> object:
  718. """Wait out caller cancellation before relinquishing startup ownership."""
  719. if not inspect.isawaitable(operation):
  720. raise TypeError("runtime start must be awaitable")
  721. worker = asyncio.create_task(operation, name="yaoyao-group-runtime-start")
  722. cancellation: asyncio.CancelledError | None = None
  723. while not worker.done():
  724. try:
  725. await asyncio.shield(worker)
  726. except asyncio.CancelledError as error:
  727. if cancellation is None:
  728. cancellation = error
  729. if cancel_worker:
  730. worker.cancel()
  731. try:
  732. result = worker.result()
  733. except BaseException:
  734. if cancellation is not None:
  735. raise cancellation
  736. raise
  737. if cancellation is not None:
  738. raise cancellation
  739. return result
  740. @staticmethod
  741. async def _run_owned_start_worker(
  742. callback: Callable[..., object],
  743. *args: object,
  744. adopt: Callable[[object], None],
  745. ) -> object:
  746. worker = asyncio.create_task(
  747. asyncio.to_thread(callback, *args),
  748. name="yaoyao-group-runtime-create",
  749. )
  750. cancellation: asyncio.CancelledError | None = None
  751. while not worker.done():
  752. try:
  753. await asyncio.shield(worker)
  754. except asyncio.CancelledError as error:
  755. if cancellation is None:
  756. cancellation = error
  757. try:
  758. result = worker.result()
  759. except BaseException:
  760. if cancellation is not None:
  761. raise cancellation
  762. raise
  763. adopt(result)
  764. if cancellation is not None:
  765. raise cancellation
  766. return result
  767. def _reset_generation(self) -> None:
  768. self._accepting = False
  769. self._starting = False
  770. if not _package._yaoyao_group_store_override:
  771. with _package._yaoyao_group_store_lock:
  772. _package._yaoyao_group_store = None
  773. _package._yaoyao_group_store_ready = False
  774. @asynccontextmanager
  775. async def _router_lifespan(_: object):
  776. manager = _package._yaoyao_group_runtime_manager
  777. await manager.acquire()
  778. try:
  779. yield
  780. finally:
  781. await manager.release()
  782. _bootstrap_lock = vars(_package).setdefault(
  783. "_yaoyao_group_bootstrap_lock", threading.RLock()
  784. )
  785. with _bootstrap_lock:
  786. if not hasattr(_package, "_yaoyao_group_store_lock"):
  787. _package._yaoyao_group_runtime_unavailable_error = RuntimeUnavailableError
  788. _package._yaoyao_group_store_lock = threading.Lock()
  789. _package._yaoyao_group_store = None
  790. _package._yaoyao_group_store_ready = False
  791. _package._yaoyao_group_store_override = False
  792. _package._yaoyao_group_runtime = _UnavailableRuntime()
  793. _package._yaoyao_group_runtime_override = False
  794. _package._yaoyao_group_orchestrator_factory = _default_orchestrator_factory
  795. _package._yaoyao_group_runtime_manager = _RuntimeManager()
  796. _package._yaoyao_node_worker_lock = threading.Lock()
  797. _package._yaoyao_node_worker = None
  798. _package._yaoyao_node_registry_lock = threading.Lock()
  799. _package._yaoyao_node_registry = None
  800. if not hasattr(_package, "_yaoyao_node_worker_lock"):
  801. _package._yaoyao_node_worker_lock = threading.Lock()
  802. _package._yaoyao_node_worker = None
  803. if not hasattr(_package, "_yaoyao_node_registry_lock"):
  804. _package._yaoyao_node_registry_lock = threading.Lock()
  805. _package._yaoyao_node_registry = None
  806. def set_store_for_testing(store: object | None) -> None:
  807. """Inject an isolated store; initialization remains lazy and off-loop."""
  808. with _package._yaoyao_group_store_lock:
  809. _package._yaoyao_group_store = store
  810. _package._yaoyao_group_store_ready = False
  811. _package._yaoyao_group_store_override = store is not None
  812. def set_agent_name_resolver(resolver: Callable[[str], str]) -> None:
  813. """Use the host-provided Hermes Bot display-name resolver."""
  814. global _agent_name_resolver
  815. _agent_name_resolver = resolver
  816. def set_node_worker_for_testing(worker: object | None) -> None:
  817. with _package._yaoyao_node_worker_lock:
  818. current = _package._yaoyao_node_worker
  819. if current is not None and current is not worker:
  820. shutdown = getattr(current, "shutdown", None)
  821. if callable(shutdown):
  822. shutdown()
  823. _package._yaoyao_node_worker = worker
  824. def _node_worker_instance() -> object:
  825. with _package._yaoyao_node_worker_lock:
  826. worker = _package._yaoyao_node_worker
  827. if worker is None:
  828. worker = NodeGatewayWorker()
  829. _package._yaoyao_node_worker = worker
  830. return worker
  831. async def _node_worker_call(method: str, *args: object, **kwargs: object) -> object:
  832. worker = _node_worker_instance()
  833. operation = getattr(worker, method, None)
  834. if not callable(operation):
  835. raise RuntimeUnavailableError()
  836. return await asyncio.to_thread(operation, *args, **kwargs)
  837. def set_node_registry_for_testing(registry: object | None) -> None:
  838. with _package._yaoyao_node_registry_lock:
  839. _package._yaoyao_node_registry = registry
  840. def _node_registry_instance() -> object:
  841. with _package._yaoyao_node_registry_lock:
  842. registry = _package._yaoyao_node_registry
  843. if registry is None:
  844. registry = PairedNodeRegistry.from_environment()
  845. _package._yaoyao_node_registry = registry
  846. return registry
  847. async def _node_registry_call(
  848. method: str, *args: object, **kwargs: object
  849. ) -> object:
  850. registry = _node_registry_instance()
  851. operation = getattr(registry, method, None)
  852. if not callable(operation):
  853. raise RuntimeUnavailableError()
  854. return await asyncio.to_thread(operation, *args, **kwargs)
  855. def set_runtime_facade(runtime: object | None) -> None:
  856. """Bind the narrow Task-8 runtime surface, or restore the safe default."""
  857. _package._yaoyao_group_runtime_override = runtime is not None
  858. _publish_runtime(_UnavailableRuntime() if runtime is None else runtime)
  859. manager = _package._yaoyao_group_runtime_manager
  860. if runtime is None:
  861. manager._accepting = False
  862. elif not manager._starting and not manager._releasing:
  863. manager._accepting = True
  864. def set_orchestrator_factory_for_testing(
  865. factory: Callable[[object], object] | None,
  866. ) -> None:
  867. """Inject construction without importing the real Gateway runtime."""
  868. _package._yaoyao_group_orchestrator_factory = (
  869. _default_orchestrator_factory if factory is None else factory
  870. )
  871. def _publish_runtime(runtime: object) -> None:
  872. _package._yaoyao_group_runtime = runtime
  873. def _store_instance() -> object:
  874. with _package._yaoyao_group_store_lock:
  875. if _package._yaoyao_group_store is None:
  876. _package._yaoyao_group_store = GroupStore.from_environment(
  877. agent_name_resolver=_agent_name_resolver
  878. )
  879. return _package._yaoyao_group_store
  880. def _initialized_store() -> object:
  881. with _package._yaoyao_group_store_lock:
  882. if _package._yaoyao_group_store is None:
  883. _package._yaoyao_group_store = GroupStore.from_environment(
  884. agent_name_resolver=_agent_name_resolver
  885. )
  886. store = _package._yaoyao_group_store
  887. if not _package._yaoyao_group_store_ready:
  888. store.initialize()
  889. _package._yaoyao_group_store_ready = True
  890. return store
  891. def _invoke_store(method: str, *args: object, **kwargs: object) -> object:
  892. """Run one trusted Store operation and classify only its input failures."""
  893. try:
  894. store = _initialized_store()
  895. except sqlite3.Error as error:
  896. raise GroupStorageAPIError() from error
  897. try:
  898. return getattr(store, method)(*args, **kwargs)
  899. except ValueError as error:
  900. raise GroupInvalidRequest(str(error)) from error
  901. except sqlite3.Error as error:
  902. raise GroupStorageAPIError() from error
  903. async def _store_call(method: str, *args: object, **kwargs: object) -> object:
  904. return await _package._yaoyao_group_runtime_manager.dispatch_store(
  905. method, *args, **kwargs
  906. )
  907. async def _runtime_call(method: str, **kwargs: object) -> object:
  908. return await _package._yaoyao_group_runtime_manager.dispatch(method, **kwargs)
  909. def _command(model: object, *, exclude_unset: bool = False) -> dict[str, object]:
  910. return model.model_dump(
  911. mode="json",
  912. by_alias=True,
  913. exclude_unset=exclude_unset,
  914. )
  915. def _create_room_command(request: CreateRoomRequest) -> dict[str, object]:
  916. command = _command(request)
  917. if "max_reply_rounds" not in request.model_fields_set:
  918. command.pop("maxReplyRounds", None)
  919. if "orchestration_mode" not in request.model_fields_set:
  920. command.pop("orchestrationMode", None)
  921. if "instructions" not in request.model_fields_set:
  922. command.pop("instructions", None)
  923. if "avatar" not in request.model_fields_set:
  924. command.pop("avatar", None)
  925. agents = command.get("agents")
  926. if isinstance(agents, list):
  927. for seed, item in zip(request.agents, agents):
  928. if (
  929. isinstance(item, dict)
  930. and "reply_without_mention" not in seed.model_fields_set
  931. ):
  932. item.pop("replyWithoutMention", None)
  933. if isinstance(item, dict) and "is_host" not in seed.model_fields_set:
  934. item.pop("isHost", None)
  935. if isinstance(item, dict) and "node_id" not in seed.model_fields_set:
  936. item.pop("nodeId", None)
  937. if isinstance(item, dict) and "node_label" not in seed.model_fields_set:
  938. item.pop("nodeLabel", None)
  939. if isinstance(item, dict):
  940. for field, alias in (
  941. ("model", "model"),
  942. ("provider", "provider"),
  943. ("reasoning_effort", "reasoningEffort"),
  944. ("fast_mode", "fastMode"),
  945. ):
  946. if field not in seed.model_fields_set:
  947. item.pop(alias, None)
  948. return command
  949. def _add_agent_command(request: AddAgentRequest) -> dict[str, object]:
  950. command = _command(request)
  951. if "reply_without_mention" not in request.model_fields_set:
  952. command.pop("replyWithoutMention", None)
  953. if "is_host" not in request.model_fields_set:
  954. command.pop("isHost", None)
  955. if "node_id" not in request.model_fields_set:
  956. command.pop("nodeId", None)
  957. if "node_label" not in request.model_fields_set:
  958. command.pop("nodeLabel", None)
  959. for field, alias in (
  960. ("model", "model"),
  961. ("provider", "provider"),
  962. ("reasoning_effort", "reasoningEffort"),
  963. ("fast_mode", "fastMode"),
  964. ):
  965. if field not in request.model_fields_set:
  966. command.pop(alias, None)
  967. return command
  968. def _validated_interaction_id(value: str) -> str:
  969. try:
  970. return normalize_interaction_id(value)
  971. except ValueError as error:
  972. raise GroupInvalidRequest(str(error)) from error
  973. async def capabilities() -> dict[str, object]:
  974. journal_epoch = await _store_call("journal_epoch")
  975. latest_cursor = await _store_call("latest_cursor")
  976. return {
  977. "protocolVersion": PROTOCOL_VERSION,
  978. "journalEpoch": journal_epoch,
  979. "latestCursor": latest_cursor,
  980. "limits": limits_payload(),
  981. "eventTypes": sorted(EVENT_TYPES),
  982. "features": [
  983. "hostFlow", "roomInstructions", "roomAvatar", "globalTopics",
  984. "nodeWorker", "nodeRegistry"
  985. ],
  986. }
  987. async def list_rooms(
  988. limit: int = Query(default=50, ge=1, le=100),
  989. cursor: str | None = Query(default=None, min_length=1, max_length=4096),
  990. archived: bool = Query(default=False),
  991. ) -> dict[str, object]:
  992. page = await _store_call(
  993. "list_rooms", limit=limit, cursor=cursor, archived=archived
  994. )
  995. return {"items": page.items, "nextCursor": page.next_cursor}
  996. async def list_topics(
  997. room_id: UUID,
  998. limit: int = Query(default=50, ge=1, le=100),
  999. cursor: str | None = Query(default=None, min_length=1, max_length=4096),
  1000. archived: bool = Query(default=False),
  1001. ) -> dict[str, object]:
  1002. page = await _store_call(
  1003. "list_topics", str(room_id), limit=limit, cursor=cursor,
  1004. archived=archived,
  1005. )
  1006. return {"items": page.items, "nextCursor": page.next_cursor}
  1007. async def list_global_topics(
  1008. limit: int = Query(default=50, ge=1, le=100),
  1009. cursor: str | None = Query(default=None, min_length=1, max_length=4096),
  1010. ) -> dict[str, object]:
  1011. page = await _store_call(
  1012. "list_global_topics", limit=limit, cursor=cursor
  1013. )
  1014. return {"items": page.items, "nextCursor": page.next_cursor}
  1015. async def list_pinned_topics(
  1016. limit: int = Query(default=100, ge=1, le=100),
  1017. ) -> dict[str, object]:
  1018. page = await _store_call("list_pinned_topics", limit=limit)
  1019. return {"items": page.items, "nextCursor": page.next_cursor}
  1020. async def update_topic(
  1021. room_id: UUID, topic_id: UUID, request: UpdateTopicRequest
  1022. ) -> dict[str, object]:
  1023. return await _runtime_call(
  1024. "update_topic",
  1025. room_id=str(room_id),
  1026. topic_id=str(topic_id),
  1027. command=_command(request, exclude_unset=True),
  1028. )
  1029. async def archive_topic(
  1030. room_id: UUID, topic_id: UUID, request: RequestIDRequest
  1031. ) -> dict[str, object]:
  1032. return await _runtime_call(
  1033. "archive_topic", room_id=str(room_id), topic_id=str(topic_id),
  1034. request_id=str(request.request_id),
  1035. )
  1036. async def restore_topic(
  1037. room_id: UUID, topic_id: UUID, request: RequestIDRequest
  1038. ) -> dict[str, object]:
  1039. return await _runtime_call(
  1040. "restore_topic", room_id=str(room_id), topic_id=str(topic_id),
  1041. request_id=str(request.request_id),
  1042. )
  1043. async def mark_topic_read(
  1044. room_id: UUID, topic_id: UUID, request: MarkTopicReadRequest
  1045. ) -> dict[str, object]:
  1046. return await _runtime_call(
  1047. "mark_topic_read",
  1048. room_id=str(room_id),
  1049. topic_id=str(topic_id),
  1050. command=_command(request, exclude_unset=True),
  1051. )
  1052. async def create_room(request: CreateRoomRequest) -> dict[str, object]:
  1053. return await _runtime_call("create_room", command=_create_room_command(request))
  1054. async def get_room(room_id: UUID) -> dict[str, object]:
  1055. return await _store_call("room_snapshot", str(room_id))
  1056. async def update_room(room_id: UUID, request: UpdateRoomRequest) -> dict[str, object]:
  1057. return await _runtime_call(
  1058. "update_room",
  1059. room_id=str(room_id),
  1060. command=_command(request, exclude_unset=True),
  1061. )
  1062. async def archive_room(room_id: UUID, request: RequestIDRequest) -> dict[str, object]:
  1063. return await _runtime_call(
  1064. "archive_room",
  1065. room_id=str(room_id),
  1066. request_id=str(request.request_id),
  1067. )
  1068. async def restore_room(room_id: UUID, request: RequestIDRequest) -> dict[str, object]:
  1069. return await _runtime_call(
  1070. "restore_room", room_id=str(room_id), request_id=str(request.request_id)
  1071. )
  1072. async def add_agent(room_id: UUID, request: AddAgentRequest) -> dict[str, object]:
  1073. return await _runtime_call(
  1074. "add_agent", room_id=str(room_id), command=_add_agent_command(request)
  1075. )
  1076. async def update_agent(
  1077. room_id: UUID,
  1078. agent_id: UUID,
  1079. request: UpdateAgentRequest,
  1080. ) -> dict[str, object]:
  1081. return await _runtime_call(
  1082. "update_agent",
  1083. room_id=str(room_id),
  1084. agent_id=str(agent_id),
  1085. command=_command(request, exclude_unset=True),
  1086. )
  1087. async def delete_agent(
  1088. room_id: UUID,
  1089. agent_id: UUID,
  1090. request: RequestIDRequest,
  1091. ) -> dict[str, object]:
  1092. return await _runtime_call(
  1093. "delete_agent",
  1094. room_id=str(room_id),
  1095. agent_id=str(agent_id),
  1096. request_id=str(request.request_id),
  1097. )
  1098. async def interrupt_agent(
  1099. room_id: UUID,
  1100. agent_id: UUID,
  1101. request: RequestIDRequest,
  1102. ) -> object:
  1103. return await _runtime_call(
  1104. "interrupt_agent",
  1105. room_id=str(room_id),
  1106. agent_id=str(agent_id),
  1107. request_id=str(request.request_id),
  1108. )
  1109. async def list_messages(
  1110. room_id: UUID,
  1111. topic_id: UUID | None = Query(default=None, alias="topicId"),
  1112. before_seq: int | None = Query(default=None, alias="beforeSeq", ge=1),
  1113. after_seq: int | None = Query(default=None, alias="afterSeq", ge=1),
  1114. limit: int = Query(default=MAX_MESSAGE_PAGE_SIZE, ge=1, le=MAX_MESSAGE_PAGE_SIZE),
  1115. ) -> dict[str, object]:
  1116. items = await _store_call(
  1117. "list_messages",
  1118. str(room_id),
  1119. topic_id=None if topic_id is None else str(topic_id),
  1120. before_seq=before_seq,
  1121. after_seq=after_seq,
  1122. limit=limit,
  1123. )
  1124. return {"items": items}
  1125. async def upload_group_files(
  1126. room_id: UUID,
  1127. files: Annotated[list[UploadFile], File(alias="file")],
  1128. ) -> dict[str, object]:
  1129. canonical_room_id = str(room_id)
  1130. await _store_call("room_snapshot", canonical_room_id)
  1131. return {
  1132. "files": await _persist_group_uploads(canonical_room_id, files),
  1133. }
  1134. async def send_message(room_id: UUID, request: SendMessageRequest) -> dict[str, object]:
  1135. return await _runtime_call(
  1136. "send_message",
  1137. room_id=str(room_id),
  1138. request_id=str(request.request_id),
  1139. client_message_id=str(request.client_message_id),
  1140. topic_id=None if request.topic_id is None else str(request.topic_id),
  1141. content=request.content,
  1142. mention_agent_ids=[str(agent_id) for agent_id in request.mention_agent_ids],
  1143. )
  1144. async def respond_approval(
  1145. room_id: UUID,
  1146. request: ApprovalRequest,
  1147. interaction_id: str = APIPath(min_length=1, max_length=200),
  1148. ) -> object:
  1149. canonical_interaction_id = _validated_interaction_id(interaction_id)
  1150. return await _runtime_call(
  1151. "respond_approval",
  1152. room_id=str(room_id),
  1153. interaction_id=canonical_interaction_id,
  1154. request_id=str(request.request_id),
  1155. choice=request.choice,
  1156. permanent=request.permanent,
  1157. )
  1158. async def respond_clarification(
  1159. room_id: UUID,
  1160. request: ClarificationRequest,
  1161. interaction_id: str = APIPath(min_length=1, max_length=200),
  1162. ) -> object:
  1163. canonical_interaction_id = _validated_interaction_id(interaction_id)
  1164. return await _runtime_call(
  1165. "respond_clarification",
  1166. room_id=str(room_id),
  1167. interaction_id=canonical_interaction_id,
  1168. request_id=str(request.request_id),
  1169. response=request.response,
  1170. )
  1171. def _node_client_id(request: Request) -> str:
  1172. value = request.headers.get("x-yaoyao-node-client", "").strip().lower()
  1173. try:
  1174. canonical = str(UUID(value))
  1175. except ValueError as error:
  1176. raise GroupInvalidRequest("Paired node client identity is required") from error
  1177. if canonical != value:
  1178. raise GroupInvalidRequest("Paired node client identity is required")
  1179. return canonical
  1180. async def node_worker_open_session(
  1181. payload: NodeWorkerOpenRequest,
  1182. request: Request,
  1183. ) -> object:
  1184. return await _node_worker_call(
  1185. "open_session", payload, _node_client_id(request)
  1186. )
  1187. async def register_paired_node(request: Request) -> object:
  1188. try:
  1189. payload = await request.json()
  1190. except Exception as error:
  1191. raise GroupInvalidRequest("Node registration requires JSON") from error
  1192. if not isinstance(payload, dict):
  1193. raise GroupInvalidRequest("Node registration must be an object")
  1194. return await _node_registry_call("register", payload)
  1195. async def list_paired_nodes() -> dict[str, object]:
  1196. nodes = await _node_registry_call("list")
  1197. return {"items": nodes}
  1198. async def refresh_paired_node_identities() -> dict[str, object]:
  1199. nodes = await _node_registry_call("list")
  1200. refreshed: list[dict[str, object]] = []
  1201. failed: list[str] = []
  1202. opener = build_opener(ProxyHandler({}))
  1203. for public in nodes:
  1204. node_id = public.get("nodeId") if isinstance(public, dict) else None
  1205. if not isinstance(node_id, str):
  1206. continue
  1207. try:
  1208. node = await _node_registry_call("get", node_id)
  1209. server_url = node.get("serverUrl")
  1210. access_token = node.get("accessToken")
  1211. if not isinstance(server_url, str) or not isinstance(access_token, str):
  1212. raise ValueError("invalid node route")
  1213. remote_request = URLRequest(
  1214. server_url.rstrip("/") + "/api/profile-identities",
  1215. method="GET",
  1216. headers={
  1217. "Accept": "application/json",
  1218. "Authorization": f"Bearer {access_token}",
  1219. },
  1220. )
  1221. def fetch() -> object:
  1222. with opener.open(remote_request, timeout=35) as response:
  1223. raw = response.read(32 * 1024 * 1024 + 1)
  1224. if len(raw) > 32 * 1024 * 1024:
  1225. raise ValueError("identity response too large")
  1226. return json.loads(raw)
  1227. payload = await asyncio.to_thread(fetch)
  1228. profiles = payload.get("profiles") if isinstance(payload, dict) else None
  1229. refreshed.append(await _node_registry_call("register", {
  1230. "nodeId": node_id,
  1231. "name": node["name"],
  1232. "serverUrl": server_url,
  1233. "fingerprint": node["fingerprint"],
  1234. "accessToken": access_token,
  1235. "profiles": profiles,
  1236. }))
  1237. except Exception:
  1238. failed.append(node_id)
  1239. return {"items": refreshed, "failedNodeIds": failed}
  1240. async def revoke_paired_node(node_id: UUID) -> dict[str, object]:
  1241. removed = await _node_registry_call("revoke", str(node_id))
  1242. if not removed:
  1243. raise GroupInvalidRequest("Paired Hermes node was not found")
  1244. return {"ok": True}
  1245. async def download_paired_node_file(
  1246. node_id: UUID,
  1247. request: Request,
  1248. path: Annotated[str, Query(min_length=1, max_length=8192)],
  1249. ) -> object:
  1250. try:
  1251. node = await _node_registry_call("get", str(node_id))
  1252. except Exception as error:
  1253. raise GroupInvalidRequest("Paired Hermes node was not found") from error
  1254. server_url = node.get("serverUrl")
  1255. access_token = node.get("accessToken")
  1256. if not isinstance(server_url, str) or not isinstance(access_token, str):
  1257. raise GroupInvalidRequest("Paired Hermes node route is invalid")
  1258. target = server_url.rstrip("/") + "/api/node-files?" + urlencode({"path": path})
  1259. headers = {
  1260. "Accept": "application/octet-stream",
  1261. "Authorization": f"Bearer {access_token}",
  1262. }
  1263. requested_range = request.headers.get("range", "")
  1264. if requested_range and re.fullmatch(r"bytes=\d*-\d*", requested_range):
  1265. headers["Range"] = requested_range
  1266. remote_request = URLRequest(target, method="GET", headers=headers)
  1267. opener = build_opener(ProxyHandler({}))
  1268. try:
  1269. response = await asyncio.to_thread(opener.open, remote_request, timeout=60)
  1270. except HTTPError as error:
  1271. status = error.code if 400 <= error.code <= 599 else 502
  1272. error.close()
  1273. return JSONResponse(
  1274. status_code=status,
  1275. content={"error": "Remote node file request was rejected"},
  1276. )
  1277. except (URLError, TimeoutError, OSError) as error:
  1278. raise GroupInvalidRequest("Remote node file is unavailable") from error
  1279. def body_stream():
  1280. try:
  1281. while True:
  1282. chunk = response.read(256 * 1024)
  1283. if not chunk:
  1284. break
  1285. yield chunk
  1286. finally:
  1287. response.close()
  1288. outgoing_headers = {"Cache-Control": "private, no-store"}
  1289. for source, target_name in (
  1290. ("Content-Length", "Content-Length"),
  1291. ("Content-Range", "Content-Range"),
  1292. ("Accept-Ranges", "Accept-Ranges"),
  1293. ("Content-Disposition", "Content-Disposition"),
  1294. ):
  1295. value = response.headers.get(source)
  1296. if value and "\r" not in value and "\n" not in value:
  1297. outgoing_headers[target_name] = value
  1298. return StreamingResponse(
  1299. body_stream(),
  1300. status_code=getattr(response, "status", 200),
  1301. media_type=response.headers.get("Content-Type", "application/octet-stream"),
  1302. headers=outgoing_headers,
  1303. )
  1304. async def node_worker_submit_prompt(
  1305. runtime_session_id: str,
  1306. payload: NodeWorkerPromptRequest,
  1307. request: Request,
  1308. ) -> dict[str, object]:
  1309. await _node_worker_call(
  1310. "submit_prompt", runtime_session_id, payload, _node_client_id(request)
  1311. )
  1312. return {"status": "streaming"}
  1313. async def node_worker_interrupt(
  1314. runtime_session_id: str,
  1315. request: Request,
  1316. ) -> dict[str, object]:
  1317. await _node_worker_call(
  1318. "interrupt", runtime_session_id, _node_client_id(request)
  1319. )
  1320. return {"status": "interrupted"}
  1321. async def node_worker_close_session(
  1322. runtime_session_id: str,
  1323. request: Request,
  1324. ) -> dict[str, object]:
  1325. closed = await _node_worker_call(
  1326. "close_session", runtime_session_id, _node_client_id(request)
  1327. )
  1328. return {"closed": bool(closed)}
  1329. async def node_worker_respond_approval(
  1330. runtime_session_id: str,
  1331. payload: NodeWorkerApprovalRequest,
  1332. request: Request,
  1333. ) -> dict[str, object]:
  1334. resolved = await _node_worker_call(
  1335. "respond_approval",
  1336. runtime_session_id,
  1337. payload,
  1338. _node_client_id(request),
  1339. )
  1340. return {"resolved": resolved}
  1341. async def node_worker_respond_clarification(
  1342. payload: NodeWorkerClarificationRequest,
  1343. request: Request,
  1344. ) -> dict[str, object]:
  1345. status = await _node_worker_call(
  1346. "respond_clarification", payload, _node_client_id(request)
  1347. )
  1348. return {"status": status}
  1349. async def node_worker_events(
  1350. request: Request,
  1351. after: int = Query(default=0, ge=0),
  1352. runtime_session_id: str | None = Query(
  1353. default=None, alias="runtimeSessionId", min_length=1, max_length=4096
  1354. ),
  1355. limit: int = Query(default=100, ge=1, le=256),
  1356. ) -> object:
  1357. return await _node_worker_call(
  1358. "events",
  1359. after=after,
  1360. runtime_id=runtime_session_id,
  1361. limit=limit,
  1362. client_id=_node_client_id(request),
  1363. )
  1364. async def node_worker_attach_file(
  1365. runtime_session_id: str,
  1366. request: Request,
  1367. ) -> object:
  1368. encoded_name = request.headers.get("x-file-name-b64", "")
  1369. mime_type = request.headers.get("x-mime-type", "application/octet-stream")
  1370. try:
  1371. name = base64.urlsafe_b64decode(
  1372. encoded_name + "=" * (-len(encoded_name) % 4)
  1373. ).decode("utf-8")
  1374. except (ValueError, UnicodeDecodeError) as error:
  1375. raise GroupInvalidRequest("Attachment name header is invalid") from error
  1376. content = await request.body()
  1377. if not content or len(content) > _MAX_GROUP_UPLOAD_FILE_BYTES:
  1378. raise GroupInvalidRequest("Remote attachment content is invalid")
  1379. return await _node_worker_call(
  1380. "attach_file",
  1381. runtime_session_id,
  1382. name=name,
  1383. mime_type=mime_type,
  1384. content=content,
  1385. client_id=_node_client_id(request),
  1386. )
  1387. async def stream_events(websocket: WebSocket) -> None:
  1388. """Delegate the read-only event channel to the authenticated streamer."""
  1389. allowed, close_code = _stream_module.websocket_upgrade_allowed(websocket)
  1390. if not allowed:
  1391. await websocket.close(code=close_code)
  1392. return
  1393. if not await asyncio.to_thread(_plugin_runtime_enabled):
  1394. await websocket.close(code=_stream_module.PLUGIN_DISABLED_CLOSE_CODE)
  1395. return
  1396. async def stream_authorized(
  1397. websocket: WebSocket, store_provider: Callable[[], object]
  1398. ) -> None:
  1399. await _stream_module.stream_authorized_group_events(
  1400. websocket,
  1401. store_provider,
  1402. availability_provider=_plugin_runtime_enabled,
  1403. )
  1404. try:
  1405. manager = _package._yaoyao_group_runtime_manager
  1406. await manager.stream_store(websocket, stream_authorized)
  1407. except RuntimeUnavailableError:
  1408. await websocket.close(code=1013, reason="Group runtime is unavailable")
  1409. def _build_router() -> APIRouter:
  1410. """Build the immutable route table once per resolved plugin directory."""
  1411. built = APIRouter(
  1412. prefix="/v1",
  1413. tags=["yaoyao-group"],
  1414. route_class=GroupAPIRoute,
  1415. lifespan=_router_lifespan,
  1416. )
  1417. built.add_api_route("/capabilities", capabilities, methods=["GET"])
  1418. built.add_api_route("/rooms", list_rooms, methods=["GET"])
  1419. built.add_api_route("/topics", list_global_topics, methods=["GET"])
  1420. built.add_api_route("/topics/pinned", list_pinned_topics, methods=["GET"])
  1421. built.add_api_route("/rooms", create_room, methods=["POST"])
  1422. built.add_api_route("/rooms/{room_id}", get_room, methods=["GET"])
  1423. built.add_api_route("/rooms/{room_id}", update_room, methods=["PATCH"])
  1424. built.add_api_route("/rooms/{room_id}", archive_room, methods=["DELETE"])
  1425. built.add_api_route("/rooms/{room_id}/restore", restore_room, methods=["POST"])
  1426. built.add_api_route("/rooms/{room_id}/topics", list_topics, methods=["GET"])
  1427. built.add_api_route(
  1428. "/rooms/{room_id}/topics/{topic_id}", update_topic, methods=["PATCH"]
  1429. )
  1430. built.add_api_route(
  1431. "/rooms/{room_id}/topics/{topic_id}", archive_topic, methods=["DELETE"]
  1432. )
  1433. built.add_api_route(
  1434. "/rooms/{room_id}/topics/{topic_id}/restore", restore_topic,
  1435. methods=["POST"],
  1436. )
  1437. built.add_api_route("/rooms/{room_id}/agents", add_agent, methods=["POST"])
  1438. built.add_api_route(
  1439. "/rooms/{room_id}/agents/{agent_id}", update_agent, methods=["PATCH"]
  1440. )
  1441. built.add_api_route(
  1442. "/rooms/{room_id}/agents/{agent_id}", delete_agent, methods=["DELETE"]
  1443. )
  1444. built.add_api_route(
  1445. "/rooms/{room_id}/agents/{agent_id}/interrupt",
  1446. interrupt_agent,
  1447. methods=["POST"],
  1448. )
  1449. built.add_api_route(
  1450. "/rooms/{room_id}/topics/{topic_id}/read",
  1451. mark_topic_read,
  1452. methods=["PATCH"],
  1453. )
  1454. built.add_api_route(
  1455. "/rooms/{room_id}/uploads", upload_group_files, methods=["POST"]
  1456. )
  1457. built.add_api_route("/rooms/{room_id}/messages", list_messages, methods=["GET"])
  1458. built.add_api_route("/rooms/{room_id}/messages", send_message, methods=["POST"])
  1459. built.add_api_route(
  1460. "/rooms/{room_id}/interactions/{interaction_id}/approval",
  1461. respond_approval,
  1462. methods=["POST"],
  1463. )
  1464. built.add_api_route(
  1465. "/rooms/{room_id}/interactions/{interaction_id}/clarification",
  1466. respond_clarification,
  1467. methods=["POST"],
  1468. )
  1469. built.add_api_route("/nodes", register_paired_node, methods=["POST"])
  1470. built.add_api_route("/nodes", list_paired_nodes, methods=["GET"])
  1471. built.add_api_route(
  1472. "/nodes/refresh-identities",
  1473. refresh_paired_node_identities,
  1474. methods=["POST"],
  1475. )
  1476. built.add_api_route(
  1477. "/nodes/{node_id}", revoke_paired_node, methods=["DELETE"]
  1478. )
  1479. built.add_api_route(
  1480. "/nodes/{node_id}/files", download_paired_node_file, methods=["GET"]
  1481. )
  1482. built.add_api_route(
  1483. "/node-worker/sessions", node_worker_open_session, methods=["POST"]
  1484. )
  1485. built.add_api_route(
  1486. "/node-worker/sessions/{runtime_session_id}/prompt",
  1487. node_worker_submit_prompt,
  1488. methods=["POST"],
  1489. )
  1490. built.add_api_route(
  1491. "/node-worker/sessions/{runtime_session_id}/interrupt",
  1492. node_worker_interrupt,
  1493. methods=["POST"],
  1494. )
  1495. built.add_api_route(
  1496. "/node-worker/sessions/{runtime_session_id}",
  1497. node_worker_close_session,
  1498. methods=["DELETE"],
  1499. )
  1500. built.add_api_route(
  1501. "/node-worker/sessions/{runtime_session_id}/approval",
  1502. node_worker_respond_approval,
  1503. methods=["POST"],
  1504. )
  1505. built.add_api_route(
  1506. "/node-worker/clarification",
  1507. node_worker_respond_clarification,
  1508. methods=["POST"],
  1509. )
  1510. built.add_api_route(
  1511. "/node-worker/events", node_worker_events, methods=["GET"]
  1512. )
  1513. built.add_api_route(
  1514. "/node-worker/sessions/{runtime_session_id}/attachments",
  1515. node_worker_attach_file,
  1516. methods=["POST"],
  1517. )
  1518. built.add_api_websocket_route("/events", stream_events)
  1519. return built
  1520. with _bootstrap_lock:
  1521. router = getattr(_package, "_yaoyao_group_router", None)
  1522. if router is None:
  1523. router = _build_router()
  1524. _package._yaoyao_group_router = router