turn_facade.py 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224
  1. """``AIAgent.run_conversation`` / ``chat`` façade.
  2. Turn admission around ``conversation_loop.run_conversation``: durable cross-process session turn lease +
  3. refresher thread and liveness watchdog (``agent.turn_facade_lease``), relay/accounting/portal scopes, and
  4. balanced start/finish marks. Extracted from ``run_agent.py``; every method resolves through ``AIAgent``'s
  5. MRO unchanged.
  6. """
  7. import logging
  8. import uuid
  9. from contextlib import suppress
  10. from typing import Any, Dict, Generator, List, Optional
  11. from agent.lazy_forward import forward as _forward
  12. # Same logger name as the origin module so log records / caplog filters are unchanged.
  13. logger = logging.getLogger("run_agent")
  14. class TurnFacadeMixin:
  15. """run_conversation()/chat() (see module docstring)."""
  16. def run_conversation(
  17. self, user_message: Any, system_message: str | None=None,
  18. conversation_history: list[dict[str, Any]] | None=None, task_id: str | None=None,
  19. stream_callback: Optional[callable]=None, persist_user_message: Optional[Any]=None,
  20. persist_user_timestamp: Optional[float]=None, persist_user_display_kind: Optional[str]=None,
  21. persist_user_display_metadata: Optional[dict[str, Any]]=None,
  22. persist_user_platform_id: Optional[str]=None, moa_config: Optional[dict[str, Any]]=None,
  23. turn_author: Optional[dict[str, Any]] = None,
  24. relay_metadata: Optional[dict[str, Any]] = None,
  25. title_user_message: Optional[str]=None,
  26. prelude: Optional[Generator]=None,
  27. ) -> dict[str, Any]:
  28. """Forwarder — see ``agent.conversation_loop.run_conversation``."""
  29. # A review shares this session_id for cache parity: fence review startup or interrupt
  30. # an admitted request and await its exit before opening live-turn instrumentation.
  31. # Foreground priority is retained if the review does not acknowledge within the bounded deadline
  32. # (#84423).
  33. from agent.background_review import cancel_background_review_for_live_turn
  34. cancel_background_review_for_live_turn(self)
  35. from agent import relay_runtime
  36. from agent.aux_accounting import reset_accounting_context, set_accounting_context
  37. from agent.auxiliary_client import scoped_runtime_main
  38. from agent.conversation_loop import run_conversation
  39. from agent.portal_tags import (
  40. reset_affinity_scope, reset_conversation_context, set_affinity_scope,
  41. set_conversation_context,
  42. )
  43. from agent.prompt_cache_scope import declared_conversation_scope_safe
  44. from agent.relay_cwd import resolve_relay_scope_cwds
  45. from agent.review_idle_queue import QUEUE as _review_queue
  46. from agent.subagent_lifecycle import bind_subagent_parent
  47. from agent.interrupt_scope import track_in_interrupt_scope
  48. from agent.turn_facade_lease import admit_durable_turn_lease, carry_unadmitted_user_message
  49. from hermes_cli.observability.relay_shared_metrics import finish_task_run, start_task_run
  50. effective_task_id = task_id or str(uuid.uuid4())
  51. session_id = str(getattr(self, "session_id", None) or "")
  52. task_context = {
  53. "session_id": session_id,
  54. "task_id": effective_task_id,
  55. "platform": getattr(self, "platform", None) or "",
  56. }
  57. relay_turn_id = f"{session_id or 'session'}:{effective_task_id}:{uuid.uuid4().hex[:8]}"
  58. self._relay_pending_turn_id = relay_turn_id
  59. relay_parent_session_id = (
  60. str(getattr(self, "_parent_session_id", None) or "")
  61. if task_context["platform"] == "subagent"
  62. else ""
  63. )
  64. relay_lease = relay_turn = lease = None
  65. # Scope tokens start None: early returns leave the try before the set_*() calls and
  66. # the finally resets each one unconditionally.
  67. token = affinity_token = acct_token = None
  68. task_started = task_finished = False
  69. relay_outcome = "failed"
  70. try:
  71. # First statement of the try so the finally's note_turn_finished balances every exit.
  72. _review_queue.note_turn_started()
  73. admission = admit_durable_turn_lease(
  74. self, session_id=session_id, relay_turn_id=relay_turn_id, task_context=task_context,
  75. conversation_history=conversation_history,
  76. )
  77. if admission.early_result is not None:
  78. carry_unadmitted_user_message(
  79. admission.early_result, user_message, persist_user_message,
  80. timestamp=persist_user_timestamp, display_kind=persist_user_display_kind,
  81. display_metadata=persist_user_display_metadata, platform_id=persist_user_platform_id,
  82. )
  83. relay_outcome = (
  84. "cancelled" if admission.early_result.get("interrupted") else "timed_out"
  85. )
  86. return admission.early_result
  87. lease = admission.lease
  88. conversation_history = admission.conversation_history
  89. relay_session_cwd, relay_turn_cwd = resolve_relay_scope_cwds(
  90. self,
  91. effective_task_id,
  92. task_context["session_id"],
  93. task_context["platform"],
  94. )
  95. relay_lease = relay_runtime.SESSION_COORDINATOR.acquire_conversation(
  96. profile_key=relay_runtime.current_profile_key(),
  97. session_id=task_context["session_id"], platform=task_context["platform"],
  98. parent_session_id=relay_parent_session_id,
  99. model=str(getattr(self, "model", None) or ""),
  100. session_cwd=relay_session_cwd,
  101. turn_cwd=relay_turn_cwd,
  102. )
  103. relay_turn_kwargs: dict[str, Any] = {
  104. "turn_id": relay_turn_id,
  105. "task_id": effective_task_id,
  106. }
  107. if relay_metadata:
  108. relay_turn_kwargs["metadata"] = relay_metadata
  109. relay_turn = relay_runtime.SESSION_COORDINATOR.begin_turn(
  110. relay_lease, **relay_turn_kwargs
  111. )
  112. # Minimal relay-runtime shims may lack the opt-out flag: default enabled.
  113. if getattr(relay_turn, "relay_enabled", True):
  114. start_task_run(
  115. **task_context,
  116. parent_session_id=getattr(self, "_parent_session_id", None) or "",
  117. )
  118. task_started = True
  119. # Ambient Nous Portal tagging: every LLM call in this turn (loop, compression,
  120. # vision, MoA, review forks) inherits `conversation=<root>`; host-declared
  121. # affinity scope falls back to it; accounting handles route aux usage to the session.
  122. token = set_conversation_context(self._conversation_root_id())
  123. affinity_token = set_affinity_scope(declared_conversation_scope_safe(self))
  124. # Publish the session accounting handles the same way so auxiliary calls record their token
  125. # usage into session_model_usage (task dimension) — the fix for aux spend being invisible in
  126. # analytics (issue #23270).
  127. acct_token = set_accounting_context(
  128. getattr(self, "_session_db", None), getattr(self, "session_id", None)
  129. )
  130. # Keep the ContextVar scope local (agent tokens may be observed from another thread).
  131. # A host that owns this thread (Hermes Console) may cancel the turn cross-thread.
  132. with bind_subagent_parent(self), scoped_runtime_main({}), track_in_interrupt_scope(self):
  133. try:
  134. if lease is not None:
  135. lease.start()
  136. result = run_conversation(
  137. self, user_message, system_message, conversation_history, effective_task_id,
  138. stream_callback, persist_user_message,
  139. persist_user_timestamp=persist_user_timestamp,
  140. persist_user_display_kind=persist_user_display_kind,
  141. persist_user_display_metadata=persist_user_display_metadata,
  142. persist_user_platform_id=persist_user_platform_id, moa_config=moa_config,
  143. turn_author=turn_author,
  144. title_user_message=title_user_message,
  145. prelude=prelude,
  146. )
  147. finally:
  148. # Post-loop relay/task finalization must not receive a late refresh interrupt;
  149. # the interrupt clear itself waits for the thread join in the outer finally.
  150. if lease is not None:
  151. lease.stop_refresher()
  152. terminal = result if isinstance(result, dict) else {}
  153. relay_outcome = (
  154. "cancelled" if terminal.get("interrupted") is True
  155. else "failed" if terminal.get("failed") is True
  156. else "success"
  157. )
  158. relay_runtime.SESSION_COORDINATOR.finish_logical_calls(relay_turn, outcome=relay_outcome)
  159. if task_started:
  160. task_finished = True
  161. finish_task_run(**task_context, result=result)
  162. return result
  163. except BaseException as exc:
  164. if isinstance(exc, (KeyboardInterrupt, InterruptedError)) or (
  165. type(exc).__name__ == "CancelledError"
  166. ):
  167. relay_outcome = "cancelled"
  168. elif isinstance(exc, TimeoutError):
  169. relay_outcome = "timed_out"
  170. if relay_turn is not None:
  171. relay_runtime.SESSION_COORDINATOR.finish_logical_calls(
  172. relay_turn, outcome=relay_outcome
  173. )
  174. if task_started and not task_finished:
  175. task_finished = True
  176. finish_task_run(**task_context, error=exc)
  177. raise
  178. finally:
  179. try:
  180. if relay_turn is not None:
  181. relay_runtime.SESSION_COORDINATOR.end_turn(relay_turn, outcome=relay_outcome)
  182. finally:
  183. try:
  184. if relay_lease is not None:
  185. relay_runtime.SESSION_COORDINATOR.release_conversation(relay_lease)
  186. finally:
  187. if lease is not None:
  188. lease.stop_refresher()
  189. lease.join_threads()
  190. lease.clear_interrupt() # refresher interrupt between stop and join; AFTER join
  191. lease.release()
  192. # Always clear mid-turn labels on exit — including interrupted early returns
  193. # that skip finalize_turn. Keep ts.
  194. with suppress(Exception):
  195. self._reset_activity_labels_after_turn()
  196. if getattr(self, "_relay_pending_turn_id", None) == relay_turn_id:
  197. self._relay_pending_turn_id = None
  198. if acct_token is not None:
  199. reset_accounting_context(acct_token)
  200. if token is not None:
  201. reset_conversation_context(token)
  202. if affinity_token is not None:
  203. reset_affinity_scope(affinity_token)
  204. # Balance note_turn_started so the idle queue's live-turn count cannot leak.
  205. with suppress(Exception):
  206. _review_queue.note_turn_finished()
  207. def chat(self, message: str, stream_callback: Optional[callable] = None) -> str:
  208. """Final response string of one turn; ``stream_callback`` receives each text delta."""
  209. return self.run_conversation(message, stream_callback=stream_callback)["final_response"]
  210. _run_codex_app_server_turn = _forward("agent.codex_runtime", "run_codex_app_server_turn")