turn_final_response.py 22 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432
  1. """No-tool-call (final text) branch of the conversation turn loop: empty/think-only recovery,
  2. intent-ack / stall-guard continuation, length-continuation joining, dropped-tool-call
  3. re-prompt, scaffolding pop, stop gates, then the durable final flush. Extracted from
  4. ``run_conversation``; nothing here imports ``agent.conversation_loop`` at module level
  5. (cycle) — loop-internal nudge constants resolve lazily.
  6. """
  7. from __future__ import annotations
  8. from dataclasses import dataclass
  9. from contextlib import nullcontext
  10. import logging
  11. from typing import Any, Callable, Dict, Optional
  12. from agent.message_metadata import append_message
  13. from agent.reasoning_promotion import answer_in_reasoning_capability
  14. from agent.repetition_guard import STOP_PATH_MIN_CHARS, is_runaway_repetition
  15. from agent.stream_delivery import publish_held_final_row
  16. from agent.turn_failure_copy import stamp_failure
  17. from agent.turn_empty_response import (
  18. housekeeping_reply_line, recover_empty_response, take_housekeeping_reply_line,
  19. )
  20. from agent.turn_stop_gates import apply_stop_gates
  21. from agent.turn_truncation import partial_result, repetition_copy
  22. _REPETITION_STOPPED = repetition_copy(
  23. "before delivery",
  24. "so the repeated output was discarded.",
  25. "; refusing to return a",
  26. )
  27. logger = logging.getLogger("agent.conversation_loop")
  28. # Ephemeral retry scaffolding rows popped before the final answer becomes durable.
  29. _EPHEMERAL_SCAFFOLDING_FLAGS = (
  30. "_thinking_prefill", "_empty_recovery_synthetic", "_empty_terminal_sentinel",
  31. "_dropped_toolcall_nudge",
  32. )
  33. @dataclass
  34. class FinalResponseVerdict:
  35. """``action``: ``"break"`` (turn ends with ``final_response``), ``"continue"`` (a
  36. continuation/re-prompt/stop-gate asked for another API call), ``"redirect"``
  37. (a late correction needs a bounded same-iteration restart) or ``"return"``
  38. (``result`` is the turn's result dict). The other fields are the loop locals rebound."""
  39. action: str
  40. active_system_prompt: Any
  41. final_response: Any
  42. _turn_exit_reason: Any
  43. _preflight_compression_blocked: Any
  44. codex_ack_continuations: Any
  45. truncated_response_parts: Any
  46. length_continue_retries: Any
  47. _pending_verification_response: Any
  48. _pending_verification_response_previewed: Any
  49. api_call_count: int
  50. result: Optional[dict[str, Any]] = None
  51. def _bare_marker_after_reply(agent: Any, final_response: Any, *, truncated_parts: Any = None,
  52. promoted: Any = None) -> bool:
  53. """End this turn on the reply written beside a housekeeping round instead of its bare marker:
  54. only when the host says a marker may not stay silent (``_silence_marker_needs_reply``), for a
  55. complete uninterrupted response, and only when a real (non-marker) reply line exists."""
  56. from gateway.response_filters import is_intentional_silence_response
  57. if (getattr(agent, "_silence_marker_needs_reply", False) is not True or truncated_parts or promoted
  58. or getattr(agent, "_interrupt_requested", False)):
  59. return False
  60. reply = housekeeping_reply_line(agent)
  61. return (bool(reply) and not is_intentional_silence_response(reply)
  62. and is_intentional_silence_response(agent._strip_think_blocks(final_response or "").strip()))
  63. def _recover_marker_reply(
  64. agent: Any, final_response: Any, verdict: Callable[[str], FinalResponseVerdict], *,
  65. truncated_parts: Any, promoted: Any,
  66. ) -> Optional[FinalResponseVerdict]:
  67. """Select a completed housekeeping reply before output transforms and persistence.
  68. Keep the caller's loop state, changing only the chosen final and its exit reason.
  69. Other hosts and permitted silence continue through normal text handling.
  70. """
  71. if not _bare_marker_after_reply(agent, final_response, truncated_parts=truncated_parts, promoted=promoted):
  72. return None
  73. result = verdict("break")
  74. result.final_response = take_housekeeping_reply_line(agent)
  75. result._turn_exit_reason = "fallback_prior_turn_content"
  76. logger.info("Silence marker after a written reply: using that reply as the final response")
  77. return result
  78. def _absorb_continuation_fragments(final_response: Any, parts: Any, messages: Any) -> tuple[Any, bool]:
  79. """Stitch length-continuation fragments in front of the closing piece; True when there were
  80. any. The continuation recovered, so the fragment rows stay in the transcript, unflagged."""
  81. if not parts:
  82. return final_response, False
  83. from agent.conversation_loop import _join_truncated_parts
  84. for frag in messages:
  85. if isinstance(frag, dict):
  86. frag.pop("_length_continuation_fragment", None)
  87. frag.pop("_length_continuation_nudge", None)
  88. return _join_truncated_parts([*parts, (final_response, False)]), True
  89. def finish_text_response(
  90. agent: Any, *, assistant_message: Any, response: Any, finish_reason: Any, messages: Any,
  91. api_messages: Any, conversation_history: Any, api_call_count: Any, user_message: Any,
  92. active_system_prompt: Any, final_response: Any, _turn_exit_reason: Any,
  93. _preflight_compression_blocked: Any, codex_ack_continuations: Any,
  94. truncated_response_parts: Any, length_continue_retries: Any,
  95. _pending_verification_response: Any, _pending_verification_response_previewed: Any,
  96. effective_task_id: Any,
  97. ) -> FinalResponseVerdict:
  98. """Finish (or defer) a text-only assistant response in the original guard order. Every
  99. continuation path sets ``final_response = None`` so an acknowledgment never suppresses
  100. iteration-limit summarization; the final message is appended and flushed only after the
  101. stop gates accept it."""
  102. from agent.conversation_loop import (
  103. _CODEX_ACK_CONTINUATION_NUDGE, _DEGENERATE_FINAL_NUDGE, _DROPPED_TOOLCALL_NUDGE_CONTENT,
  104. )
  105. def _verdict(action: str, result: Optional[dict[str, Any]] = None) -> FinalResponseVerdict:
  106. return FinalResponseVerdict(
  107. action=action, active_system_prompt=active_system_prompt, final_response=final_response,
  108. _turn_exit_reason=_turn_exit_reason,
  109. _preflight_compression_blocked=_preflight_compression_blocked,
  110. codex_ack_continuations=codex_ack_continuations,
  111. truncated_response_parts=truncated_response_parts,
  112. length_continue_retries=length_continue_retries,
  113. _pending_verification_response=_pending_verification_response,
  114. _pending_verification_response_previewed=_pending_verification_response_previewed,
  115. api_call_count=api_call_count,
  116. result=result,
  117. )
  118. # Reasoning-only clean stop on a trusted route (elsewhere reasoning is private and takes the
  119. # ladder): some parsers (vLLM nemotron_v3 past ~500K prompt tokens) file the whole answer as
  120. # reasoning when the closing delimiter is missing; ``stop`` means generation is complete, so
  121. # promote it BEFORE the ladder. ``length`` (cut off mid-thought) stays on the continuation path.
  122. # The promoted text is RETURNED as the answer but never written into the assistant
  123. # row's ``content``: chain-of-thought stored as ordinary content is indistinguishable
  124. # from a real reply on every history surface (#111761). The row keeps ``content``
  125. # empty with the text in its reasoning fields and carries the promoted text as the
  126. # ``api_content`` sidecar, so the next turn still replays it byte-identically.
  127. # Anthropic thinking (signed ``thinking`` block, or a plugin's ``*.native_assistant`` carrier
  128. # of native Claude turns) is a summary written by a separate model, never the answer: it
  129. # takes the empty-response continuation below instead.
  130. _content = assistant_message.content
  131. _promoted = None
  132. if (
  133. finish_reason == "stop"
  134. and not assistant_message.tool_calls
  135. and (_content is None or (isinstance(_content, str) and not _content.strip()))
  136. and not any(
  137. isinstance(d, dict) and (
  138. (d.get("type") in ("thinking", "redacted_thinking") and (d.get("signature") or d.get("data")))
  139. or str(d.get("type") or "").endswith(".native_assistant")
  140. )
  141. for d in getattr(assistant_message, "reasoning_details", None) or ()
  142. )
  143. and answer_in_reasoning_capability(agent)
  144. ):
  145. _promoted = agent._extract_reasoning(assistant_message) or None
  146. if _promoted:
  147. # WARNING, not INFO: a model that keeps ending turns this way is stalled
  148. # (planning monologue, zero tool calls) while the turn reports "complete".
  149. logger.warning(
  150. "Reasoning-only clean stop (%d chars) — returning the reasoning as the final "
  151. "response (model=%s provider=%s api_calls=%d tool_turns=%d)",
  152. len(_promoted), agent.model, agent.provider, api_call_count,
  153. sum(1 for m in messages if isinstance(m, dict) and m.get("role") == "assistant" and m.get("tool_calls")),
  154. )
  155. final_response = _promoted or assistant_message.content or ""
  156. # Unmute: _mute_post_response from a housekeeping tool turn must not silence
  157. # empty-response warnings on the final response path.
  158. agent._mute_post_response = False
  159. # Think-block-only / empty content: recovery path.
  160. if not agent._has_content_after_think_block(final_response):
  161. _ev = recover_empty_response(
  162. agent, assistant_message, response, finish_reason, final_response=final_response,
  163. messages=messages, api_messages=api_messages, conversation_history=conversation_history,
  164. active_system_prompt=active_system_prompt, api_call_count=api_call_count,
  165. turn_exit_reason=_turn_exit_reason,
  166. preflight_compression_blocked=_preflight_compression_blocked,
  167. )
  168. final_response = _ev.final_response
  169. _turn_exit_reason = _ev.turn_exit_reason
  170. active_system_prompt = _ev.active_system_prompt
  171. _preflight_compression_blocked = _ev.preflight_compression_blocked
  172. api_call_count = _ev.api_call_count
  173. return _verdict(_ev.action, _ev.result)
  174. agent._empty_content_retries = 0
  175. agent._thinking_prefill_retries = 0
  176. # Surface the one-shot fallback switch notice before dropping the retry buffer so a
  177. # provider/model switch stays visible on success.
  178. agent._emit_pending_fallback_notice()
  179. agent._clear_status_buffer()
  180. if marker_verdict := _recover_marker_reply(
  181. agent, final_response, _verdict, truncated_parts=truncated_response_parts, promoted=_promoted):
  182. return marker_verdict
  183. # Defensive: repair malformed role-alternation before API call. Catches cases where the history got
  184. # wedged into a ``tool → user`` or ``user → user`` tail (e.g. after empty- response scaffolding was
  185. # stripped and a new user message landed after an orphan tool result). Most providers return empty
  186. # content on malformed sequences, which would otherwise retrigger the empty-retry loop indefinitely.
  187. # repair_message_sequence_with_cursor also recomputes the SessionDB flush cursor (_last_flushed_db_idx)
  188. # when repair compacts the list, so the turn-end flush doesn't skip the assistant/tool chain (#44837).
  189. # One-time repeated-heal escalation notice (#96870): if the sanitizer above just crossed the per-session
  190. # heal threshold, deliver the queued notice through the status/warning callback — the normal out-of-band
  191. # delivery channel (gateway status message / CLI print). NEVER appended to messages/api_messages:
  192. # conversation context and the cached prompt prefix stay byte-identical.
  193. from agent.agent_runtime_helpers import (
  194. intent_ack_continuation_mode, looks_like_degenerate_final, promoted_reasoning_announces_action,
  195. tool_results_this_turn, trailing_continue_intent,
  196. )
  197. _ack_mode = intent_ack_continuation_mode(agent)
  198. # Said-continue-but-stopped guard: no tool calls but the short reply TAILS with an
  199. # announced next action. Reuses the SAME bounded continuation counter (max 2 per turn).
  200. # Promoted reasoning gets the broader first-person-plan tail detector: with tools offered
  201. # and zero tool calls, chain-of-thought ending on "Let me batch the terminal calls..." is a
  202. # stalled model, and returning it as the answer aborts the tool loop while reporting
  203. # "complete" (#111761). Same cap, so a model that never acts still ends after 2 nudges.
  204. _stall_text = agent._strip_think_blocks(final_response or "")
  205. _stall_continue_intent = (
  206. bool(getattr(agent, "_stall_guards", True))
  207. and agent.valid_tool_names
  208. and codex_ack_continuations < 2
  209. and (
  210. trailing_continue_intent(_stall_text)
  211. or (bool(_promoted) and promoted_reasoning_announces_action(_stall_text))
  212. )
  213. )
  214. # Degenerate-final guard (#103483): the turn did real tool work and then stopped on a
  215. # fragment. Same scope knob and the SAME bounded counter as the ack continuation; the nudge
  216. # row itself closes the tool-work window, so a second fragment ends the turn as the answer.
  217. _tool_rows = tool_results_this_turn(messages)
  218. _degenerate_final = (
  219. bool(getattr(agent, "_stall_guards", True))
  220. and _ack_mode != "off"
  221. and codex_ack_continuations < 2
  222. and _tool_rows > 0
  223. and looks_like_degenerate_final(_stall_text, user_message=user_message)
  224. )
  225. # Precedence: an announced next action outranks the fragment shape; the codex ack is last.
  226. if _stall_continue_intent:
  227. _continuation_kind = "stall"
  228. elif _degenerate_final:
  229. _continuation_kind = "degenerate"
  230. elif (
  231. _ack_mode != "off"
  232. and agent.valid_tool_names
  233. and codex_ack_continuations < 2
  234. and agent._looks_like_codex_intermediate_ack(
  235. user_message=user_message, assistant_content=final_response, messages=messages,
  236. require_workspace=(_ack_mode == "codex_only"),
  237. )
  238. ):
  239. _continuation_kind = "ack"
  240. else:
  241. _continuation_kind = None
  242. if _continuation_kind:
  243. if _continuation_kind == "stall":
  244. logger.info(
  245. "Stall guard: turn ending on trailing continue-"
  246. "intent with no tool calls — re-prompting to act "
  247. "(%d/2)", codex_ack_continuations + 1,
  248. )
  249. elif _continuation_kind == "degenerate":
  250. logger.warning(
  251. "Degenerate final: %d-char fragment %r ended the turn after %d tool result(s) — "
  252. "re-prompting (%d/2)", len(_stall_text), _stall_text[:40], _tool_rows,
  253. codex_ack_continuations + 1,
  254. )
  255. codex_ack_continuations += 1
  256. interim_msg = agent._build_assistant_message(assistant_message, "incomplete")
  257. if _promoted:
  258. # Same sidecar as the final row: the wire copy must carry the promoted text, not only
  259. # ``reasoning_content``, or the continuation replays an empty assistant turn.
  260. interim_msg["api_content"] = final_response
  261. append_message(messages, interim_msg)
  262. agent._emit_interim_assistant_message(interim_msg)
  263. append_message(messages, {
  264. "role": "user",
  265. "content": (
  266. _DEGENERATE_FINAL_NUDGE if _continuation_kind == "degenerate"
  267. else _CODEX_ACK_CONTINUATION_NUDGE
  268. ),
  269. })
  270. agent._session_messages = messages
  271. # An acknowledgment is non-final: its text must not suppress iteration-limit
  272. # summarization if the continuation exhausts budget.
  273. final_response = None
  274. return _verdict("continue")
  275. codex_ack_continuations = 0
  276. final_response, _joined = _absorb_continuation_fragments(final_response, truncated_response_parts, messages)
  277. if _joined:
  278. truncated_response_parts, length_continue_retries = [], 0
  279. final_response = agent._strip_think_blocks(final_response).strip()
  280. # A provider may end a degenerate loop normally with finish_reason="stop" instead of
  281. # exhausting its output cap (#100716). Check every completed visible text response before
  282. # any verify/kanban interim emission or durable transcript write.
  283. # Runaway scale and shape only: a completed answer the user asked to be repetitive is
  284. # delivered, unlike a length-truncated fragment that burned the whole budget.
  285. if (
  286. final_response
  287. and len(final_response) >= STOP_PATH_MIN_CHARS
  288. and is_runaway_repetition(final_response)
  289. ):
  290. line, user_response, error = _REPETITION_STOPPED
  291. agent._vprint(f"{agent.log_prefix}{line}", force=True, diagnostic=True)
  292. agent._cleanup_task_resources(effective_task_id)
  293. agent._persist_session(messages, conversation_history)
  294. return _verdict("return", stamp_failure(
  295. partial_result(messages, api_call_count, user_response, error), "truncated", True,
  296. ))
  297. final_msg = agent._build_assistant_message(assistant_message, finish_reason)
  298. if _promoted:
  299. # Replay sidecar only: ``content`` stays empty so the row is never mistaken for a
  300. # real reply; ``build_api_messages`` substitutes ``api_content`` on the wire.
  301. final_msg["api_content"] = final_response
  302. # Dropped tool-call recovery (seen with Claude via gateways): finish_reason="tool_calls" with empty
  303. # tool_calls would end the turn unstarted; re-prompt (max 3 CONSECUTIVE stalls).
  304. if (
  305. finish_reason == "tool_calls"
  306. and not assistant_message.tool_calls
  307. and getattr(agent, "_dropped_toolcall_retries", 0) < 3
  308. ):
  309. agent._dropped_toolcall_retries = getattr(agent, "_dropped_toolcall_retries", 0) + 1
  310. logger.warning(
  311. "finish_reason=tool_calls with empty tool_calls array "
  312. "(narration only) — re-prompting to emit the call "
  313. "(retry %d/3, model=%s provider=%s)",
  314. agent._dropped_toolcall_retries, agent.model, agent.provider,
  315. )
  316. agent._emit_diagnostic_status(
  317. "↻ Model signaled a tool call but sent none — "
  318. f"re-prompting ({agent._dropped_toolcall_retries}/3)"
  319. )
  320. # Both halves of the re-prompt pair are ephemeral scaffolding: never persisted,
  321. # and the finalization pop strips an unanswered tail pair.
  322. final_msg["_dropped_toolcall_nudge"] = True
  323. append_message(messages, final_msg)
  324. append_message(messages, {
  325. "role": "user",
  326. "content": _DROPPED_TOOLCALL_NUDGE_CONTENT,
  327. "_dropped_toolcall_nudge": True,
  328. })
  329. agent._session_messages = messages
  330. final_response = None
  331. return _verdict("continue")
  332. # Genuine turn end (no dropped-tool-call mismatch): clear stall budget.
  333. agent._dropped_toolcall_retries = 0
  334. # Pop prefill / empty-retry scaffolding before the final response or
  335. # verification follow-up; it must not become durable transcript.
  336. while (
  337. messages
  338. and isinstance(messages[-1], dict)
  339. and any(messages[-1].get(flag) for flag in _EPHEMERAL_SCAFFOLDING_FLAGS)
  340. ):
  341. messages.pop()
  342. _sg = apply_stop_gates(
  343. agent, final_msg, final_response=final_response, messages=messages,
  344. conversation_history=conversation_history,
  345. pending_verification_response=_pending_verification_response,
  346. pending_verification_response_previewed=_pending_verification_response_previewed,
  347. )
  348. _pending_verification_response = _sg.pending_verification_response
  349. _pending_verification_response_previewed = _sg.pending_verification_response_previewed
  350. if _sg.continue_turn:
  351. final_response = None
  352. return _verdict("continue")
  353. # Plugins rewrite the reply BEFORE it is appended and flushed: SQLite treats a non-blank
  354. # assistant row as settled, so a transform after this write would reach the user but never
  355. # the stored/replayed transcript (#44239). finalize_turn reads the recorded outcome; like
  356. # there, an interrupted turn keeps the raw text.
  357. from agent.turn_finalizer import apply_llm_output_transform
  358. _transformed = False
  359. if not getattr(agent, "_interrupt_requested", False):
  360. final_response, _transformed, _ = apply_llm_output_transform(
  361. agent, final_response, turn_id=getattr(agent, "_current_turn_id", "") or "", logger=logger,
  362. )
  363. if _transformed:
  364. if _promoted:
  365. final_msg["api_content"] = final_response
  366. else:
  367. final_msg["content"] = final_response
  368. publish_held_final_row(agent, final_msg, final_response, _joined)
  369. # Serialize acceptance against the final reply commit, not the end of the
  370. # HTTP request. Corrections during output processing still belong to this turn.
  371. with getattr(agent, "_pending_redirect_lock", None) or nullcontext():
  372. if getattr(agent, "_turn_redirect_open", False):
  373. if agent._pending_redirect:
  374. agent._llm_output_transform = None # the discarded reply never became durable
  375. final_response = None
  376. return _verdict("redirect")
  377. agent._turn_redirect_open = False
  378. append_message(messages, final_msg)
  379. # Make the answer durable before leaving the loop (_DB_PERSISTED_MARKER keeps
  380. # _persist_session idempotent). Failure must NOT abort the turn: finalize retries.
  381. try:
  382. agent._flush_messages_to_session_db(messages, conversation_history)
  383. except Exception:
  384. logger.warning(
  385. "final text-turn flush failed (session=%s) — reply is "
  386. "not yet durable; relying on finalize_turn retry",
  387. getattr(agent, "session_id", None) or "none",
  388. exc_info=True,
  389. )
  390. _turn_exit_reason = f"text_response(finish_reason={finish_reason})"
  391. if not agent.quiet_mode:
  392. agent._safe_print(f"🎉 Conversation completed after {api_call_count} OpenAI-compatible API call(s)")
  393. return _verdict("break")