gateway_agent.py 81 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522
  1. """The AIAgent surface main's HermesCLI uses, backed by the shared gateway session (CALLMAP §3.2-3.3).
  2. ``run_conversation`` submits ``prompt.submit`` and replays the gateway's event stream, on the
  3. calling (agent) thread, into the SAME callbacks HermesCLI passed to ``AIAgent`` on main, then
  4. returns a dict shaped like ``AIAgent.run_conversation``'s. The CLI process never builds an agent,
  5. never runs a tool and never writes ``state.db``: the turn runs in the gateway.
  6. Event contract: wave_a.md (frozen). Every frame is a gateway ``event`` with params
  7. ``{type, session_id, execution_generation, admission_id?, payload}``.
  8. """
  9. from __future__ import annotations
  10. import json
  11. import logging
  12. import queue
  13. import threading
  14. import time
  15. import uuid
  16. from contextlib import suppress
  17. from hermes_cli.gateway_client import GatewayClientError, GatewayRPCError
  18. from hermes_cli.gateway_connection import DISCONNECTED, NOT_SENT, CallStopped, lost_before
  19. logger = logging.getLogger(__name__)
  20. # How long a turn waits for its settlement after an interrupt (main: cli_chat_turn_mixin 10 s).
  21. INTERRUPT_SETTLE_SECONDS = 10.0
  22. _POLL = 0.1
  23. # ``steer()`` / ``redirect()``'s reply when the owner consumed the text as a typed voice stop (TUI-26):
  24. # truthy, so a caller that only asks "taken?" never re-queues it.
  25. VOICE_STOPPED = "voice_stopped"
  26. _RESULT_DEFAULTS = {
  27. "final_response": "", "failed": False, "partial": False, "error": None, "failure_reason": None,
  28. "completed": True, "interrupted": False, "interrupt_message": None, "api_calls": 0,
  29. "pending_steer": None, "last_reasoning": None, "response_previewed": False,
  30. "response_transformed": False, "pre_transform_response": None, "billing_block": None,
  31. "auxiliary_usage": {},
  32. }
  33. # ``session.usage`` / ``session.stats`` (wave_a2 contract, session-cumulative) → the agent attributes
  34. # main's status bar, spinner (``↓ N tok``) and /usage read off ``AIAgent``.
  35. _COUNTER_FROM_USAGE = {
  36. "session_input_tokens": "input_tokens", "session_output_tokens": "output_tokens",
  37. "session_prompt_tokens": "prompt_tokens", "session_completion_tokens": "completion_tokens",
  38. "session_total_tokens": "total_tokens", "session_cache_read_tokens": "cache_read_tokens",
  39. "session_cache_write_tokens": "cache_write_tokens", "session_reasoning_tokens": "reasoning_tokens",
  40. "session_api_calls": "api_calls",
  41. }
  42. class _CompressorView:
  43. """``agent.context_compressor`` as the status bar / banner read it (plain attributes)."""
  44. def __init__(self):
  45. self.last_prompt_tokens = 0
  46. self.last_real_prompt_tokens = None
  47. self.context_length = 0
  48. self.compression_count = 0
  49. self._config_context_length = None
  50. self.threshold_tokens = 0
  51. class _Turn:
  52. """One ``run_conversation``; what each consumer got of the reply's current segment (``shown``: the
  53. terminal, ``spoken``: ``stream_callback``) and the closed segments and interims (``seen``), for the
  54. settlement after a replay gap."""
  55. def __init__(self, session_id):
  56. self.session_id, self.admission = session_id, None
  57. # Parts, joined on read: ``+=`` on an attribute copies the whole segment per delta (quadratic).
  58. self._shown, self._spoken = [], []
  59. self.seen, self.answered, self.gapped = set(), set(), False
  60. @property
  61. def shown(self):
  62. return "".join(self._shown)
  63. @property
  64. def spoken(self):
  65. return "".join(self._spoken)
  66. def close_segment(self):
  67. self.seen |= {self.shown.strip(), self.spoken.strip()}
  68. self._shown, self._spoken = [], []
  69. class GatewayAgent:
  70. """Gateway-backed stand-in for ``run_agent.AIAgent`` (constructed at the same call site)."""
  71. platform = "cli"
  72. _supports_active_turn_redirect = True
  73. def __init__(self, *, session_db=None, session_id=None, model=None, provider=None, base_url=None,
  74. api_mode=None, max_iterations=90, quiet_mode=True, tool_progress_mode="all",
  75. reasoning_config=None, service_tier=None, clarify_callback=None, connection_callback=None,
  76. connection_update_callback=None,
  77. reasoning_callback=None, thinking_callback=None, tool_progress_callback=None,
  78. tool_start_callback=None, tool_complete_callback=None, stream_delta_callback=None,
  79. tool_gen_callback=None, notice_callback=None, notice_clear_callback=None,
  80. reaction_callback=None, interim_assistant_callback=None, connection=None,
  81. push_reasoning=False, model_confirm_callback=None, modal_withdraw_callback=None,
  82. one_turn=False, one_turn_reasoning=None, one_turn_alias="", **_ignored):
  83. conn = connection or getattr(session_db, "connection", None)
  84. if conn is None:
  85. raise GatewayClientError("Gateway session unavailable; no local fallback")
  86. self.connection = conn
  87. self._session_db = session_db
  88. self.session_id = session_id
  89. self.model = model or ""
  90. self.provider = provider or ""
  91. self.base_url = base_url or ""
  92. self.api_mode = api_mode
  93. self.api_key = None # never on this side of the wire
  94. self.max_iterations = max_iterations
  95. self.quiet_mode = quiet_mode
  96. self._service_tier = None
  97. self.clarify_callback = clarify_callback
  98. # The manage_connections card: the gateway runs the operation and streams connection.request /
  99. # connection.update; the card answers through connection_respond / connection_retry.
  100. self.connection_callback = connection_callback
  101. self.connection_update_callback = connection_update_callback
  102. self._reasoning_callback = None
  103. self._show_reasoning_sent = None
  104. self.thinking_callback = thinking_callback
  105. self.tool_progress_callback = tool_progress_callback
  106. self.tool_start_callback = tool_start_callback
  107. self.tool_complete_callback = tool_complete_callback
  108. self.stream_delta_callback = stream_delta_callback
  109. self.tool_gen_callback = tool_gen_callback
  110. self.notice_callback = notice_callback
  111. self.notice_clear_callback = notice_clear_callback
  112. self.reaction_callback = reaction_callback
  113. self.interim_assistant_callback = interim_assistant_callback
  114. # The CLI's confirm prompt for the owner's model-guard refusal; None where nobody can answer (-q).
  115. self.model_confirm_callback = model_confirm_callback
  116. # Closes the CLI's open modal for one server-request method when the gateway withdraws it
  117. # (``request.cancel``: another viewer answered, the turn ended); called off the agent thread.
  118. self.modal_withdraw_callback = modal_withdraw_callback
  119. self._open_request = None # (request id, method) of the server request a modal is answering
  120. # Set by the CLI after construction: a ``session.control.update`` mid-turn (a tool moved the goal
  121. # or loop) marks its mirrored managers stale; the dock re-reads them off this thread.
  122. self.control_update_callback = None
  123. self.suppress_status_output = False
  124. self._print_fn = None
  125. # Inert private attributes main's CLI writes (CALLMAP §3.2).
  126. self._last_flushed_db_idx = 0
  127. self._session_messages: list = []
  128. self._db_flush_scan_prefix = None
  129. self._persist_user_message_idx = self._persist_user_message_override = None
  130. self._persist_user_message_timestamp = None
  131. self._pending_cli_user_message = None
  132. self._voice_turn_pending = False
  133. self._auto_load_skills_result = None
  134. self._auto_load_skills_resolved = False
  135. self._session_db_created = True
  136. self._fallback_activated = False
  137. self._rate_limited_until = None
  138. self._primary_runtime = None
  139. self._interrupt_requested = False
  140. self._active_children: list = []
  141. self._turn_ask_index = None
  142. self._usage_stale = False
  143. self._current_task_id = self._current_turn_id = self._current_api_request_id = ""
  144. self._memory_manager = None
  145. self._memory_store = None
  146. self._checkpoint_mgr = None
  147. self.context_compressor = _CompressorView()
  148. self._reset_session_figures()
  149. # Main's store type, the one /new, /resume and /branch swap in: a read-only mirror of the gateway's
  150. # todo snapshot (``_set_todos``), read by the pet's done-plan beat.
  151. from tools.todo_tool import TodoStore
  152. self._todo_store = TodoStore()
  153. # Part of the _compress_context seam: it sets the owner's report here and compress_now reads it.
  154. self.compression_summary = None
  155. self._generation = None
  156. self._admission = None
  157. self._turn = None # a turn a later one replaced stops taking frames
  158. self._epoch = None # the connection epoch this turn was submitted on
  159. self._interrupt_sent_at = None
  160. self._rate_limit_state = None
  161. self._config_context_length = None
  162. # Session-scope settings the gateway applies (its turn renders tools in this mode, its agent asks
  163. # for this effort): written once main's rebuilt agent is ready, then on every change.
  164. self._tool_progress_mode = "all"
  165. self.tool_progress_mode = tool_progress_mode
  166. self._reasoning_config = None
  167. # Only a user-picked effort (/reasoning, a model pick's --reasoning) is committed at build; the
  168. # config-resolved level must never override the session's frozen launch policy on resume.
  169. # ``reasoning_pushed``: the commit landed, so the CLI stops re-sending it on every later rebuild.
  170. self.reasoning_pushed = False
  171. if push_reasoning:
  172. self.reasoning_pushed = self.pin_reasoning(reasoning_config)
  173. else:
  174. self._reasoning_config = reasoning_config
  175. # Main's /moa rebuilds its agent on the MoA virtual provider for one turn (the session's info
  176. # below then overwrites ``model``): that preset rides the turn's submit as its model_override.
  177. self._moa_preset = model if provider == "moa" else None
  178. # ``/model --once``: chat retires the agent that switch_model touched and builds this one.
  179. # Capture the pick, and the alias it resolved through, before ``_apply_info`` copies the session
  180. # model over it.
  181. self._turn_route = self._route_off_session(model, provider, one_turn_alias) if one_turn else None
  182. self._taken_turn_route = None # the pick the admission being sent took (``_take_turn_route``)
  183. # ``/model B --once --reasoning X``: X rides that admission's ``model_override``, never a session pin.
  184. self._turn_reasoning = one_turn_reasoning if one_turn else None
  185. self._apply_info(self._state().info)
  186. if self._turn_route:
  187. self.model = model # the resolved model, never the alias the admission sends
  188. if self._turn_route.get("provider"):
  189. self.provider = self._turn_route["provider"]
  190. self.reasoning_callback = reasoning_callback
  191. self.service_tier = service_tier
  192. state = self._state()
  193. state.usage_listeners.append(self.apply_session_usage)
  194. state.request_listeners.append(self._on_request_withdrawn)
  195. if state.usage:
  196. self.apply_session_usage(state.usage)
  197. # -- session-scope settings ------------------------------------------------------------------
  198. @property
  199. def tool_progress_mode(self):
  200. return self._tool_progress_mode
  201. @tool_progress_mode.setter
  202. def tool_progress_mode(self, mode):
  203. """``/verbose`` / ``/focus``: ``config.set verbose`` with the explicit mode (never ``cycle``, which
  204. could drift from the CLI's own cycle)."""
  205. if mode == self._tool_progress_mode or mode not in {"off", "new", "all", "verbose"}:
  206. self._tool_progress_mode = mode
  207. return
  208. self._tool_progress_mode = mode
  209. try:
  210. self.connection.call("config.set", session_id=self.session_id, key="verbose", value=mode)
  211. except GatewayClientError as exc:
  212. logger.debug("config.set verbose failed: %s", exc)
  213. @property
  214. def reasoning_config(self):
  215. return self._reasoning_config
  216. @reasoning_config.setter
  217. def reasoning_config(self, config):
  218. """/new's re-derived effort and a one-turn restore: ``session.mutate reasoning`` when it differs from
  219. the session's effort (an inherited level stays inherited)."""
  220. self._set_reasoning(config, explicit=False)
  221. def pin_reasoning(self, config):
  222. """``/reasoning <level>`` (session scope; main rebuilds its agent with the new config) and a model
  223. pick's ``--reasoning``: always ``session.mutate reasoning``, even when the session already runs that
  224. level by inheritance, so it becomes the session's own choice. True when the owner committed it."""
  225. return self._set_reasoning(config, explicit=True)
  226. def stage_turn_reasoning(self, config):
  227. """``/model B --once --reasoning X``: X for the one-turn admission only (its ``model_override``).
  228. Nothing is sent to the session."""
  229. self._reasoning_config = config
  230. self._turn_reasoning = _effort_word(config)
  231. def restore_reasoning(self, config):
  232. """A one-turn restore: the level goes back on this object only. The session was never written."""
  233. self._reasoning_config = config
  234. self._turn_reasoning = None
  235. def _set_reasoning(self, config, *, explicit):
  236. self._reasoning_config = config
  237. effort = _effort_word(config)
  238. if effort is None:
  239. return False
  240. info = self._state().info or {}
  241. if not explicit and info.get("reasoning_effort") == effort:
  242. return True
  243. try:
  244. snapshot = self.connection.call("session.resume", session_id=self.session_id)
  245. # A policy mutation is generation-fenced: the owner refuses it without the generation.
  246. self.connection.call("session.mutate", session_id=self.session_id, request_id=uuid.uuid4().hex,
  247. expected_revision=snapshot["revision"],
  248. expected_generation=snapshot["execution_generation"], operation="reasoning",
  249. payload={"effort": effort})
  250. info["reasoning_effort"] = effort
  251. return True
  252. except (GatewayClientError, KeyError, TypeError) as exc:
  253. logger.debug("session.mutate reasoning failed: %s", exc)
  254. return False
  255. def _route_off_session(self, model, provider="", alias=""):
  256. """``{model, provider}`` the turn sends when the session runs another route, else None.
  257. ``alias``, the ``model_aliases`` entry the pick resolved through, is sent instead of the bare
  258. model: two aliases may name one model at different endpoints, so the owner must not re-resolve
  259. it. An alias makes even the session's own model a one-turn override."""
  260. state = self._state()
  261. if not model or not (state.info or {}).get("model") or (state.runs_route(model, provider) and not alias):
  262. return None
  263. return {"model": alias or model, **({"provider": provider} if provider else {})}
  264. def switch_model(self, new_model, new_provider="", api_key="", base_url="", api_mode="", capabilities=None, *,
  265. once=False, restore=False, alias=""):
  266. """Session-scoped ``/model`` and /resume commit ``session.mutate model``.
  267. ``once=True`` does not write the session. The next ``chat`` builds a new agent; that
  268. constructor carries the pick, because this agent is retired when the route signature
  269. changes. ``restore=True`` only puts the previous model back on this object and clears the
  270. one-turn route. The admission already has its ``model_override``.
  271. "Already on this route" is the session row, not ``self.model`` (a one-turn pick sets
  272. ``self.model`` without committing). A session switch of that same target still mutates
  273. on the generation fence.
  274. A guarded target the owner refuses with ``confirmation_required`` is re-sent with its token
  275. only on the user's yes to ``model_confirm_callback``: a no returns False with nothing
  276. written; with no prompt the refusal raises. Any refusal raises: main's callers roll their
  277. own fields back."""
  278. if once or restore:
  279. # ``alias``: the ``model_aliases`` entry a ``--once`` pick resolved through (``_route_off_session``).
  280. self._turn_route = None if restore else self._route_off_session(new_model, new_provider, alias)
  281. if restore:
  282. self._turn_reasoning = None
  283. if new_model:
  284. self.model = new_model
  285. if new_provider:
  286. self.provider = new_provider
  287. return True
  288. if new_model == self.model and (not new_provider or new_provider == self.provider):
  289. if self._route_off_session(new_model, new_provider) is None:
  290. self._turn_route = None
  291. return True
  292. from hermes_cli.gateway_mutations import model_refusal_text
  293. payload = {"model": new_model, **({"provider": new_provider} if new_provider else {})}
  294. snapshot = self.connection.call("session.resume", session_id=self.session_id)
  295. fence = dict(session_id=self.session_id, operation="model", expected_revision=snapshot["revision"],
  296. expected_generation=snapshot["execution_generation"])
  297. result = self.connection.call("session.mutate", request_id=uuid.uuid4().hex, payload=payload, **fence) or {}
  298. if result.get("status") == "confirmation_required":
  299. if self.model_confirm_callback is None:
  300. raise GatewayClientError(model_refusal_text(result))
  301. if not self.model_confirm_callback(result):
  302. return False
  303. # The refusal wrote nothing: the same fence is re-sent with the owner's token.
  304. result = self.connection.call("session.mutate", request_id=uuid.uuid4().hex,
  305. payload={**payload, "confirm": result["confirm"]}, **fence) or {}
  306. if result.get("status") == "confirmation_required":
  307. raise GatewayClientError(model_refusal_text(result, confirmed=True))
  308. state = self._state()
  309. try:
  310. state.adopt_snapshot(self.connection.call("session.resume", session_id=self.session_id))
  311. except (GatewayClientError, KeyError, TypeError) as exc:
  312. # Committed: the next turn runs on the new model, so main must not roll its fields back.
  313. logger.warning("session.resume after the committed model switch failed: %s", exc)
  314. # A rebuilt stand-in reads the session's info: it must show the committed model.
  315. provider = result.get("provider") or new_provider
  316. state.info = {**(state.info or {}), "model": result.get("model") or new_model,
  317. **({"provider": provider} if provider else {})}
  318. # The session now runs this route, so a leftover one-turn override must not ride the next submit.
  319. self._turn_route = None
  320. self._apply_info(state.info)
  321. return True
  322. # -- session identity ----------------------------------------------------------------------
  323. @property
  324. def _todo_store(self):
  325. return self._todos
  326. @_todo_store.setter
  327. def _todo_store(self, store):
  328. """Main swaps in a fresh ``TodoStore`` after /new, /resume and /branch move ``session_id`` (and the
  329. constructor builds one): it starts with the gateway's snapshot of that session, so a resumed
  330. plan is there before its next ``todo.updated``."""
  331. self._todos = store
  332. snapshot = self._state().todo_state
  333. if snapshot:
  334. self._set_todos(snapshot)
  335. @property
  336. def session_id(self):
  337. return self._session_id
  338. @session_id.setter
  339. def session_id(self, value):
  340. """Main repoints ``agent.session_id`` on /new, /resume and /branch: attach this viewer to that
  341. gateway session (idempotent) and read its state from then on."""
  342. previous = getattr(self, "_session_id", None)
  343. self._session_id = value
  344. if previous is None or value == previous or not value:
  345. return
  346. # The session left behind keeps its own figures: a later frame of its must not repaint this one.
  347. left = self.connection.state(previous)
  348. with suppress(ValueError):
  349. left.usage_listeners.remove(self.apply_session_usage)
  350. with suppress(ValueError):
  351. left.request_listeners.remove(self._on_request_withdrawn)
  352. store = self._session_db
  353. if store is not None and hasattr(store, "attach"):
  354. try:
  355. store.attach(value)
  356. except GatewayClientError as exc:
  357. logger.debug("session.resume %s failed: %s", value, exc)
  358. else:
  359. try:
  360. self.connection.call("session.resume", session_id=value)
  361. except GatewayClientError as exc:
  362. logger.debug("session.resume %s failed: %s", value, exc)
  363. state = self._state()
  364. if self.apply_session_usage not in state.usage_listeners:
  365. state.usage_listeners.append(self.apply_session_usage)
  366. if self._on_request_withdrawn not in state.request_listeners:
  367. state.request_listeners.append(self._on_request_withdrawn)
  368. self._apply_info(state.info)
  369. if state.usage:
  370. self.apply_session_usage(state.usage)
  371. self._sync_show_reasoning()
  372. notice = self._lost_turn_notice()
  373. if notice:
  374. self._emit_print(notice)
  375. # -- reasoning display -------------------------------------------------------------------
  376. @property
  377. def reasoning_callback(self):
  378. return self._reasoning_callback
  379. @reasoning_callback.setter
  380. def reasoning_callback(self, callback):
  381. """Main installs a reasoning sink at construction and on ``/reasoning show|hide`` / verbose; the
  382. sink's presence is what makes the agent ask the provider for reasoning. The gateway agent
  383. gets the same switch: the session's ``show_reasoning`` display flag, sent on each change."""
  384. self._reasoning_callback = callback
  385. self._sync_show_reasoning()
  386. def _sync_show_reasoning(self):
  387. """Sent unless this viewer already set the value: a session it attaches (/new, /resume, /branch)
  388. may hold another viewer's "1". A "0" outlives a redial (a restarted gateway starts with the
  389. flag unset, read as off); a "1" is set again on each gateway life."""
  390. show = self._reasoning_callback is not None
  391. sent = self._show_reasoning_sent
  392. if sent and sent[:2] == (self.session_id, show) and (not show or sent[2] == self.connection.epoch):
  393. return
  394. try:
  395. self.connection.call("config.set", session_id=self.session_id, key="show_reasoning",
  396. value="1" if show else "0", timeout=10)
  397. except GatewayClientError as exc:
  398. logger.debug("config.set show_reasoning failed: %s", exc)
  399. return
  400. self._show_reasoning_sent = (self.session_id, show, self.connection.epoch)
  401. @property
  402. def service_tier(self):
  403. return self._service_tier
  404. @service_tier.setter
  405. def service_tier(self, tier):
  406. """Main rebuilds AIAgent(service_tier=...) after ``/fast``; the gateway agent gets the same tier
  407. as the session's override (``config.set service_tier``), sent when it differs from the last
  408. one sent for this session. The session's own default (None at first build) is left alone."""
  409. self._service_tier = tier
  410. # Remembered on the session's shared state: /fast rebuilds this stand-in, the session stays.
  411. state = self._state()
  412. wanted = tier or "normal"
  413. sent = getattr(state, "service_tier_sent", None)
  414. if wanted == sent or (sent is None and not tier):
  415. return
  416. try:
  417. self.connection.call("config.set", session_id=self.session_id, key="service_tier",
  418. value=wanted, timeout=10)
  419. except GatewayClientError as exc:
  420. logger.debug("config.set service_tier failed: %s", exc)
  421. return
  422. state.service_tier_sent = wanted
  423. # -- snapshot-backed reads ---------------------------------------------------------------
  424. def _state(self):
  425. return self.connection.state(self.session_id)
  426. def _apply_info(self, info):
  427. info = info or {}
  428. if info.get("model"):
  429. self.model = info["model"]
  430. if info.get("provider"):
  431. self.provider = info["provider"]
  432. if info.get("context_length"):
  433. self.context_compressor.context_length = int(info["context_length"])
  434. @property
  435. def tools(self):
  436. """Tool schemas the gateway session will load (``info.tools`` {toolset: [names]})."""
  437. groups = (self._state().info or {}).get("tools") or {}
  438. names = [name for members in groups.values() for name in (members or [])]
  439. return [{"type": "function", "function": {"name": name}} for name in names]
  440. @property
  441. def valid_tool_names(self):
  442. return {tool["function"]["name"] for tool in self.tools}
  443. def get_rate_limit_state(self):
  444. return self._rate_limit_state
  445. def apply_session_usage(self, usage):
  446. """Install one session-cumulative usage dict (the ``session.usage`` event / ``session.stats``
  447. result) on main's attributes. Plain assignments: the render thread reads them lock-free."""
  448. if not isinstance(usage, dict):
  449. return
  450. for attr, key in _COUNTER_FROM_USAGE.items():
  451. value = usage.get(key)
  452. if isinstance(value, int) and not isinstance(value, bool):
  453. setattr(self, attr, value)
  454. compressor = self.context_compressor
  455. if isinstance(usage.get("last_prompt_tokens"), int):
  456. compressor.last_prompt_tokens = usage["last_prompt_tokens"]
  457. if usage.get("context_length"):
  458. compressor.context_length = int(usage["context_length"])
  459. if "config_context_length" in usage:
  460. pin = usage.get("config_context_length")
  461. compressor._config_context_length = self._config_context_length = pin if isinstance(pin, int) else None
  462. if isinstance(usage.get("compression_count"), int):
  463. compressor.compression_count = usage["compression_count"]
  464. source = usage.get("context_source")
  465. if source is not None:
  466. # context_display_source(): a "local_estimate" reading is a shown value != the real one.
  467. compressor.last_real_prompt_tokens = (
  468. None if source == "provider_usage" else compressor.last_prompt_tokens + 1)
  469. if isinstance(usage.get("context_tokens"), int):
  470. self._context_tokens = usage["context_tokens"]
  471. self._anchor_display()
  472. latency, tps = usage.get("avg_latency_s"), usage.get("tokens_per_s")
  473. if isinstance(latency, (int, float)) and latency > 0 and isinstance(tps, (int, float)):
  474. # The bar averages these deques (mean latency, sum/sum velocity): one aligned sample each.
  475. self._api_latency_history = [float(latency)]
  476. self._api_output_history = [float(tps) * float(latency)]
  477. if "rate_limit" in usage:
  478. self._rate_limit_state = _rate_limit_state(usage.get("rate_limit"))
  479. if usage.get("model"):
  480. self.model = usage["model"]
  481. if usage.get("provider"):
  482. self.provider = usage["provider"]
  483. # -- no-ops: the gateway owns persistence, prompt cache, memory and clients --------------
  484. def _flush_messages_to_session_db(self, *a, **k):
  485. return None
  486. def _persist_session(self, *a, **k):
  487. return None
  488. def _ensure_db_session(self, *a, **k):
  489. return None
  490. def _invalidate_system_prompt(self, *a, **k):
  491. return None
  492. def _reset_session_figures(self):
  493. """Zero the per-session figures main's bar, spinner and /usage read (context length stays)."""
  494. for attr in _COUNTER_FROM_USAGE:
  495. setattr(self, attr, 0)
  496. compressor = self.context_compressor
  497. compressor.last_prompt_tokens, compressor.last_real_prompt_tokens, compressor.compression_count = 0, None, 0
  498. self._context_tokens = self._turn_calls_base = 0
  499. self._turn_base_usage_anchor = self._turn_api_calls = None
  500. self._api_latency_history, self._api_output_history = [], []
  501. def reset_session_state(self, *a, **k):
  502. """/new, /resume and /branch, after the ``session_id`` switch: drop the previous session's
  503. figures, then show the gateway's for this one (``session.stats``, else its cached
  504. ``session.usage``). A brand-new session (no transcript, no usage yet) reads zero until its
  505. first turn publishes, without a round trip."""
  506. self._reset_session_figures()
  507. state = self._state()
  508. if not (state.messages or state.usage):
  509. return
  510. if not self._refresh_stats() and state.usage:
  511. self.apply_session_usage(state.usage)
  512. def release_clients(self, *a, **k):
  513. return None
  514. def clear_interrupt(self, *a, **k):
  515. self._interrupt_requested = False
  516. def shutdown_memory_provider(self, *a, **k):
  517. return None
  518. def close(self, *a, **k):
  519. return None
  520. def _restore_primary_runtime(self, *a, **k):
  521. return None
  522. def _summarize_api_error(self, exc):
  523. return str(exc)[:300]
  524. # -- controls ------------------------------------------------------------------------------
  525. def interrupt(self, message=None):
  526. """``session.interrupt`` for the running generation; ``message`` stays CLI-side (main
  527. re-queues it as the next turn itself)."""
  528. self._interrupt_requested = True
  529. if self._interrupt_sent_at is None:
  530. self._interrupt_sent_at = time.monotonic()
  531. generation = self._generation
  532. if generation is None:
  533. generation = self._state().execution_generation
  534. try:
  535. self.connection.call("session.interrupt", session_id=self.session_id,
  536. execution_generation=generation, timeout=5)
  537. except Exception as exc: # health: allow BLE001 -- the settle wait below bounds a lost interrupt
  538. logger.debug("session.interrupt failed: %s", exc)
  539. def hard_interrupt(self, message=None, tool_reason=None):
  540. self.interrupt(message)
  541. def _correct(self, verb, text):
  542. """-> ``True`` (accepted), ``False`` (not taken: the caller queues the text), or
  543. ``"voice_stopped"`` (TUI-26: the owner took a bare stop phrase as the end of this LOCAL
  544. session's voice chat; the text is consumed and reaches no turn, so it is never re-queued)."""
  545. generation = self._generation
  546. if generation is None:
  547. return False
  548. try:
  549. result = self.connection.call(f"session.{verb}", session_id=self.session_id, text=text,
  550. execution_generation=generation)
  551. except GatewayClientError:
  552. return False
  553. if (result or {}).get("voice_stopped") is True:
  554. from agent.i18n import t
  555. self._emit_print(t("cli.voice.stop_phrase_typed"))
  556. return VOICE_STOPPED
  557. return (result or {}).get("status") in {"queued", "redirected"}
  558. def _compress_context(self, messages, system_message=None, *, approx_tokens=None, focus_topic=None,
  559. force=True, verbatim_tail=None, **_kw):
  560. """Main's manual ``/compress`` seam (``compress_now``) as ``session.mutate compress``: the
  561. gateway summarizes and commits; the returned transcript is the gateway's compacted history.
  562. ``verbatim_tail`` rows are stamped as stored, so ``compress_now`` does not rejoin them.
  563. The gateway's own report (``summary``: flags and note (with the reason)) is kept for ``compress_now``;
  564. a ``noop`` answer (a failed summary or nothing removable) committed nothing, so the history,
  565. the tail and the compression count stay as they were."""
  566. from agent.context_compressor import _DB_PERSISTED_MARKER
  567. from agent.conversation_compression import COMPACTION_STATUS
  568. from hermes_cli.gateway_client import COMPRESS_RPC_TIMEOUT
  569. payload = {}
  570. if focus_topic:
  571. payload["focus"] = focus_topic
  572. if verbatim_tail:
  573. payload["partial"] = True
  574. payload["keep_last"] = max(1, sum(1 for m in verbatim_tail if m.get("role") == "user"))
  575. self._emit_print(COMPACTION_STATUS)
  576. self.compression_summary = None
  577. snapshot = self.connection.call("session.resume", session_id=self.session_id)
  578. result = self.connection.call("session.mutate", timeout=COMPRESS_RPC_TIMEOUT, session_id=self.session_id,
  579. request_id=uuid.uuid4().hex, expected_revision=snapshot["revision"],
  580. expected_generation=snapshot["execution_generation"],
  581. operation="compress", payload=payload) or {}
  582. if isinstance(result.get("summary"), dict):
  583. self.compression_summary = result["summary"]
  584. if result.get("status") == "noop":
  585. return list(messages), system_message
  586. for row in verbatim_tail or ():
  587. row[_DB_PERSISTED_MARKER] = True
  588. after = self.connection.call("session.resume", session_id=self.session_id)
  589. self._state().adopt_snapshot(after)
  590. compressor = self.context_compressor
  591. compressor.compression_count += 1
  592. compressor.last_prompt_tokens = -1
  593. self._turn_base_usage_anchor = None
  594. return [{k: v for k, v in m.items() if k != "row_id"} for m in after.get("messages") or []
  595. if not m.get("archived")], system_message
  596. def steer(self, text):
  597. return self._correct("steer", text)
  598. def redirect(self, text):
  599. accepted = self._correct("redirect", text)
  600. if accepted is True:
  601. # Main's turn then answers the redirect row first (the interrupted call has no usage), so
  602. # its anchor is priced through that row: it, not the original ask, is the turn's ask.
  603. self._turn_ask_index = None
  604. return accepted
  605. # -- the turn ------------------------------------------------------------------------------
  606. def _submit_params(self, user_message, persist_user_message, turn_author):
  607. attachments = None
  608. if isinstance(user_message, list):
  609. # Main's native image turn: OpenAI content parts built from local files. The gateway takes
  610. # text plus staged attachments and routes the images itself (native or described).
  611. user_message, attachments = self._stage_content_parts(user_message)
  612. if isinstance(persist_user_message, list):
  613. persist_user_message = user_message
  614. text = persist_user_message if isinstance(persist_user_message, str) else user_message
  615. params = {"session_id": self.session_id, "submission_id": uuid.uuid4().hex, "text": text}
  616. if attachments:
  617. params["attachments"] = attachments
  618. if isinstance(user_message, str) and user_message != text:
  619. params["api_text"] = user_message
  620. if turn_author:
  621. params["turn_author"] = turn_author
  622. if self._voice_turn_pending:
  623. params["voice_turn"] = True
  624. staged = self._pending_cli_user_message
  625. if isinstance(staged, dict) and staged.get("display_kind"):
  626. params["display_kind"] = staged["display_kind"]
  627. if getattr(self, "_finite", False):
  628. params["finite"] = True
  629. if self.clarify_callback is not None:
  630. # Main's batch panel answers the clarify tool's whole question set (one ``clarify`` request).
  631. params["clarify_batch"] = True
  632. info = self._state().info or {}
  633. pending = self._take_turn_route()
  634. if pending:
  635. # /model --once: this admission alone runs the pick. The session row stays put.
  636. params["model_override"] = pending
  637. elif self._moa_preset and (info.get("provider"), info.get("model")) != ("moa", self._moa_preset):
  638. # /moa one-shot: this admission alone runs the preset (unless it is the session's own
  639. # route); the session's route is untouched.
  640. params["model_override"] = {"model": self._moa_preset, "provider": "moa"}
  641. return params
  642. def _take_turn_route(self):
  643. """The ``/model --once`` pick for the admission being built, consumed here: one admission carries
  644. it, even when a later ``run_conversation`` submits while this one's ``prompt.submit`` still blocks.
  645. A refusal that admitted nothing (``session_busy``) puts it back with ``_give_back_turn_route``.
  646. Staging already compared the pick with the session's route (``_route_off_session``), so it is not
  647. compared again: its ``model`` may be an alias spelled like the session's model, and the owner runs a
  648. plain pick of the session's own route on the session's endpoint and key (``one_turn_runtime``)."""
  649. pending, reasoning = self._turn_route, self._turn_reasoning
  650. self._turn_route = self._turn_reasoning = self._taken_turn_route = None
  651. if not pending:
  652. return None
  653. self._taken_turn_route = (pending, reasoning)
  654. return {**pending, **({"reasoning": reasoning} if reasoning else {})}
  655. def _give_back_turn_route(self):
  656. taken, self._taken_turn_route = getattr(self, "_taken_turn_route", None), None
  657. if taken and self._turn_route is None:
  658. self._turn_route, self._turn_reasoning = taken
  659. def _stage_content_parts(self, parts):
  660. """``[{type: text}, {type: image_url, image_url: {url: data:...}}]`` -> (text, attachments): each
  661. image is staged on the owner with ``image.attach_bytes`` (bytes read here, locally, by main's
  662. ``build_native_content_parts``); main's ``[Image attached at: <local path>]`` hints are dropped
  663. because the gateway names its own staged copies."""
  664. texts, attachments = [], []
  665. for part in parts:
  666. if not isinstance(part, dict):
  667. continue
  668. if part.get("type") == "text":
  669. lines = str(part.get("text") or "").splitlines()
  670. texts.append("\n".join(ln for ln in lines if not ln.startswith("[Image attached")).strip())
  671. elif part.get("type") == "image_url":
  672. url = (part.get("image_url") or {}).get("url") if isinstance(part.get("image_url"), dict) else None
  673. if isinstance(url, str) and url.startswith("data:image/"):
  674. staged = self.connection.call("image.attach_bytes", session_id=self.session_id, content_base64=url)
  675. attachments.append({"path": staged["path"], "mime": staged["mime"]})
  676. return "\n\n".join(t for t in texts if t), attachments
  677. def run_conversation(self, user_message, conversation_history=None, stream_callback=None,
  678. task_id=None, persist_user_message=None, turn_author=None, **_kw):
  679. turn = self._turn = _Turn(self.session_id) # first: a turn main gave up on stops consuming
  680. history = list(conversation_history or [])
  681. self._turn_ask_index = len(history) # the staged ask's row in this turn's transcript
  682. self._turn_api_calls = None
  683. self._turn_calls_base = self.session_api_calls
  684. self._usage_stale = True
  685. self._interrupt_requested = False
  686. self._interrupt_sent_at = None
  687. from hermes_cli.gateway_tools_notify import take_admitted_turn
  688. adopted = take_admitted_turn(self, persist_user_message if isinstance(persist_user_message, str)
  689. else user_message)
  690. if adopted is not None:
  691. # A turn the gateway already admitted and is running (its frames are queued). A recovered
  692. # ``/queue`` turn missed some frames: its reply is completed from the receipt.
  693. receipt = adopted
  694. turn.gapped = bool(adopted.get("recovered"))
  695. else:
  696. self._drain_stale()
  697. self._taken_turn_route = None
  698. try:
  699. # Inside the try: staging an image is a gateway call, and its failure is a failed turn.
  700. # Building the params consumes a ``/model --once`` pick (``_take_turn_route``).
  701. notice = self._prepare_submit(turn)
  702. if notice:
  703. return self._unadmitted(history, user_message, notice)
  704. params = self._submit_params(user_message, persist_user_message, turn_author)
  705. if self._stop(turn)():
  706. raise CallStopped("prompt.submit")
  707. receipt = self.connection.call("prompt.submit", **{**params, "session_id": turn.session_id})
  708. except CallStopped: # main moved on (a later turn, /new, Ctrl-C's bound) before the submit
  709. self._give_back_turn_route() # nothing was sent: the pick is still owed
  710. return self._failed(history, user_message, "Stopped before the prompt was sent; nothing was sent.")
  711. except GatewayRPCError as exc:
  712. # The owner answered and refused: not a lost connection. Only its own site code
  713. # (session_busy: send again) is a verdict; any other refusal stays unclassified.
  714. busy = str(exc) == "session_busy"
  715. if busy:
  716. # Nothing was admitted: the resend carries the pick (the CLI keeps its restore).
  717. self._give_back_turn_route()
  718. return self._failed(history, user_message, str(exc),
  719. failure_reason="session_busy" if busy else None, retryable=busy)
  720. except GatewayClientError as exc:
  721. if str(exc) == NOT_SENT:
  722. return self._unadmitted(history, user_message, str(exc))
  723. return self._failed(history, user_message, str(exc), failure_reason="gateway_connection")
  724. if (receipt or {}).get("voice_stopped") is True:
  725. return self._voice_stopped(history)
  726. self._epoch = getattr(self.connection, "epoch", None)
  727. turn.admission = self._admission = (receipt or {}).get("admission_id")
  728. if receipt and receipt.get("execution_generation") is not None:
  729. self._generation = receipt["execution_generation"]
  730. starts: dict = {}
  731. try:
  732. settled = (adopted or {}).get("receipt")
  733. outcome = {"_receipt": settled} if settled else self._pump(stream_callback, starts, turn)
  734. finally:
  735. if self._owns(turn):
  736. self._generation_done()
  737. if isinstance(outcome, Exception) and self._owns(turn):
  738. return self._failed(history, user_message, str(outcome) or DISCONNECTED,
  739. failure_reason="gateway_connection")
  740. result = self._result(history, user_message, outcome, turn) if self._owns(turn) else None
  741. if not self._owns(turn): # a later turn or a session switch took over: it reads and paints nothing
  742. return self._failed(history, user_message, "A later turn took over this terminal.")
  743. if turn.gapped:
  744. self._paint_owed(turn, result, outcome, stream_callback)
  745. return result
  746. def _drain_stale(self):
  747. """Frames left from an earlier turn of this viewer (a late settlement) are not this turn's. A
  748. ``/queue`` admission's start among them is remembered: that turn is painted after this one."""
  749. from hermes_cli.gateway_tools_notify import missed_start
  750. while True:
  751. try:
  752. frame = self.connection.events.get_nowait()
  753. except queue.Empty:
  754. return
  755. if isinstance(frame, Exception):
  756. if lost_before(frame, getattr(self.connection, "epoch", None)):
  757. continue # a connection a reconnect already replaced
  758. self.connection.events.put(frame)
  759. return
  760. params = frame.get("params") if isinstance(frame, dict) else None
  761. if isinstance(params, dict) and params.get("session_id") == self.session_id:
  762. missed_start(self._state(), params)
  763. def _generation_done(self):
  764. self._generation = None
  765. def _expired(self):
  766. return self._interrupt_sent_at is not None and time.monotonic() - self._interrupt_sent_at > INTERRUPT_SETTLE_SECONDS
  767. def _owns(self, turn):
  768. return self._turn is turn and self.session_id == turn.session_id
  769. def _stop(self, turn):
  770. """The ``abandon`` of a turn's blocking reads: it lost the terminal, or Ctrl-C's settle bound passed."""
  771. return lambda: not self._owns(turn) or self._expired()
  772. def _lost(self, turn):
  773. """The ``abandon`` of a turn's end-of-turn reads (its receipt, the cumulative stats): only losing the
  774. terminal stops them. Past Ctrl-C's settle bound they still run, bounded by their own timeouts."""
  775. return lambda: not self._owns(turn)
  776. def _prepare_submit(self, turn):
  777. """Before a prompt is sent: re-attach after a replay gap, give a redialled (restarted) owner the
  778. reasoning flag again, and return the notice of a turn lost in that restart: a prompt queued
  779. behind it would wait with no end, so it is refused until ``/discard``."""
  780. state = self._state()
  781. if state.gaps != state.attached_gaps: # a replay gap between turns retired the subscription
  782. self.connection.reattach(turn.session_id, abandon=self._stop(turn))
  783. self.connection.start()
  784. self._sync_show_reasoning()
  785. notice = self._lost_turn_notice()
  786. return f"Your message was not sent.\n{notice}" if notice else ""
  787. def _lost_turn_notice(self):
  788. from hermes_cli.gateway_chat_view import pending_lines
  789. pending = self._state().pending
  790. return "\n".join(pending_lines(pending)) if any(row["status"] == "unknown" for row in pending) else ""
  791. def _pump(self, stream_callback, starts, turn):
  792. """Dispatch frames until this admission's ``message.complete``; returns its payload, or the
  793. transport error (disconnect)."""
  794. events = self.connection.events
  795. while self._owns(turn):
  796. if self._expired():
  797. return {"status": "interrupted", "outcome": "cancelled", "_settle_timeout": True}
  798. try:
  799. frame = events.get(timeout=_POLL)
  800. except queue.Empty:
  801. continue
  802. if not self._owns(turn):
  803. with events.mutex: # the later turn's frame goes back where it was
  804. events.queue.appendleft(frame)
  805. break
  806. if isinstance(frame, Exception):
  807. if lost_before(frame, self._epoch):
  808. continue # the previous connection's loss, already reported; this turn is live
  809. return frame
  810. params = frame.get("params") if isinstance(frame, dict) else None
  811. if not isinstance(params, dict) or params.get("session_id") != self.session_id:
  812. continue
  813. if frame.get("method") in _SERVER_REQUESTS and "id" in frame:
  814. self._answer_request(frame)
  815. continue
  816. kind, payload = params.get("type"), params.get("payload") or {}
  817. admission = params.get("admission_id") or (payload.get("admission_id") if isinstance(payload, dict) else None)
  818. if self._admission and admission and admission != self._admission:
  819. from hermes_cli.gateway_tools_notify import missed_start
  820. missed_start(self._state(), params) # a /queue turn run ahead of this one: painted after it
  821. continue
  822. if params.get("execution_generation") is not None:
  823. self._generation = params["execution_generation"]
  824. self._state().execution_generation = params["execution_generation"]
  825. if kind == "message.complete":
  826. return payload
  827. if kind == "session.replay_gap":
  828. outcome = self._recover(turn)
  829. if outcome is not None:
  830. return outcome
  831. continue
  832. try:
  833. self._dispatch(kind, payload, stream_callback, starts)
  834. except Exception:
  835. logger.debug("event %s dispatch failed", kind, exc_info=True)
  836. return None
  837. def _recover(self, turn):
  838. """``gateway_replay_gap``: re-attach, answer the controls the hole hid, stop painting live text. A
  839. turn the snapshot no longer lists settles from its receipt; None waits for the live completion."""
  840. from hermes_cli.gateway_replay_gap import settled
  841. lost, stop = GatewayClientError("session_replay_gap: " + DISCONNECTED), self._stop(turn)
  842. try:
  843. snapshot = self.connection.reattach(turn.session_id, abandon=stop)
  844. row = next((r for r in snapshot.get("pending") or [] if r.get("admission_id") == turn.admission), {})
  845. if row.get("status") == "unknown":
  846. return lost # its completion was the one the hole lost: no other is owed
  847. turn.gapped |= row.get("status") != "queued" # one still queued lost nothing
  848. self._restore_connection_card(snapshot.get("pending_connection"))
  849. for prompt in snapshot.get("prompts") or []:
  850. if row.get("status") == "started" and prompt.get("execution_generation") == row.get("execution_generation") \
  851. and prompt.get("prompt_id") not in turn.answered and not stop():
  852. turn.answered.add(prompt.get("prompt_id"))
  853. try:
  854. self._dispatch(f"{prompt.get('kind')}.request", prompt, None, {})
  855. except Exception: # a broken modal is a skipped answer, never a failed turn
  856. logger.debug("control %s dispatch failed", prompt.get("prompt_id"), exc_info=True)
  857. if row or not turn.admission or stop():
  858. return None
  859. receipt = self.connection.call("prompt.receipt", session_id=turn.session_id, admission_id=turn.admission,
  860. include_result=True, abandon=stop)
  861. except CallStopped:
  862. return None
  863. except GatewayClientError:
  864. return lost
  865. verdict = settled(receipt or {})
  866. return {"_receipt": receipt} if verdict else lost if verdict is None else None
  867. def _dispatch(self, kind, payload, stream_callback, starts):
  868. handler = _HANDLERS.get(kind)
  869. if handler is not None:
  870. handler(self, payload, stream_callback, starts)
  871. # event handlers (agent thread) ------------------------------------------------------------
  872. def _on_delta(self, payload, stream_callback, starts):
  873. text, turn = payload.get("text"), self._turn
  874. if not isinstance(text, str):
  875. return self._close_segment(starts, separator=True)
  876. if turn.gapped:
  877. return # live text stopped at the replay gap; the settlement shows the reply once
  878. if self.stream_delta_callback is not None:
  879. self.stream_delta_callback(text)
  880. turn._shown.append(text)
  881. if stream_callback is not None:
  882. stream_callback(text)
  883. turn._spoken.append(text)
  884. def _close_segment(self, starts, separator=False):
  885. """A segment boundary: the ``text: None`` separator, or a later boundary when it fell in a gap."""
  886. turn = self._turn
  887. if self.stream_delta_callback is not None and (separator or any(turn._shown)):
  888. self.stream_delta_callback(None)
  889. turn.close_segment()
  890. def _on_interim(self, payload, stream_callback, starts):
  891. text = payload.get("text")
  892. self._close_segment(starts)
  893. self._turn.seen.add(str(text or "").strip())
  894. if self.interim_assistant_callback is not None:
  895. self.interim_assistant_callback(text, already_streamed=bool(payload.get("already_streamed")))
  896. elif text and str(text).strip():
  897. self._emit_print(text)
  898. def _on_tool_generating(self, payload, stream_callback, starts):
  899. if self.tool_gen_callback is not None:
  900. self.tool_gen_callback(payload.get("name"))
  901. def _on_tool_progress(self, payload, stream_callback, starts):
  902. if self.tool_progress_callback is not None:
  903. self.tool_progress_callback("tool.progress", payload.get("name"), payload.get("message"), None,
  904. tool_call_id=payload.get("tool_id"), progress=payload.get("progress"),
  905. total=payload.get("total"), percent=payload.get("percent"))
  906. def _on_tool_start(self, payload, stream_callback, starts):
  907. self._close_segment(starts)
  908. name = payload.get("name") or payload.get("tool_name") or "tool"
  909. args = payload.get("args") if isinstance(payload.get("args"), dict) else {}
  910. call_id = payload.get("tool_id") or payload.get("tool_call_id") or ""
  911. starts[call_id] = time.monotonic()
  912. if self._usage_stale:
  913. # Main's counters move right after each API call, before its tools run (the spinner's
  914. # `↓ N tok` beside a tool or approval); the gateway's next session.usage frame comes only
  915. # at the next step, so the first tool of each batch reads session.stats once.
  916. self._usage_stale = False
  917. self._refresh_stats()
  918. if self.tool_progress_callback is not None:
  919. from agent.display import build_tool_preview
  920. self.tool_progress_callback("tool.started", name, build_tool_preview(name, args), args)
  921. # No tool_start_callback: main's snapshots the local FS for inline diffs; the gateway
  922. # snapshots before its tool writes and ships ``tool.complete.inline_diff`` instead.
  923. def _on_tool_complete(self, payload, stream_callback, starts):
  924. name = payload.get("name") or payload.get("tool_name") or "tool"
  925. args = payload.get("args") if isinstance(payload.get("args"), dict) else {}
  926. call_id = payload.get("tool_id") or payload.get("tool_call_id") or ""
  927. result = payload.get("result")
  928. duration = payload.get("duration_s")
  929. if duration is None:
  930. started = starts.pop(call_id, None)
  931. duration = (time.monotonic() - started) if started is not None else 0.0
  932. if self.tool_progress_callback is not None:
  933. self.tool_progress_callback("tool.completed", name, None, None, duration=duration,
  934. is_error=bool(payload.get("is_error")), result=result)
  935. self._usage_stale = True
  936. from hermes_cli.gateway_tools import mark_dirty
  937. mark_dirty() # a terminal/process call may have started or stopped a background process
  938. if name == "todo":
  939. self._todo_from_result(result)
  940. diff = payload.get("inline_diff")
  941. if isinstance(diff, str) and diff:
  942. from cli import _cprint
  943. from hermes_cli.cli_modern_layout import diff_printer
  944. emit = diff_printer(_cprint)
  945. for line in diff.rstrip("\n").splitlines():
  946. emit(line)
  947. if name == "delegate_task" and self.tool_complete_callback is not None:
  948. self.tool_complete_callback(call_id, name, args, result)
  949. elif self.tool_complete_callback is not None:
  950. self.tool_complete_callback(call_id, name, args, result)
  951. def _todo_from_result(self, result):
  952. try:
  953. data = json.loads(result) if isinstance(result, str) else result
  954. except ValueError:
  955. return
  956. if isinstance(data, dict):
  957. self._set_todos(data)
  958. def _on_todo(self, payload, stream_callback, starts):
  959. self._set_todos(payload)
  960. def _set_todos(self, snapshot):
  961. """The gateway's ``{todos, revision}`` into the CLI's ``TodoStore`` (``restore``: no new revision)."""
  962. if isinstance(snapshot.get("todos"), list):
  963. try:
  964. self._todo_store.restore(snapshot["todos"], revision=snapshot.get("revision"))
  965. except (ValueError, TypeError) as exc:
  966. logger.debug("todo snapshot not mirrored: %s", exc)
  967. def _on_control_update(self, payload, stream_callback, starts):
  968. if self.control_update_callback is not None:
  969. self.control_update_callback()
  970. def _on_thinking(self, payload, stream_callback, starts):
  971. if self.thinking_callback is not None:
  972. self.thinking_callback(payload.get("text") or "")
  973. def _on_reasoning(self, payload, stream_callback, starts):
  974. if self.reasoning_callback is not None:
  975. self.reasoning_callback(payload.get("text") or "")
  976. def _on_reasoning_available(self, payload, stream_callback, starts):
  977. if self.tool_progress_callback is not None:
  978. self.tool_progress_callback("reasoning.available", "_thinking", (payload.get("text") or "")[:500], None)
  979. def _on_notice(self, payload, stream_callback, starts):
  980. if self.notice_callback is None:
  981. return
  982. from agent.credits_tracker import AgentNotice
  983. self.notice_callback(AgentNotice(text=str(payload.get("text") or ""), level=payload.get("level") or "info",
  984. kind=payload.get("kind") or "sticky", ttl_ms=payload.get("ttl_ms"),
  985. key=payload.get("key"), id=payload.get("id")))
  986. def _on_notice_clear(self, payload, stream_callback, starts):
  987. if self.notice_clear_callback is not None:
  988. self.notice_clear_callback(payload.get("key"))
  989. def _on_reaction(self, payload, stream_callback, starts):
  990. if self.reaction_callback is not None:
  991. self.reaction_callback(payload.get("kind"))
  992. def _on_print(self, payload, stream_callback, starts):
  993. self._emit_print(payload.get("text") or "")
  994. def _on_review_summary(self, payload, stream_callback, starts):
  995. line = review_summary_line(payload)
  996. if line:
  997. self._emit_print(line)
  998. def _emit_print(self, text):
  999. if self.suppress_status_output:
  1000. return
  1001. (self._print_fn or print)(text)
  1002. def _on_approval(self, payload, stream_callback, starts):
  1003. from tools.terminal_tool import _get_approval_callback
  1004. callback = _get_approval_callback()
  1005. choices = list(payload.get("choices") or [])
  1006. choice = "deny"
  1007. if callback is not None:
  1008. try:
  1009. choice = callback(payload.get("command") or "", payload.get("description") or "",
  1010. allow_permanent="always" in choices, allow_session="session" in choices,
  1011. smart_denied=False)
  1012. except TypeError:
  1013. choice = callback(payload.get("command") or "", payload.get("description") or "")
  1014. if choice not in choices:
  1015. choice = "deny"
  1016. self.connection.call("approval.respond", session_id=self.session_id,
  1017. execution_generation=payload.get("execution_generation", self._generation),
  1018. prompt_id=payload.get("prompt_id"), choice=choice)
  1019. def _on_clarify(self, payload, stream_callback, starts):
  1020. answer = ""
  1021. if self.clarify_callback is not None:
  1022. qid = payload.get("prompt_id") or "q0"
  1023. reply = self.clarify_callback([{"qid": qid, "question": payload.get("question") or "",
  1024. "choices": list(payload.get("choices") or []),
  1025. "multi_select": bool(payload.get("multi_select"))}])
  1026. if isinstance(reply, dict):
  1027. value = (reply.get("answers") or {}).get(qid)
  1028. answer = ", ".join(map(str, value)) if isinstance(value, (list, tuple)) else (value or "")
  1029. elif isinstance(reply, str):
  1030. answer = reply
  1031. self.connection.call("clarify.respond", session_id=self.session_id,
  1032. execution_generation=payload.get("execution_generation", self._generation),
  1033. prompt_id=payload.get("prompt_id"), answer=str(answer))
  1034. def _on_connection_request(self, payload, stream_callback, starts):
  1035. if self.connection_callback is not None:
  1036. self.connection_callback(payload)
  1037. def _on_connection_update(self, payload, stream_callback, starts):
  1038. if self.connection_update_callback is not None:
  1039. self.connection_update_callback(payload)
  1040. def _restore_connection_card(self, pending):
  1041. """After a replay gap, the resume snapshot's open operation: (re)open the card from it, or
  1042. close a stale card when none remains (the gap may have eaten the request or the settle)."""
  1043. if pending:
  1044. if self.connection_callback is not None:
  1045. self.connection_callback(pending)
  1046. elif self.connection_update_callback is not None:
  1047. self.connection_update_callback({"settled": True})
  1048. def connection_respond(self, op_id, result):
  1049. """The card's answer to the gateway's open operation (``connection.respond``); returns its result."""
  1050. return self.connection.call("connection.respond", op_id=op_id, result=result,
  1051. owner={"type": "session", "session_id": self.session_id})
  1052. def connection_retry(self, name):
  1053. """The card's Try again on a failed or expired row: the gateway re-mints it on the open operation."""
  1054. return self.connection.call("connectors.connect", connectors=[name], reconnect=True,
  1055. owner={"type": "session", "session_id": self.session_id})
  1056. def _answer_request(self, frame):
  1057. """A gateway server→client request (``sudo``, ``secret``, the ``vault.*`` prompts, ``clarify``): main's own modal
  1058. answers it on this (agent) thread, through the callback HermesCLI registered for the turn; the
  1059. answer travels only in the JSON-RPC response frame."""
  1060. method = frame["method"]
  1061. self._open_request = (frame["id"], method)
  1062. try:
  1063. answer = _SERVER_REQUESTS[method](self, frame.get("params") or {})
  1064. except Exception: # health: allow BLE001 -- a broken modal is a skip, never a hung tool
  1065. logger.debug("server request %s failed", method, exc_info=True)
  1066. answer = {"outcome": "cancelled"} if method == "clarify" else ""
  1067. finally:
  1068. self._open_request = None
  1069. if method == "clarify":
  1070. self.connection.reply(frame["id"], answer)
  1071. else:
  1072. self.connection.reply(frame["id"], {"value": answer if isinstance(answer, str) else ""})
  1073. def _on_request_withdrawn(self, payload):
  1074. """``request.cancel`` (connection loop thread): the gateway settled or withdrew a request. When
  1075. this agent thread is parked in the modal answering it (another viewer completed the form, the
  1076. turn timed out or was interrupted), release that modal so the pump reads the turn's remaining
  1077. frames; its late reply to the already-settled request is dropped by the gateway."""
  1078. current = self._open_request
  1079. if current is None or payload.get("id") != current[0] or self.modal_withdraw_callback is None:
  1080. return
  1081. try:
  1082. self.modal_withdraw_callback(current[1])
  1083. except Exception: # health: allow BLE001 -- a broken teardown must not stop the connection pump
  1084. logger.debug("modal withdraw for %s failed", current[1], exc_info=True)
  1085. def _ask_clarify(self, params):
  1086. return clarify_reply(self.clarify_callback, params)
  1087. def _ask_sudo(self, params):
  1088. from tools.terminal_tool import _get_sudo_password_callback
  1089. callback = _get_sudo_password_callback()
  1090. return (callback() or "") if callback is not None else ""
  1091. def _ask_secret(self, params):
  1092. """Main's masked "Skill Setup Required" panel (the CLI's registered secret-capture callback,
  1093. ``hermes_cli.callbacks.prompt_for_secret``) collects the value and prints main's lines; the
  1094. gateway, not this process, saves it in the profile ``.env``, so the panel's save is captured."""
  1095. from tools import skills_tool
  1096. callback = skills_tool._secret_capture_callback
  1097. if callback is None:
  1098. return ""
  1099. from hermes_cli import callbacks
  1100. captured = []
  1101. def capture(key, value):
  1102. captured.append(value)
  1103. return {"success": True, "stored_as": key, "validated": False}
  1104. with _SECRET_LOCK:
  1105. saver, callbacks.save_env_value_secure = callbacks.save_env_value_secure, capture
  1106. try:
  1107. callback(params.get("env_var") or "", params.get("prompt") or "", params.get("metadata"))
  1108. finally:
  1109. callbacks.save_env_value_secure = saver
  1110. return captured[0] if captured else ""
  1111. def _ask_vault_unlock(self, params):
  1112. """Main's masked password-manager unlock panel, through the callback HermesCLI registered."""
  1113. from agent.vault_backends.unlock import get_unlock_prompt_callback
  1114. callback = get_unlock_prompt_callback()
  1115. if callback is None:
  1116. return ""
  1117. return callback(str(params.get("backend") or ""), str(params.get("display_name") or "")) or ""
  1118. def _ask_vault_save_login(self, params):
  1119. """Main's two-step "save this login" panel. The gateway stores the login in the vault, so the
  1120. identifier and password go back as one JSON string in the response frame, as the cards send it."""
  1121. from agent.vault_backends.unlock import get_save_login_prompt_callback
  1122. callback = get_save_login_prompt_callback()
  1123. if callback is None:
  1124. return ""
  1125. answer = callback(str(params.get("origin") or ""), str(params.get("site") or ""))
  1126. if not isinstance(answer, dict) or not answer.get("password"):
  1127. return ""
  1128. try:
  1129. return json.dumps({"identifier": str(answer.get("identifier") or ""), "password": str(answer["password"])})
  1130. finally:
  1131. answer.clear()
  1132. def _ask_vault_code(self, params):
  1133. """Main's one-time-code panel, through the callback HermesCLI registered."""
  1134. from agent.vault_backends.unlock import get_code_prompt_callback
  1135. callback = get_code_prompt_callback()
  1136. if callback is None:
  1137. return ""
  1138. return callback(str(params.get("site") or ""), str(params.get("hint") or "")) or ""
  1139. # -- result --------------------------------------------------------------------------------
  1140. def _user_row(self, user_message):
  1141. staged = self._pending_cli_user_message
  1142. if isinstance(staged, dict):
  1143. return staged
  1144. return {"role": "user", "content": user_message}
  1145. def _voice_stopped(self, history):
  1146. """TUI-26: the owner took a bare stop phrase typed into this LOCAL session's voice chat (turned
  1147. on by another viewer) as the end of that chat and admitted nothing, so no ``message.complete``
  1148. will come. The turn ends at once with main's typed-stop notice; the history is unchanged."""
  1149. from agent.i18n import t
  1150. self._give_back_turn_route() # nothing was admitted: a ``/model --once`` pick is still owed
  1151. self._emit_print(t("cli.voice.stop_phrase_typed"))
  1152. return {**_RESULT_DEFAULTS, "messages": list(history), "voice_stopped": True, "session_id": self.session_id}
  1153. def _unadmitted(self, history, user_message, error):
  1154. """A turn the owner never saw (a pre-submit notice, or a submit that was never sent): the CLI
  1155. keeps its local state (no history row, the ``/model --once`` pick and notes) for the resend."""
  1156. self._give_back_turn_route()
  1157. return {**self._failed(history, user_message, error, failure_reason="gateway_connection"),
  1158. "messages": history, "admitted": False}
  1159. def _failed(self, history, user_message, error, *, failure_reason=None, retryable=False):
  1160. """``failure_reason="gateway_connection"``: the CLI shows ``error`` as written instead of
  1161. classifying a lost gateway as a model failure ("Run /model to switch...")."""
  1162. out = {**_RESULT_DEFAULTS, "final_response": "", "messages": history + [self._user_row(user_message)],
  1163. "failed": True, "completed": False, "error": error, "session_id": self.session_id}
  1164. if failure_reason:
  1165. out.update(failure_reason=failure_reason, failure_retryable=retryable)
  1166. return out
  1167. def _result(self, history, user_message, complete, turn):
  1168. receipt = (complete or {}).get("_receipt") or {}
  1169. if receipt: # settled from it after a replay gap
  1170. complete = {"outcome": receipt.get("outcome")}
  1171. elif turn.admission:
  1172. try:
  1173. receipt = self.connection.call("prompt.receipt", session_id=turn.session_id, abandon=self._lost(turn),
  1174. admission_id=turn.admission, include_result=True) or {}
  1175. except GatewayClientError as exc:
  1176. logger.debug("prompt.receipt failed: %s", exc)
  1177. stored = dict(receipt.get("result") or {})
  1178. usage = dict(receipt.get("usage") or {})
  1179. status = (complete or {}).get("status") or (complete or {}).get("outcome")
  1180. out = {**_RESULT_DEFAULTS, **stored}
  1181. if "final_response" not in stored:
  1182. out["final_response"] = (complete or {}).get("text") or (complete or {}).get("content") or ""
  1183. if status in {"interrupted", "cancelled"} or (complete or {}).get("outcome") == "cancelled":
  1184. out["interrupted"] = True
  1185. out["completed"] = False
  1186. elif status in {"error", "failed"} and not stored:
  1187. out.update(failed=True, completed=False)
  1188. suffix = stored.get("messages") if isinstance(stored.get("messages"), list) else None
  1189. if suffix is not None and stored.get("_compressed"):
  1190. out["messages"] = list(suffix)
  1191. else:
  1192. out["messages"] = history + [self._user_row(user_message)] + list(suffix or [])
  1193. if not suffix and out.get("final_response") and not out.get("failed"):
  1194. out["messages"].append({"role": "assistant", "content": out["final_response"]})
  1195. out["session_id"] = self.session_id
  1196. if not self._owns(turn): # taken over during that read: the newer turn's state stays untouched
  1197. return out
  1198. self._session_messages = out["messages"]
  1199. calls = stored.get("api_calls")
  1200. # An interrupted turn's own count includes the attempt Ctrl-C cut off (the agent counts a call
  1201. # before the request goes out). Only a response prices the ask: fall back to the gateway's
  1202. # cumulative count, which moves per response, so an unanswered ask stays main's ``~`` estimate.
  1203. counted = isinstance(calls, int) and not isinstance(calls, bool) and not out.get("interrupted")
  1204. self._turn_api_calls = calls if counted else None
  1205. self._apply_usage(stored, usage, turn)
  1206. return out
  1207. def _paint_owed(self, turn, out, complete, stream_callback):
  1208. """After a replay gap, the reply once (``owed_reply``): a reuse this terminal showed whole stays
  1209. the only copy; otherwise main's panel shows what streaming did not."""
  1210. from hermes_cli.gateway_replay_gap import owed_reply
  1211. reply = out.get("pre_transform_response") if out.get("response_transformed") else None
  1212. reply = reply if isinstance(reply, str) else out.get("final_response")
  1213. if out.get("failed") or not isinstance(reply, str) or not reply.strip():
  1214. return
  1215. reused = out.get("response_previewed") or out.get("response_reused") or complete.get("response_reused")
  1216. out["response_previewed"] = bool(reused) and reply.strip() in turn.seen | {turn.shown.strip(), turn.spoken.strip()}
  1217. for consumer, got in ((self.stream_delta_callback, turn.shown), (stream_callback, turn.spoken)):
  1218. owed = owed_reply(got, reply) if consumer is not None and not out["response_previewed"] else ""
  1219. if owed: # each consumer completes what it got itself, never twice
  1220. consumer(owed)
  1221. def _anchor_display(self):
  1222. """Main's bar shows the anchored ``context_tokens`` by re-deriving it from
  1223. ``_turn_base_usage_anchor`` over ``_session_messages`` (``anchored_context_tokens``), and marks
  1224. it ``~`` when the turn appended rows after its first response. Rebuild an anchor over this
  1225. viewer's transcript that yields the gateway's figure: rows after the first API call of a
  1226. multi-call turn are the estimated delta (main's ``~``); a single reply is covered by the anchor."""
  1227. from agent.model_metadata import estimate_messages_tokens_rough
  1228. from agent.usage_anchor import capture_usage_anchor
  1229. messages = self._session_messages if isinstance(self._session_messages, list) else []
  1230. tokens = getattr(self, "_context_tokens", 0) or 0
  1231. if tokens <= 0 or not messages or self._generation is not None:
  1232. self._turn_base_usage_anchor = None # mid-turn: the bar falls back to last_prompt_tokens
  1233. return
  1234. # Main anchors on the turn's FIRST response, priced over the transcript through the turn's ask.
  1235. # A turn with no completed call (interrupted before a response) keeps the previous anchor, so
  1236. # its ask is estimated delta too.
  1237. # The turn's own ask, never a later user-role row of the same turn (a mid-turn /steer row).
  1238. ask = getattr(self, "_turn_ask_index", None)
  1239. last_user = ask if isinstance(ask, int) and 0 <= ask < len(messages) and messages[ask].get("role") == "user" \
  1240. else next((i for i in range(len(messages) - 1, -1, -1) if messages[i].get("role") == "user"),
  1241. len(messages) - 1)
  1242. # Did this turn complete an API call? The turn result's own count when the gateway sent one: a
  1243. # rebuilt gateway agent (/personality, /model, and /undo, /retry bumping the runtime generation)
  1244. # restarts its session counters, so the cumulative delta can read "no call" for a turn that
  1245. # answered; without that count a LOWER cumulative is a new agent that made calls, never "no call".
  1246. turn_calls = self._turn_api_calls
  1247. calls, turn_base = self.session_api_calls, self._turn_calls_base
  1248. made_call = turn_calls > 0 if isinstance(turn_calls, int) else (calls > turn_base or 0 < calls < turn_base)
  1249. base = last_user + 1 if made_call else last_user
  1250. if base <= 0:
  1251. self._turn_base_usage_anchor = None
  1252. return
  1253. delta = messages[base:]
  1254. if delta and delta[0].get("role") == "assistant":
  1255. delta = delta[1:]
  1256. estimate = estimate_messages_tokens_rough(delta, charge_stale_thinking=False) if delta else 0
  1257. self._turn_base_usage_anchor = capture_usage_anchor(max(1, tokens - estimate), 0, messages[:base])
  1258. def _refresh_stats(self, turn=None):
  1259. """``session.stats`` → the same attributes ``session.usage`` sets; False when unavailable."""
  1260. try:
  1261. stats = self.connection.call("session.stats", session_id=self.session_id, timeout=10,
  1262. abandon=turn and self._lost(turn))
  1263. except GatewayClientError as exc:
  1264. logger.debug("session.stats unavailable: %s", exc)
  1265. return False
  1266. stats = stats.get("usage") if isinstance(stats, dict) and isinstance(stats.get("usage"), dict) else stats
  1267. if not (isinstance(stats, dict) and isinstance(stats.get("api_calls"), int)):
  1268. return False
  1269. if turn is None or self._owns(turn):
  1270. self._state().apply_usage(stats)
  1271. return True
  1272. def _apply_usage(self, stored, receipt_usage, turn):
  1273. """Turn end: the session-cumulative ``session.stats`` (the same dict ``session.usage`` carries);
  1274. a gateway without the verb leaves the per-turn receipt figures as before."""
  1275. if self._refresh_stats(turn) or not self._owns(turn):
  1276. return
  1277. # Fallback: the classic-CLI result carries the gateway agent's session_* counters
  1278. # (turn_finalizer _SESSION_TOKEN_KEYS); per-turn receipt usage only accumulates what is missing.
  1279. usage = {key: stored[key] for key in _COUNTER_FROM_USAGE.values() if isinstance(stored.get(key), int)}
  1280. for key in ("input_tokens", "output_tokens"):
  1281. if key not in usage and isinstance(receipt_usage.get(key), int):
  1282. attr = "session_" + key
  1283. usage[key] = getattr(self, attr) + receipt_usage[key]
  1284. usage.setdefault("prompt_tokens", usage.get("input_tokens"))
  1285. usage.setdefault("completion_tokens", usage.get("output_tokens"))
  1286. if isinstance(usage.get("prompt_tokens"), int) and isinstance(usage.get("completion_tokens"), int):
  1287. usage.setdefault("total_tokens", usage["prompt_tokens"] + usage["completion_tokens"])
  1288. if isinstance(stored.get("api_calls"), int):
  1289. usage["api_calls"] = self.session_api_calls + stored["api_calls"]
  1290. for key in ("last_prompt_tokens", "context_length", "model"):
  1291. if receipt_usage.get(key) or stored.get(key):
  1292. usage[key] = receipt_usage.get(key) or stored.get(key)
  1293. self.apply_session_usage(usage)
  1294. def _effort_word(config):
  1295. """The ``session.mutate reasoning`` effort for main's ``reasoning_config`` dict (None: no override)."""
  1296. if not isinstance(config, dict):
  1297. return None
  1298. if config.get("enabled") is False:
  1299. return "none"
  1300. effort = config.get("effort")
  1301. return effort if isinstance(effort, str) and effort else None
  1302. def _rate_limit_state(data):
  1303. """``get_rate_limit_state()`` rebuilt from its serialized dict (None stays None)."""
  1304. if not isinstance(data, dict):
  1305. return None
  1306. from agent.rate_limit_tracker import RateLimitBucket, RateLimitState
  1307. buckets = {name: RateLimitBucket(**{k: v for k, v in (data.get(name) or {}).items()
  1308. if k in {"limit", "remaining", "reset_seconds", "captured_at"}})
  1309. for name in ("requests_min", "requests_hour", "tokens_min", "tokens_hour")}
  1310. return RateLimitState(**buckets, captured_at=float(data.get("captured_at") or 0.0),
  1311. provider=str(data.get("provider") or ""))
  1312. def review_summary_line(payload):
  1313. """Main's ``display.review.summary_cli`` line for the gateway's ``review.summary`` frame: the background
  1314. review's "💾 Self-improvement review: ..." (``/refine``, the post-turn review), which the gateway
  1315. publishes to a local viewer once the turn settled. None for an empty one."""
  1316. text = str(payload.get("text") or "").strip() if isinstance(payload, dict) else ""
  1317. return f" {text}" if text else None
  1318. def _moa_handler(kind):
  1319. def handler(agent, payload, stream_callback, starts):
  1320. if agent.tool_progress_callback is None:
  1321. return
  1322. extra = {k: v for k, v in payload.items() if k not in {"label", "text", "name", "preview", "index", "count"}}
  1323. # Main's _on_tool_progress reads moa_index / moa_count (the gateway frame uses the TUI keys).
  1324. if payload.get("index") is not None:
  1325. extra["moa_index"] = payload["index"]
  1326. if payload.get("count") is not None:
  1327. extra["moa_count"] = payload["count"]
  1328. agent.tool_progress_callback(kind, payload.get("label") or payload.get("name"),
  1329. payload.get("text") or payload.get("preview"), None, **extra)
  1330. return handler
  1331. def clarify_reply(callback, params) -> dict:
  1332. """Main's batch clarify panel (``callback(questions)``, ``HermesCLI._clarify_callback``) answering a
  1333. ``clarify`` server request's whole question set: its ``ClarifyResult``."""
  1334. questions = [{"qid": q.get("qid"), "question": q.get("question") or "",
  1335. "choices": list(q.get("choices") or []), "multi_select": bool(q.get("multi_select"))}
  1336. for q in params.get("questions") or [] if isinstance(q, dict) and q.get("qid")]
  1337. if callback is None or not questions:
  1338. return {"outcome": "cancelled"}
  1339. reply = callback(questions)
  1340. if not isinstance(reply, dict):
  1341. return {"outcome": "cancelled"}
  1342. answers = {qid: (value if isinstance(value, str) or value is None else json.dumps(value))
  1343. for qid, value in (reply.get("answers") or {}).items()}
  1344. out = {"answers": answers}
  1345. if reply.get("outcome") in ("submitted", "timed_out", "cancelled"):
  1346. out["outcome"] = reply["outcome"]
  1347. return out
  1348. _SECRET_LOCK = threading.Lock()
  1349. _SERVER_REQUESTS = {
  1350. "sudo": GatewayAgent._ask_sudo,
  1351. "secret": GatewayAgent._ask_secret,
  1352. "vault.unlock_prompt": GatewayAgent._ask_vault_unlock,
  1353. "vault.save_login": GatewayAgent._ask_vault_save_login,
  1354. "vault.code": GatewayAgent._ask_vault_code,
  1355. "clarify": GatewayAgent._ask_clarify,
  1356. }
  1357. _HANDLERS = {
  1358. "message.delta": GatewayAgent._on_delta,
  1359. "message.interim": GatewayAgent._on_interim,
  1360. "tool.generating": GatewayAgent._on_tool_generating,
  1361. "tool.progress": GatewayAgent._on_tool_progress,
  1362. "tool.start": GatewayAgent._on_tool_start,
  1363. "tool.complete": GatewayAgent._on_tool_complete,
  1364. "todo.updated": GatewayAgent._on_todo,
  1365. "session.control.update": GatewayAgent._on_control_update,
  1366. "thinking.delta": GatewayAgent._on_thinking,
  1367. "reasoning.delta": GatewayAgent._on_reasoning,
  1368. "reasoning.available": GatewayAgent._on_reasoning_available,
  1369. "moa.reference": _moa_handler("moa.reference"),
  1370. "moa.aggregating": _moa_handler("moa.aggregating"),
  1371. "notification.show": GatewayAgent._on_notice,
  1372. "notification.clear": GatewayAgent._on_notice_clear,
  1373. "reaction": GatewayAgent._on_reaction,
  1374. "agent.print": GatewayAgent._on_print,
  1375. "review.summary": GatewayAgent._on_review_summary,
  1376. "approval.request": GatewayAgent._on_approval,
  1377. "clarify.request": GatewayAgent._on_clarify,
  1378. "connection.request": GatewayAgent._on_connection_request,
  1379. "connection.update": GatewayAgent._on_connection_update,
  1380. }