group_node_worker.py 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341
  1. """Authenticated remote-execution facade for a paired Hermes node.
  2. The public HTTP authentication boundary lives in the YaoYao Web node proxy.
  3. This module deliberately exposes only the same stable Gateway operations used
  4. by the native group orchestrator and keeps a bounded, cursor-based event journal
  5. so an owning Hermes can drive a remote Agent without holding an inbound socket.
  6. """
  7. from __future__ import annotations
  8. from collections import deque
  9. import base64
  10. import copy
  11. import threading
  12. from typing import Any, Literal
  13. from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
  14. from .group_gateway import GroupGatewayAdapter, SessionIdentity
  15. MAX_NODE_EVENTS = 4096
  16. MAX_NODE_EVENT_PAGE = 256
  17. MAX_NODE_STRING = 4096
  18. class NodeWorkerModel(BaseModel):
  19. model_config = ConfigDict(populate_by_name=True, extra="forbid")
  20. class NodeWorkerOpenRequest(NodeWorkerModel):
  21. profile: str = Field(min_length=1, max_length=100)
  22. title: str = Field(min_length=1, max_length=500)
  23. cwd: str = Field(default="", max_length=MAX_NODE_STRING)
  24. stored_session_id: str | None = Field(
  25. default=None, alias="storedSessionId", max_length=MAX_NODE_STRING
  26. )
  27. model: str | None = Field(default=None, max_length=MAX_NODE_STRING)
  28. provider: str | None = Field(default=None, max_length=MAX_NODE_STRING)
  29. reasoning_effort: str | None = Field(
  30. default=None, alias="reasoningEffort", max_length=32
  31. )
  32. fast_mode: bool | None = Field(default=None, alias="fastMode")
  33. @field_validator(
  34. "profile", "title", "stored_session_id", "model", "provider",
  35. "reasoning_effort",
  36. )
  37. @classmethod
  38. def normalize_strings(cls, value: str | None) -> str | None:
  39. if value is None:
  40. return None
  41. normalized = value.strip()
  42. if not normalized:
  43. raise ValueError("string value must not be blank")
  44. return normalized
  45. @model_validator(mode="after")
  46. def validate_model_pair(self) -> "NodeWorkerOpenRequest":
  47. if (self.model is None) != (self.provider is None):
  48. raise ValueError("model and provider must be set together")
  49. return self
  50. class NodeWorkerPromptRequest(NodeWorkerModel):
  51. text: str = Field(min_length=1, max_length=1_000_000)
  52. @field_validator("text")
  53. @classmethod
  54. def normalize_text(cls, value: str) -> str:
  55. if not value.strip():
  56. raise ValueError("text must not be blank")
  57. return value
  58. class NodeWorkerApprovalRequest(NodeWorkerModel):
  59. choice: Literal["once", "session", "always", "deny"]
  60. class NodeWorkerClarificationRequest(NodeWorkerModel):
  61. request_id: str = Field(alias="requestId", min_length=1, max_length=MAX_NODE_STRING)
  62. answer: str = Field(min_length=1, max_length=1_000_000)
  63. class NodeWorkerError(RuntimeError):
  64. """Raised when the worker lifecycle or cursor contract is invalid."""
  65. class NodeGatewayWorker:
  66. """Own one local Gateway adapter and a bounded replayable event journal."""
  67. def __init__(self, *, gateway: GroupGatewayAdapter | None = None) -> None:
  68. self._condition = threading.Condition(threading.RLock())
  69. self._cursor = 0
  70. self._events: deque[dict[str, object]] = deque(maxlen=MAX_NODE_EVENTS)
  71. self._runtime_clients: dict[str, str] = {}
  72. self._clarification_clients: dict[str, str] = {}
  73. self._closed = False
  74. self._gateway = gateway or GroupGatewayAdapter(on_event=self._on_event)
  75. def open_session(
  76. self, request: NodeWorkerOpenRequest, client_id: str = "local"
  77. ) -> dict[str, object]:
  78. self._require_open()
  79. configuration = {
  80. "model": request.model,
  81. "provider": request.provider,
  82. "reasoning_effort": request.reasoning_effort,
  83. "fast": request.fast_mode,
  84. }
  85. if request.stored_session_id is None:
  86. identity = self._gateway.create_session(
  87. request.profile,
  88. request.title,
  89. request.cwd,
  90. [],
  91. configuration,
  92. )
  93. else:
  94. identity = self._gateway.resume_session(
  95. request.profile, request.stored_session_id
  96. )
  97. with self._condition:
  98. client = self._client_id(client_id)
  99. self._runtime_clients[identity.runtime_id] = client
  100. for event in self._events:
  101. if event.get("runtimeSessionId") == identity.runtime_id:
  102. event["clientId"] = client
  103. if event.get("type") == "clarify.request":
  104. payload = event.get("payload")
  105. if isinstance(payload, dict):
  106. request_id = payload.get("request_id") or payload.get(
  107. "requestId"
  108. )
  109. if isinstance(request_id, str):
  110. self._clarification_clients[request_id] = client
  111. return self._identity(identity)
  112. def submit_prompt(
  113. self,
  114. runtime_id: str,
  115. request: NodeWorkerPromptRequest,
  116. client_id: str = "local",
  117. ) -> None:
  118. self._require_open()
  119. self._gateway.submit_prompt(
  120. self._owned_runtime(runtime_id, client_id), request.text
  121. )
  122. def interrupt(self, runtime_id: str, client_id: str = "local") -> None:
  123. self._require_open()
  124. self._gateway.interrupt(self._owned_runtime(runtime_id, client_id))
  125. def close_session(self, runtime_id: str, client_id: str = "local") -> bool:
  126. self._require_open()
  127. return self._gateway.close(self._owned_runtime(runtime_id, client_id))
  128. def respond_approval(
  129. self,
  130. runtime_id: str,
  131. request: NodeWorkerApprovalRequest,
  132. client_id: str = "local",
  133. ) -> int:
  134. self._require_open()
  135. return self._gateway.respond_approval(
  136. self._owned_runtime(runtime_id, client_id), request.choice
  137. )
  138. def respond_clarification(
  139. self,
  140. request: NodeWorkerClarificationRequest,
  141. client_id: str = "local",
  142. ) -> str:
  143. self._require_open()
  144. client = self._client_id(client_id)
  145. with self._condition:
  146. if self._clarification_clients.get(request.request_id) != client:
  147. raise NodeWorkerError("Clarification does not belong to this client")
  148. return self._gateway.respond_clarification(request.request_id, request.answer)
  149. def attach_file(
  150. self,
  151. runtime_id: str,
  152. *,
  153. name: str,
  154. mime_type: str,
  155. content: bytes,
  156. client_id: str = "local",
  157. ) -> dict[str, object]:
  158. self._require_open()
  159. runtime = self._owned_runtime(runtime_id, client_id)
  160. if not isinstance(name, str) or not name.strip() or len(name) > 240:
  161. raise NodeWorkerError("Attachment name is invalid")
  162. if not isinstance(mime_type, str) or not mime_type.strip() or len(mime_type) > 200:
  163. raise NodeWorkerError("Attachment MIME type is invalid")
  164. if not isinstance(content, bytes) or not content or len(content) > 25 * 1024 * 1024:
  165. raise NodeWorkerError("Attachment content is invalid")
  166. result = self._gateway.request(
  167. "file.attach",
  168. {
  169. "session_id": runtime,
  170. "name": name.strip(),
  171. "data_url": (
  172. f"data:{mime_type.strip()};base64,"
  173. + base64.b64encode(content).decode("ascii")
  174. ),
  175. },
  176. )
  177. if not isinstance(result, dict):
  178. raise NodeWorkerError("Gateway attachment response is invalid")
  179. return result
  180. def events(
  181. self,
  182. *,
  183. after: int,
  184. runtime_id: str | None,
  185. limit: int,
  186. client_id: str = "local",
  187. ) -> dict[str, object]:
  188. if isinstance(after, bool) or not isinstance(after, int) or after < 0:
  189. raise NodeWorkerError("after must be a non-negative integer")
  190. if isinstance(limit, bool) or not isinstance(limit, int):
  191. raise NodeWorkerError("limit must be an integer")
  192. bounded_limit = max(1, min(limit, MAX_NODE_EVENT_PAGE))
  193. selected_runtime = (
  194. None if runtime_id is None else self._runtime_id(runtime_id)
  195. )
  196. client = self._client_id(client_id)
  197. with self._condition:
  198. client_events = [
  199. event for event in self._events
  200. if event.get("clientId") == client
  201. ]
  202. oldest = (
  203. int(client_events[0]["cursor"])
  204. if client_events else self._cursor + 1
  205. )
  206. reset = bool(client_events) and after > 0 and after < oldest - 1
  207. selected = [
  208. copy.deepcopy(event)
  209. for event in client_events
  210. if int(event["cursor"]) > after
  211. and (
  212. selected_runtime is None
  213. or event["runtimeSessionId"] == selected_runtime
  214. )
  215. ][:bounded_limit]
  216. items = []
  217. for event in selected:
  218. event.pop("clientId", None)
  219. items.append(event)
  220. return {
  221. "items": items,
  222. "latestCursor": self._cursor,
  223. "oldestCursor": oldest,
  224. "reset": reset,
  225. }
  226. def shutdown(self) -> None:
  227. with self._condition:
  228. if self._closed:
  229. return
  230. self._closed = True
  231. self._gateway.shutdown()
  232. def _on_event(
  233. self, runtime_id: str, event_type: str, payload: dict[str, Any]
  234. ) -> None:
  235. with self._condition:
  236. if self._closed:
  237. return
  238. self._cursor += 1
  239. self._events.append(
  240. {
  241. "cursor": self._cursor,
  242. "runtimeSessionId": runtime_id,
  243. "type": event_type,
  244. "payload": copy.deepcopy(payload),
  245. "clientId": self._runtime_clients.get(runtime_id, "local"),
  246. }
  247. )
  248. if event_type == "clarify.request":
  249. request_id = payload.get("request_id") or payload.get("requestId")
  250. if isinstance(request_id, str):
  251. self._clarification_clients[request_id] = (
  252. self._runtime_clients.get(runtime_id, "local")
  253. )
  254. self._condition.notify_all()
  255. def _require_open(self) -> None:
  256. with self._condition:
  257. if self._closed:
  258. raise NodeWorkerError("Node worker is closed")
  259. @staticmethod
  260. def _runtime_id(value: str) -> str:
  261. if not isinstance(value, str):
  262. raise NodeWorkerError("runtimeSessionId must be a string")
  263. normalized = value.strip()
  264. if not normalized or len(normalized) > MAX_NODE_STRING:
  265. raise NodeWorkerError("runtimeSessionId is invalid")
  266. return normalized
  267. @staticmethod
  268. def _client_id(value: str) -> str:
  269. if not isinstance(value, str):
  270. raise NodeWorkerError("Node client identity is invalid")
  271. normalized = value.strip().lower()
  272. if not normalized or len(normalized) > 128:
  273. raise NodeWorkerError("Node client identity is invalid")
  274. return normalized
  275. def _owned_runtime(self, runtime_id: str, client_id: str) -> str:
  276. runtime = self._runtime_id(runtime_id)
  277. client = self._client_id(client_id)
  278. with self._condition:
  279. if self._runtime_clients.get(runtime) != client:
  280. raise NodeWorkerError("Runtime does not belong to this client")
  281. return runtime
  282. @staticmethod
  283. def _identity(identity: SessionIdentity) -> dict[str, object]:
  284. if not isinstance(identity, SessionIdentity):
  285. raise NodeWorkerError("Gateway returned an invalid session identity")
  286. return {
  287. "storedSessionId": identity.stored_id,
  288. "runtimeSessionId": identity.runtime_id,
  289. "running": identity.running,
  290. }
  291. __all__ = [
  292. "MAX_NODE_EVENT_PAGE",
  293. "NodeGatewayWorker",
  294. "NodeWorkerApprovalRequest",
  295. "NodeWorkerClarificationRequest",
  296. "NodeWorkerError",
  297. "NodeWorkerOpenRequest",
  298. "NodeWorkerPromptRequest",
  299. ]