turn_stop_gates.py 10 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223
  1. """Text-response stop gates for the conversation turn loop.
  2. When the model stops with a text answer, four gates may instead append the answer as an
  3. interim row plus a user-role nudge and continue the turn: late language-server verdicts on this
  4. turn's edits (a durable row, see ``_late_lsp_verdicts``), verify-on-stop (#65919),
  5. the ``pre_verify`` plugin hook after code edits, and the kanban worker terminal-tool guard.
  6. Each keeps the candidate answer as a budget-exhaustion fallback
  7. (``pending_verification_response``) and clears ``final_response`` so the finalizer can tell
  8. this gate from error exits (#61631). Nothing here imports ``agent.conversation_loop`` at
  9. module level (cycle).
  10. """
  11. from __future__ import annotations
  12. import logging
  13. import os
  14. from dataclasses import dataclass
  15. from typing import Any, Dict, List, Optional
  16. from agent.message_metadata import append_message
  17. logger = logging.getLogger("agent.conversation_loop")
  18. @dataclass
  19. class StopGateVerdict:
  20. """``continue_turn`` True → a nudge was appended; re-enter the turn loop with
  21. ``final_response=None`` and the pending-verification fields updated."""
  22. continue_turn: bool
  23. final_response: Any
  24. pending_verification_response: Any
  25. pending_verification_response_previewed: Any
  26. def _verify_on_stop_nudge(agent) -> Optional[str]:
  27. try:
  28. from agent.verification_stop import (
  29. build_verify_on_stop_nudge, verify_on_stop_enabled
  30. )
  31. if verify_on_stop_enabled():
  32. return build_verify_on_stop_nudge(
  33. session_id=getattr(agent, "session_id", None),
  34. changed_paths=getattr(agent, "_turn_file_mutation_paths", set()),
  35. attempts=getattr(agent, "_verification_stop_nudges", 0),
  36. )
  37. except Exception:
  38. logger.debug("verification stop-loop check failed", exc_info=True)
  39. return None
  40. def _pre_verify_nudge(agent, final_response, attempt: int) -> Optional[str]:
  41. """After code edits a registered ``pre_verify`` hook may keep the agent going one
  42. more turn; no default continuation cost."""
  43. _edited = sorted(getattr(agent, "_turn_file_mutation_paths", set()) or [])
  44. try:
  45. from agent.verify_hooks import max_verify_nudges
  46. from hermes_cli.lifecycle import has_hook
  47. from hermes_cli.plugins import get_pre_verify_continue_message
  48. if _edited and has_hook("pre_verify") and attempt < max_verify_nudges():
  49. # Posture is fixed for the session — resolve once + cache.
  50. coding = getattr(agent, "_resolved_is_coding", None)
  51. if coding is None:
  52. from agent.coding_context import is_coding_context
  53. coding = bool(is_coding_context(platform=getattr(agent, "platform", "") or ""))
  54. agent._resolved_is_coding = coding
  55. return get_pre_verify_continue_message(
  56. session_id=getattr(agent, "session_id", None) or "",
  57. platform=getattr(agent, "platform", "") or "",
  58. model=getattr(agent, "model", "") or "", coding=coding, attempt=attempt,
  59. final_response=final_response, changed_paths=_edited,
  60. )
  61. except Exception:
  62. logger.debug("pre_verify hook check failed", exc_info=True)
  63. return None
  64. def _kanban_stop_nudge(agent, messages) -> Optional[str]:
  65. """Workers must end with a terminal board tool (kanban_complete / kanban_block /
  66. kanban_request_review / kanban_request_changes); a narrated stop is recorded
  67. as protocol_violation, so nudge once or twice first."""
  68. try:
  69. from agent.kanban_stop import build_kanban_stop_nudge
  70. return build_kanban_stop_nudge(
  71. messages=messages, attempts=getattr(agent, "_kanban_stop_nudges", 0)
  72. )
  73. except Exception:
  74. logger.debug("kanban stop-loop check failed", exc_info=True)
  75. return None
  76. _MAX_LSP_TURN_END_NOTES = 3
  77. def _late_lsp_verdicts(agent) -> Optional[str]:
  78. """Language-server verdicts on this turn's edits that no tool result carried yet (the edit was the
  79. last tool call; a one-shot run has no next turn to carry them): waits briefly for checks still
  80. running (``agent.lsp.deferred.settle_for_agent``) and returns them as a message for the model."""
  81. issued = getattr(agent, "_lsp_turn_end_notes", 0)
  82. if not isinstance(issued, int) or issued >= _MAX_LSP_TURN_END_NOTES:
  83. return None
  84. try:
  85. from agent.lsp.deferred import settle_for_agent
  86. notes = settle_for_agent(agent)
  87. except Exception:
  88. logger.debug("late LSP verdict check failed", exc_info=True)
  89. return None
  90. if not notes:
  91. return None
  92. body = "\n\n".join(text for _path, text in notes)
  93. return ("[System note: the language server reported problems in files you edited this turn, after "
  94. "those tool results had returned. Fix them if they are real, then give your final answer.]\n\n"
  95. + body)
  96. def _append_interim_answer(agent, final_msg, messages, conversation_history, flush_fail_msg: str) -> None:
  97. """Real content: persist and emit as interim so the user sees the attempted answer;
  98. only the nudge is flagged synthetic (#65919). A held turn's answer (typed hidden) is not shown
  99. and flushes with the turn instead, so a budget fallback can still publish it as the rewrite."""
  100. agent._emit_interim_assistant_message(final_msg)
  101. append_message(messages, final_msg)
  102. if final_msg.get("display_kind") == "hidden":
  103. return
  104. try:
  105. agent._flush_messages_to_session_db(messages, conversation_history)
  106. except Exception:
  107. logger.debug(flush_fail_msg, exc_info=True)
  108. def apply_stop_gates(
  109. agent: Any, final_msg: dict[str, Any], *, final_response: Any, messages: list[dict[str, Any]],
  110. conversation_history: Any, pending_verification_response: Any,
  111. pending_verification_response_previewed: Any,
  112. ) -> StopGateVerdict:
  113. """Run verify-on-stop → pre_verify hook → kanban stop guard, in that order. Nudges
  114. are user-role rows appended only after the assistant answer row, so role alternation
  115. holds. Hook lookups are imported lazily from their origin modules (tests patch them
  116. there)."""
  117. def _continue(nudge: str, flag: str) -> StopGateVerdict:
  118. """Append the synthetic nudge row and hand the turn back to the loop."""
  119. append_message(messages, {"role": "user", "content": nudge, flag: True})
  120. agent._session_messages = messages
  121. # Keep the answer only as a budget-exhaustion fallback; clear ``final_response`` so
  122. # the finalizer can tell this gate from error exits. Mark previewed only if the
  123. # candidate is reused (#61631).
  124. return StopGateVerdict(
  125. continue_turn=True, final_response=None,
  126. pending_verification_response=final_response,
  127. # Prefix semantics on purpose: the streamed prefix IS on screen here. The gateway
  128. # interim verdict uses _interim_content_fully_streamed instead (#88954).
  129. pending_verification_response_previewed=agent._interim_content_was_streamed(
  130. final_response or ""
  131. ),
  132. )
  133. _lsp_note = _late_lsp_verdicts(agent)
  134. if _lsp_note:
  135. agent._lsp_turn_end_notes = getattr(agent, "_lsp_turn_end_notes", 0) + 1 # int: checked above
  136. final_msg["finish_reason"] = "verification_required"
  137. _append_interim_answer(
  138. agent, final_msg, messages, conversation_history, "late-LSP interim flush failed"
  139. )
  140. # A durable row (no scaffolding flag): it is never stripped, so no sent byte changes later.
  141. append_message(messages, {"role": "user", "content": _lsp_note})
  142. agent._session_messages = messages
  143. logger.debug("late LSP verdicts delivered before the final answer (%d)", agent._lsp_turn_end_notes)
  144. return StopGateVerdict(
  145. continue_turn=True, final_response=None,
  146. pending_verification_response=final_response,
  147. pending_verification_response_previewed=agent._interim_content_was_streamed(final_response or ""),
  148. )
  149. _verify_nudge = _verify_on_stop_nudge(agent)
  150. if _verify_nudge:
  151. agent._verification_stop_nudges = getattr(agent, "_verification_stop_nudges", 0) + 1
  152. final_msg["finish_reason"] = "verification_required"
  153. _append_interim_answer(
  154. agent, final_msg, messages, conversation_history, "verify-on-stop interim flush failed"
  155. )
  156. verdict = _continue(_verify_nudge, "_verification_stop_synthetic")
  157. # Internal nudge: stay silent on the terminal, debug-log only.
  158. logger.debug("verification stop-loop nudge issued (attempt %d)", agent._verification_stop_nudges)
  159. return verdict
  160. _attempt = getattr(agent, "_pre_verify_nudges", 0)
  161. _verify_nudge2 = _pre_verify_nudge(agent, final_response, _attempt)
  162. if _verify_nudge2:
  163. agent._pre_verify_nudges = _attempt + 1
  164. final_msg["finish_reason"] = "verify_hook_continue"
  165. _append_interim_answer(
  166. agent, final_msg, messages, conversation_history, "pre_verify interim flush failed"
  167. )
  168. verdict = _continue(_verify_nudge2, "_pre_verify_synthetic")
  169. logger.debug("pre_verify nudge issued (attempt %d)", agent._pre_verify_nudges)
  170. return verdict
  171. _kanban_nudge = _kanban_stop_nudge(agent, messages)
  172. if _kanban_nudge:
  173. agent._kanban_stop_nudges = getattr(agent, "_kanban_stop_nudges", 0) + 1
  174. final_msg["finish_reason"] = "kanban_terminal_required"
  175. final_msg["_kanban_stop_synthetic"] = True
  176. append_message(messages, final_msg)
  177. verdict = _continue(_kanban_nudge, "_kanban_stop_synthetic")
  178. logger.info(
  179. "kanban stop-loop nudge issued (attempt %d) task=%s",
  180. agent._kanban_stop_nudges,
  181. os.environ.get("HERMES_KANBAN_TASK", ""),
  182. )
  183. agent._emit_diagnostic_status(
  184. "⚠️ Kanban worker tried to exit without a terminal board call "
  185. "(kanban_complete/kanban_request_review/kanban_block) — nudging to finish"
  186. )
  187. return verdict
  188. return StopGateVerdict(
  189. continue_turn=False, final_response=final_response,
  190. pending_verification_response=pending_verification_response,
  191. pending_verification_response_previewed=pending_verification_response_previewed,
  192. )