| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223 |
- """Text-response stop gates for the conversation turn loop.
- When the model stops with a text answer, four gates may instead append the answer as an
- interim row plus a user-role nudge and continue the turn: late language-server verdicts on this
- turn's edits (a durable row, see ``_late_lsp_verdicts``), verify-on-stop (#65919),
- the ``pre_verify`` plugin hook after code edits, and the kanban worker terminal-tool guard.
- Each keeps the candidate answer as a budget-exhaustion fallback
- (``pending_verification_response``) and clears ``final_response`` so the finalizer can tell
- this gate from error exits (#61631). Nothing here imports ``agent.conversation_loop`` at
- module level (cycle).
- """
- from __future__ import annotations
- import logging
- import os
- from dataclasses import dataclass
- from typing import Any, Dict, List, Optional
- from agent.message_metadata import append_message
- logger = logging.getLogger("agent.conversation_loop")
- @dataclass
- class StopGateVerdict:
- """``continue_turn`` True → a nudge was appended; re-enter the turn loop with
- ``final_response=None`` and the pending-verification fields updated."""
- continue_turn: bool
- final_response: Any
- pending_verification_response: Any
- pending_verification_response_previewed: Any
- def _verify_on_stop_nudge(agent) -> Optional[str]:
- try:
- from agent.verification_stop import (
- build_verify_on_stop_nudge, verify_on_stop_enabled
- )
- if verify_on_stop_enabled():
- return build_verify_on_stop_nudge(
- session_id=getattr(agent, "session_id", None),
- changed_paths=getattr(agent, "_turn_file_mutation_paths", set()),
- attempts=getattr(agent, "_verification_stop_nudges", 0),
- )
- except Exception:
- logger.debug("verification stop-loop check failed", exc_info=True)
- return None
- def _pre_verify_nudge(agent, final_response, attempt: int) -> Optional[str]:
- """After code edits a registered ``pre_verify`` hook may keep the agent going one
- more turn; no default continuation cost."""
- _edited = sorted(getattr(agent, "_turn_file_mutation_paths", set()) or [])
- try:
- from agent.verify_hooks import max_verify_nudges
- from hermes_cli.lifecycle import has_hook
- from hermes_cli.plugins import get_pre_verify_continue_message
- if _edited and has_hook("pre_verify") and attempt < max_verify_nudges():
- # Posture is fixed for the session — resolve once + cache.
- coding = getattr(agent, "_resolved_is_coding", None)
- if coding is None:
- from agent.coding_context import is_coding_context
- coding = bool(is_coding_context(platform=getattr(agent, "platform", "") or ""))
- agent._resolved_is_coding = coding
- return get_pre_verify_continue_message(
- session_id=getattr(agent, "session_id", None) or "",
- platform=getattr(agent, "platform", "") or "",
- model=getattr(agent, "model", "") or "", coding=coding, attempt=attempt,
- final_response=final_response, changed_paths=_edited,
- )
- except Exception:
- logger.debug("pre_verify hook check failed", exc_info=True)
- return None
- def _kanban_stop_nudge(agent, messages) -> Optional[str]:
- """Workers must end with a terminal board tool (kanban_complete / kanban_block /
- kanban_request_review / kanban_request_changes); a narrated stop is recorded
- as protocol_violation, so nudge once or twice first."""
- try:
- from agent.kanban_stop import build_kanban_stop_nudge
- return build_kanban_stop_nudge(
- messages=messages, attempts=getattr(agent, "_kanban_stop_nudges", 0)
- )
- except Exception:
- logger.debug("kanban stop-loop check failed", exc_info=True)
- return None
- _MAX_LSP_TURN_END_NOTES = 3
- def _late_lsp_verdicts(agent) -> Optional[str]:
- """Language-server verdicts on this turn's edits that no tool result carried yet (the edit was the
- last tool call; a one-shot run has no next turn to carry them): waits briefly for checks still
- running (``agent.lsp.deferred.settle_for_agent``) and returns them as a message for the model."""
- issued = getattr(agent, "_lsp_turn_end_notes", 0)
- if not isinstance(issued, int) or issued >= _MAX_LSP_TURN_END_NOTES:
- return None
- try:
- from agent.lsp.deferred import settle_for_agent
- notes = settle_for_agent(agent)
- except Exception:
- logger.debug("late LSP verdict check failed", exc_info=True)
- return None
- if not notes:
- return None
- body = "\n\n".join(text for _path, text in notes)
- return ("[System note: the language server reported problems in files you edited this turn, after "
- "those tool results had returned. Fix them if they are real, then give your final answer.]\n\n"
- + body)
- def _append_interim_answer(agent, final_msg, messages, conversation_history, flush_fail_msg: str) -> None:
- """Real content: persist and emit as interim so the user sees the attempted answer;
- only the nudge is flagged synthetic (#65919). A held turn's answer (typed hidden) is not shown
- and flushes with the turn instead, so a budget fallback can still publish it as the rewrite."""
- agent._emit_interim_assistant_message(final_msg)
- append_message(messages, final_msg)
- if final_msg.get("display_kind") == "hidden":
- return
- try:
- agent._flush_messages_to_session_db(messages, conversation_history)
- except Exception:
- logger.debug(flush_fail_msg, exc_info=True)
- def apply_stop_gates(
- agent: Any, final_msg: dict[str, Any], *, final_response: Any, messages: list[dict[str, Any]],
- conversation_history: Any, pending_verification_response: Any,
- pending_verification_response_previewed: Any,
- ) -> StopGateVerdict:
- """Run verify-on-stop → pre_verify hook → kanban stop guard, in that order. Nudges
- are user-role rows appended only after the assistant answer row, so role alternation
- holds. Hook lookups are imported lazily from their origin modules (tests patch them
- there)."""
- def _continue(nudge: str, flag: str) -> StopGateVerdict:
- """Append the synthetic nudge row and hand the turn back to the loop."""
- append_message(messages, {"role": "user", "content": nudge, flag: True})
- agent._session_messages = messages
- # Keep the answer only as a budget-exhaustion fallback; clear ``final_response`` so
- # the finalizer can tell this gate from error exits. Mark previewed only if the
- # candidate is reused (#61631).
- return StopGateVerdict(
- continue_turn=True, final_response=None,
- pending_verification_response=final_response,
- # Prefix semantics on purpose: the streamed prefix IS on screen here. The gateway
- # interim verdict uses _interim_content_fully_streamed instead (#88954).
- pending_verification_response_previewed=agent._interim_content_was_streamed(
- final_response or ""
- ),
- )
- _lsp_note = _late_lsp_verdicts(agent)
- if _lsp_note:
- agent._lsp_turn_end_notes = getattr(agent, "_lsp_turn_end_notes", 0) + 1 # int: checked above
- final_msg["finish_reason"] = "verification_required"
- _append_interim_answer(
- agent, final_msg, messages, conversation_history, "late-LSP interim flush failed"
- )
- # A durable row (no scaffolding flag): it is never stripped, so no sent byte changes later.
- append_message(messages, {"role": "user", "content": _lsp_note})
- agent._session_messages = messages
- logger.debug("late LSP verdicts delivered before the final answer (%d)", agent._lsp_turn_end_notes)
- return StopGateVerdict(
- continue_turn=True, final_response=None,
- pending_verification_response=final_response,
- pending_verification_response_previewed=agent._interim_content_was_streamed(final_response or ""),
- )
- _verify_nudge = _verify_on_stop_nudge(agent)
- if _verify_nudge:
- agent._verification_stop_nudges = getattr(agent, "_verification_stop_nudges", 0) + 1
- final_msg["finish_reason"] = "verification_required"
- _append_interim_answer(
- agent, final_msg, messages, conversation_history, "verify-on-stop interim flush failed"
- )
- verdict = _continue(_verify_nudge, "_verification_stop_synthetic")
- # Internal nudge: stay silent on the terminal, debug-log only.
- logger.debug("verification stop-loop nudge issued (attempt %d)", agent._verification_stop_nudges)
- return verdict
- _attempt = getattr(agent, "_pre_verify_nudges", 0)
- _verify_nudge2 = _pre_verify_nudge(agent, final_response, _attempt)
- if _verify_nudge2:
- agent._pre_verify_nudges = _attempt + 1
- final_msg["finish_reason"] = "verify_hook_continue"
- _append_interim_answer(
- agent, final_msg, messages, conversation_history, "pre_verify interim flush failed"
- )
- verdict = _continue(_verify_nudge2, "_pre_verify_synthetic")
- logger.debug("pre_verify nudge issued (attempt %d)", agent._pre_verify_nudges)
- return verdict
- _kanban_nudge = _kanban_stop_nudge(agent, messages)
- if _kanban_nudge:
- agent._kanban_stop_nudges = getattr(agent, "_kanban_stop_nudges", 0) + 1
- final_msg["finish_reason"] = "kanban_terminal_required"
- final_msg["_kanban_stop_synthetic"] = True
- append_message(messages, final_msg)
- verdict = _continue(_kanban_nudge, "_kanban_stop_synthetic")
- logger.info(
- "kanban stop-loop nudge issued (attempt %d) task=%s",
- agent._kanban_stop_nudges,
- os.environ.get("HERMES_KANBAN_TASK", ""),
- )
- agent._emit_diagnostic_status(
- "⚠️ Kanban worker tried to exit without a terminal board call "
- "(kanban_complete/kanban_request_review/kanban_block) — nudging to finish"
- )
- return verdict
- return StopGateVerdict(
- continue_turn=False, final_response=final_response,
- pending_verification_response=pending_verification_response,
- pending_verification_response_previewed=pending_verification_response_previewed,
- )
|