turn_context.py 73 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432
  1. """Per-turn setup for ``run_conversation`` (the turn prologue).
  2. ``build_turn_context`` runs the once-per-turn setup (stdio guard, sanitization, prompt
  3. restore-or-build, session row, idle/preflight compaction via ``turn_context_compaction``,
  4. pre_llm_call hook, prefetch, persistence), mutating ``agent`` as the loop expects, and
  5. returns a ``TurnContext`` with only the locals the loop reads back.
  6. ``build_api_messages`` builds the wire copy for one API call."""
  7. from __future__ import annotations
  8. import logging
  9. import sys
  10. import threading
  11. import time
  12. import uuid
  13. from contextlib import suppress
  14. from dataclasses import dataclass
  15. from typing import Any, Dict, List, Mapping, Optional, Tuple
  16. from agent.conversation_compression import recover_rotated_compression_session
  17. from agent.iteration_budget import IterationBudget
  18. from agent.memory_context import build_memory_context_block
  19. from agent.memory_provider import is_trivial_prompt
  20. from agent.message_content import flatten_message_text
  21. from agent.lsp.deferred import forward_to_agent as forward_lsp_verdicts
  22. from agent.plugin_live_notes import pop_plugin_notices
  23. from agent.skills_index_delta import stage_skills_index_note
  24. from agent.prompt_refresh import refresh_warm_prompt
  25. from agent.message_metadata import (
  26. PERSISTENCE_ONLY_MESSAGE_FIELDS, PRE_LLM_BLOCK_WITHHELD_PROMPT, append_message, stamp_message_timestamp,
  27. )
  28. from agent.model_metadata import (
  29. estimate_messages_tokens_rough,
  30. estimate_native_anthropic_request_tokens_rough,
  31. estimate_request_tokens_rough,
  32. )
  33. from agent.image_token_cost import bind_image_token_cost
  34. from agent.usage_anchor import anchored_context_tokens, restore_usage_anchor
  35. from agent.turn_author import parse_turn_author
  36. logger = logging.getLogger(__name__)
  37. def _str_attr(agent: Any, name: str) -> str:
  38. """``getattr(agent, name, "") or ""`` — route facts read off partial agents/doubles."""
  39. return getattr(agent, name, "") or ""
  40. def _preflight_request_tokens(
  41. agent: Any, messages: list[dict[str, Any]], system_prompt: str
  42. ) -> int:
  43. """Token estimate for automatic preflight compression: a valid provider usage anchor,
  44. else the checkpoint-pruned native wire payload, else the generic estimator."""
  45. anchored = anchored_context_tokens(messages, getattr(agent, "_usage_anchor", None))
  46. agent._request_pressure_anchored = anchored is not None
  47. if anchored is not None:
  48. return anchored
  49. tools = getattr(agent, "tools", None) or None
  50. try:
  51. from agent.codex_responses_adapter import estimate_native_responses_preflight_tokens
  52. native = estimate_native_responses_preflight_tokens(
  53. agent, messages, system_prompt=system_prompt or "", tools=tools
  54. )
  55. if isinstance(native, int) and not isinstance(native, bool) and native >= 0:
  56. return native
  57. except Exception:
  58. logger.debug(
  59. "native Responses preflight estimate unavailable; "
  60. "using generic transcript estimate",
  61. exc_info=True,
  62. )
  63. charge_stale_thinking = _agent_stale_thinking_on_wire(agent)
  64. estimate_messages = messages
  65. if charge_stale_thinking and getattr(agent, "api_mode", "") == "anthropic_messages":
  66. from agent.anthropic_thinking_policy import native_anthropic_preserves_prior_thinking
  67. if native_anthropic_preserves_prior_thinking(
  68. getattr(agent, "base_url", ""), getattr(agent, "model", "")
  69. ):
  70. from agent.anthropic_thinking_replay import apply_rejected_thinking_suppression
  71. # Preflight runs on canonical history, while the eventual request is a
  72. # filtered copy. Mirror suppression onto shallow message copies before
  73. # pricing the exact native replay carriers.
  74. estimate_messages = [
  75. dict(message) if isinstance(message, dict) else message
  76. for message in messages
  77. ]
  78. apply_rejected_thinking_suppression(agent, estimate_messages)
  79. return estimate_native_anthropic_request_tokens_rough(
  80. estimate_messages, system_prompt=system_prompt or "", tools=tools
  81. )
  82. return estimate_request_tokens_rough(
  83. estimate_messages, system_prompt=system_prompt or "", tools=tools,
  84. charge_stale_thinking=charge_stale_thinking,
  85. )
  86. def _agent_stale_thinking_on_wire(agent: Any) -> bool:
  87. """Whether the active route replays stale thinking text; ``True`` (conservative full
  88. charge) when route facts are unavailable."""
  89. try:
  90. from agent.message_sanitization import stale_thinking_reaches_wire
  91. return stale_thinking_reaches_wire(
  92. *(_str_attr(agent, k) for k in ("api_mode", "provider", "model", "base_url"))
  93. )
  94. except Exception:
  95. return True
  96. def compose_multimodal_context_part(
  97. ext_prefetch_cache: str, plugin_user_context: str,
  98. ) -> Optional[str]:
  99. """The ephemeral context of one turn (memory prefetch + ``pre_llm_call``) as one text
  100. block; ``None`` when nothing is injected. The string sidecar appends it to ``content``;
  101. a multimodal (list) turn carries it as a durable text part (#71998)."""
  102. fenced = build_memory_context_block(ext_prefetch_cache) if ext_prefetch_cache else ""
  103. injections = [part for part in (fenced, plugin_user_context) if part]
  104. return "\n\n".join(injections) if injections else None
  105. def compose_user_api_content(
  106. content: Any, ext_prefetch_cache: str, plugin_user_context: str
  107. ) -> Optional[str]:
  108. """Compose the API-bound content of the current turn's string user message.
  109. Single source for the ``api_content`` sidecar and the wire bytes so they never drift
  110. (what turn N sends is what turn N+1 replays). ``None`` when nothing is injected or the
  111. content is not a string (list content takes the text-part path)."""
  112. if not isinstance(content, str):
  113. return None
  114. injection = compose_multimodal_context_part(ext_prefetch_cache, plugin_user_context)
  115. return None if injection is None else content + "\n\n" + injection
  116. def substitute_api_content(api_msg: dict[str, Any]) -> Optional[str]:
  117. """Pop the ``api_content`` sidecar and substitute it into ``content`` (keeps the
  118. prompt-cache prefix byte-stable). Returns the popped sidecar, or ``None``."""
  119. sidecar = api_msg.pop("api_content", None)
  120. if isinstance(sidecar, str) and sidecar and api_msg.get("role") in ("user", "assistant"):
  121. api_msg["content"] = sidecar
  122. return sidecar
  123. def drop_stale_api_content(msg: dict[str, Any]) -> None:
  124. """Drop the ``api_content`` sidecar from a message whose content was rewritten
  125. (replaying it would resend what the rewrite removed; cost is one cache miss)."""
  126. msg.pop("api_content", None)
  127. def extract_api_content_sidecar(msg: Mapping[str, Any]) -> Optional[str]:
  128. """Extract the ``api_content`` sidecar; ``None`` when absent/non-string."""
  129. v = msg.get("api_content")
  130. return v if isinstance(v, str) else None
  131. def _pop_turn_note(agent: Any, attr: str) -> str:
  132. """One-shot per-turn note: read and clear, so the system prompt stays byte-stable and a
  133. cached agent never replays a stale note."""
  134. note = getattr(agent, attr, "") or ""
  135. if hasattr(agent, attr):
  136. with suppress(Exception):
  137. setattr(agent, attr, "")
  138. return note if isinstance(note, str) else ""
  139. def consume_gateway_turn_context_notes(agent: Any) -> str:
  140. """Pop the gateway's per-turn must-deliver notes."""
  141. return _pop_turn_note(agent, "_gateway_turn_context_notes")
  142. def consume_surface_switch_note(agent: Any) -> str:
  143. """Pop the surface-switch note staged by the system-prompt restore (#104414); rides the same
  144. user-message channel as the gateway notes, behind the cached prefix."""
  145. return _pop_turn_note(agent, "_surface_switch_note")
  146. def consume_skills_index_note(agent: Any) -> str:
  147. """Pop the skills-index delta staged by the system-prompt restore; same channel as above."""
  148. return _pop_turn_note(agent, "_skills_index_note")
  149. def append_notes_to_multimodal_content(content: Any, notes: Optional[str]) -> bool:
  150. """Append must-deliver notes as a durable text part on a multimodal (list) user
  151. message (the sidecar path returns ``None`` for non-string content)."""
  152. if not notes or not isinstance(content, list):
  153. return False
  154. with suppress(Exception):
  155. content.append({"type": "text", "text": notes})
  156. return True
  157. return False
  158. # Cron sessions are never auto-titled: cron names its own session and its opener is a delivery hint.
  159. # Subagent runs get a cheap ``Subagent: <goal>`` title instead of a model call (apply_subagent_title).
  160. _UNTITLED_PLATFORMS = frozenset({"cron"})
  161. def _maybe_title_session_at_turn_start(
  162. agent: Any, messages: list[Any], title_user_message: Optional[str] = None,
  163. ) -> None:
  164. """Kick off auto-titling for the session's first user message; never fatal."""
  165. session_db = getattr(agent, "_session_db", None)
  166. session_id = getattr(agent, "session_id", None)
  167. if not session_db or not session_id:
  168. return
  169. platform = str(getattr(agent, "platform", "") or "").lower()
  170. if platform in _UNTITLED_PLATFORMS:
  171. return
  172. try:
  173. from agent.message_content import flatten_message_text
  174. from agent.title_generator import apply_subagent_title, maybe_auto_title
  175. # Turn's user message as text; image-only turns yield "" and are skipped.
  176. user_text = ""
  177. title_preview = None
  178. for msg in reversed(messages or []):
  179. if isinstance(msg, dict) and msg.get("role") == "user":
  180. user_text = flatten_message_text(msg.get("content")).strip()
  181. metadata = msg.get("display_metadata")
  182. if isinstance(metadata, dict) and isinstance(metadata.get("title_preview"), str):
  183. title_preview = metadata["title_preview"]
  184. break
  185. if title_user_message is not None:
  186. user_text = title_user_message.strip()
  187. if not user_text:
  188. return
  189. # The session row is created lazily; force it now or the title write matches
  190. # zero rows.
  191. if not getattr(agent, "_session_db_created", False):
  192. ensure = getattr(agent, "_ensure_db_session", None)
  193. if callable(ensure):
  194. ensure()
  195. if not getattr(agent, "_session_db_created", False):
  196. return
  197. if platform == "subagent":
  198. apply_subagent_title(session_db, session_id, user_text)
  199. return
  200. # Snapshot runtime identity so the background titler can skip if the user
  201. # switches models before it fires.
  202. # ``session_id`` rides along so the background titler's OpenCode request carries the
  203. # same ``x-opencode-session`` affinity as the turn it belongs to (#112717).
  204. main_runtime = {
  205. k: getattr(agent, k, None)
  206. for k in ("model", "provider", "base_url", "api_key", "api_mode", "session_id")
  207. }
  208. # See #19027.
  209. upgrade = maybe_auto_title(
  210. session_db,
  211. session_id,
  212. user_text,
  213. conversation_history=messages,
  214. failure_callback=(
  215. getattr(agent, "_title_failure_callback", None)
  216. or getattr(agent, "_emit_auxiliary_failure", None)
  217. ),
  218. main_runtime=main_runtime,
  219. title_callback=getattr(agent, "_on_session_title", None),
  220. runtime_validator=lambda: (
  221. getattr(agent, "model", None) == main_runtime["model"]
  222. and getattr(agent, "provider", None) == main_runtime["provider"]
  223. ),
  224. title_preview=title_preview,
  225. )
  226. # Unstarted = the title call would share a self-hosted endpoint with this turn's request
  227. # (#117296); ``finalize_turn`` starts it once the model has answered.
  228. if upgrade is not None and upgrade.ident is None:
  229. agent._deferred_title_upgrade = upgrade
  230. except Exception:
  231. logger.debug("Turn-start auto-title dispatch failed", exc_info=True)
  232. def start_deferred_title_upgrade(agent: Any) -> None:
  233. """Fire the title upgrade ``_maybe_title_session_at_turn_start`` held back; no-op when none."""
  234. upgrade = getattr(agent, "_deferred_title_upgrade", None)
  235. if upgrade is None:
  236. return
  237. agent._deferred_title_upgrade = None
  238. from agent.title_generator import start_title_upgrade
  239. start_title_upgrade(upgrade)
  240. def reanchor_current_turn_user_idx(messages: list[Any], user_message: Any) -> int:
  241. """Locate this turn's user message after compaction rebuilt ``messages``.
  242. Prefers the LAST user message whose content exactly matches this turn's text, else
  243. the last user-originated turn; compaction handoffs are never the fallback.
  244. Returns -1 when there is no user-originated message.
  245. Compression replaces list entries with fresh copies (and may append a todo-snapshot user message or a
  246. restored user turn AFTER the surviving copy of the current turn's message), so a pre-compression index
  247. is meaningless. Prefer the LAST user message whose content exactly matches this turn's text — the
  248. surviving copy in the common case — so the injection stamp and the #48677 persist override can't land on
  249. a todo-snapshot or historical row. Fall back to the last *user-originated* turn when no exact match
  250. survives (merge-summary-into-tail rewrites the content but the trackers still need a live anchor).
  251. Compaction handoffs must never become the fallback anchor (#80622) — they are reference-only
  252. scaffolding, not the active ask.
  253. """
  254. from agent.context_compressor import user_originated_turn_view
  255. fallback = -1
  256. for i in range(len(messages) - 1, -1, -1):
  257. msg = messages[i]
  258. if not (isinstance(msg, dict) and msg.get("role") == "user"):
  259. continue
  260. # Typed synthetic current events keep their persistence anchor when raw
  261. # content is unchanged; not eligible for the human-only fallback below.
  262. if msg.get("content") == user_message:
  263. return i
  264. live_view = user_originated_turn_view(msg)
  265. if live_view is None:
  266. continue
  267. if live_view.get("content") == user_message:
  268. return i
  269. # Prefer a real human turn over a synthetic handoff / continuation marker
  270. # when the exact content was rewritten by merge-into-tail.
  271. if fallback < 0:
  272. fallback = i
  273. return fallback
  274. def export_current_turn_boundary(agent: Any, result: Any, user_message: Any) -> Any:
  275. """Stamp ``{turn_id, current_turn_user_idx}`` on a result envelope, proven against the
  276. exact ``result["messages"]`` projection it travels with.
  277. Hosts that settle their own transcript by index (hermes-webui) must never guess which
  278. row is the current user turn after this loop rewrote history (alternation repair,
  279. compaction, post-turn micro-compaction): a guessed index or a text match can relabel an
  280. identical historical prompt and claim its old answer as this turn's. So the producer
  281. exports the coordinate, computed on the final list, only when the addressed row is this
  282. turn's user message verbatim. Otherwise the keys are omitted and hosts fail closed.
  283. A preflight-timeout envelope carries the prior history without this turn's row (#7100), so a
  284. repeated prompt would resolve to its historical copy: nothing is exported there.
  285. """
  286. if not isinstance(result, dict) or result.get("turn_exit_reason") == "context_compression_timeout":
  287. return result
  288. messages = result.get("messages")
  289. turn_id = str(getattr(agent, "_current_turn_id", "") or "")
  290. if not isinstance(messages, list) or not turn_id or user_message is None:
  291. return result
  292. idx = reanchor_current_turn_user_idx(messages, user_message)
  293. if idx < 0 or idx >= len(messages):
  294. return result
  295. row = messages[idx]
  296. if not (isinstance(row, dict) and row.get("role") == "user"):
  297. return result
  298. from agent.context_compressor import user_originated_turn_view
  299. live_view = user_originated_turn_view(row)
  300. if row.get("content") != user_message and not (
  301. isinstance(live_view, dict) and live_view.get("content") == user_message
  302. ):
  303. return result # rewritten (merge-into-tail) row: not a proven boundary
  304. result["turn_id"] = turn_id
  305. result["current_turn_user_idx"] = idx
  306. return result
  307. def compression_made_progress(
  308. orig_len: int, new_len: int, orig_tokens: int, new_tokens: int
  309. ) -> bool:
  310. """``True`` if a compression pass materially reduced the request: fewer rows, or a
  311. >5% token cut with the same rows (same floor as the overflow-handler retry).
  312. Compression can succeed by summarising message contents — reducing the estimated request token count —
  313. without reducing the message row count. Treating row count as the sole progress signal false-positives
  314. on size-only wins and surfaces a misleading "Cannot compress further" failure even when post-compression
  315. tokens are well below the model context window. See issue #39548 for an observed case: 220 → 220
  316. messages, ~288k → ~183k tokens on a 1M-context model still triggered auto-reset.
  317. The token reduction must be *material* (>5%) to count as progress — the same floor the overflow-handler
  318. retry path uses (conversation_loop.py, 39550) — so a sub-5% wobble doesn't keep the multi-pass loop
  319. spinning. See #39550.
  320. """
  321. return new_len < orig_len or (orig_tokens > 0 and new_tokens < orig_tokens * 0.95)
  322. class PreflightCompressionTimedOut(RuntimeError):
  323. """Raised when an oversized turn cannot safely finish preflight."""
  324. def _fail_closed_after_preflight_timeout(agent, request_tokens: int) -> None:
  325. """Stop an oversized turn instead of sending its unchanged provider payload.
  326. Only a request the model cannot accept (above its context window, or of unknown fit) is stopped: a
  327. request that merely sits above the compression threshold is sent unchanged, exactly as the
  328. cooldown-blocked path sends it every turn — otherwise a slow summariser turns a session that still
  329. fits its window into a turn that can never run (#113646, #114594)."""
  330. from agent.conversation_compression import context_compression_timed_out, request_exceeds_model_window
  331. if not context_compression_timed_out(agent):
  332. return
  333. if request_exceeds_model_window(agent, request_tokens) is False:
  334. logger.warning(
  335. "Preflight compression timed out but the request (~%s tokens) fits the model window (%s); "
  336. "sending it uncompressed this turn",
  337. f"{request_tokens:,}", f"{agent.context_compressor.context_length:,}",
  338. )
  339. return
  340. raise PreflightCompressionTimedOut(
  341. "Context compression timed out before it could commit while the request "
  342. f"was still approximately {request_tokens:,} tokens. The provider call "
  343. "was not sent. Run /compress and wait for it to finish, then retry."
  344. )
  345. def _fail_closed_on_insufficient_progress(agent, request_tokens: int) -> None:
  346. """Stop an over-window turn the moment preflight proves it cannot shrink the session, with
  347. "start a new session" guidance, instead of sending a request the model cannot accept.
  348. ``_fail_closed_after_preflight_timeout`` only stops a turn whose compression wait timed out. A
  349. pass that ran and reclaimed nothing (or under 5%) on a request still above the model window used
  350. to fall through to the provider call: the provider rejected it, the overflow handler forced
  351. another compression pass, and each pass re-waited its budget while the UI sat blocked (#116472:
  352. ~356k tokens on a 131k window). Only a ``True`` verdict fails closed — an unknown window or a
  353. fitting request keeps the send-as-is behaviour — and a pass skipped by the summary-failure
  354. cooldown is a defer, not proof of incompressibility, so it keeps its typed cooldown result.
  355. """
  356. from agent.conversation_compression import compression_blocked_transiently, request_exceeds_model_window
  357. if request_exceeds_model_window(agent, request_tokens) is not True:
  358. return
  359. if compression_blocked_transiently(agent):
  360. return
  361. window = agent.context_compressor.context_length
  362. raise PreflightCompressionTimedOut(
  363. "Context compression could not bring this session under the model's context window "
  364. f"(~{request_tokens:,} tokens vs {window:,}). The provider call was not "
  365. "sent. Start a new session with /new; this session is too large to compress further."
  366. )
  367. def _review_fork_first_request_pending(agent: Any) -> bool:
  368. """Whether a detached review fork has yet to send its first provider request: it
  369. replays the parent's FULL snapshot as a warm cache read, so compaction must wait
  370. for that first response. Dormant without the attribute."""
  371. return bool(
  372. getattr(agent, "_review_defer_compaction_before_first_response", False)
  373. and not getattr(agent, "_turn_received_provider_response", False)
  374. )
  375. def _compression_warrants_another_preflight_pass(
  376. orig_tokens: int, new_tokens: int, threshold_tokens: int
  377. ) -> bool:
  378. """Another immediate summary only if still over threshold AND the previous pass cut
  379. tokens by >5%."""
  380. return new_tokens >= threshold_tokens and orig_tokens > 0 and new_tokens < orig_tokens * 0.95
  381. def _should_run_preflight_estimate(
  382. messages: list[dict[str, Any]], protect_first_n: int, protect_last_n: int, threshold_tokens: int
  383. ) -> bool:
  384. """Cheap gate for the (expensive) full preflight estimate: message count exceeds the
  385. protected ranges OR a rough char-based estimate crosses the threshold (few-but-huge
  386. case). The estimator undercounts by design (omits system/tools) so one large base64
  387. image is not mistaken for ~250K tokens."""
  388. return (
  389. len(messages) > protect_first_n + protect_last_n + 1
  390. or estimate_messages_tokens_rough(messages) >= threshold_tokens
  391. )
  392. def _should_idle_compact(
  393. *, enabled: bool, idle_after_seconds: int, idle_gap_seconds: float, tokens: int,
  394. floor_tokens: int, cooldown_active: bool, last_compaction_tokens: int = 0,
  395. ) -> bool:
  396. """Pure predicate: idle compaction fires after a wall-clock gap of
  397. ``idle_after_seconds`` (opt-in, <= 0 disables), independent of ``threshold_tokens``;
  398. never at/below ``floor_tokens`` or during a compression-failure cooldown.
  399. ``floor_tokens`` (``threshold_tokens × summary_target_ratio``) is a theoretical target a
  400. real pass routinely misses (system prompt, tool schemas and protected head/tail are
  401. incompressible), so a session compacted to above it would re-summarise on every idle
  402. resume without growing. ``last_compaction_tokens`` — what the previous pass actually
  403. produced (``ContextCompressor.last_compression_rough_tokens``, same rough shape as
  404. ``tokens``) — raises the floor to ``last + floor_tokens`` so the transcript must gain a
  405. floor's worth of NEW content first. ``0`` (nothing compacted yet / counter reset) keeps
  406. the original semantics exactly.
  407. A session that compacted to well above that target therefore stays above it forever, so every later idle
  408. resume re-runs a full summarisation over a transcript that has not grown — minutes of silently blocked
  409. prompt on a slow route, reclaiming nothing (#97239).
  410. """
  411. if not enabled or idle_after_seconds <= 0 or idle_gap_seconds < idle_after_seconds or cooldown_active:
  412. return False
  413. effective_floor = floor_tokens
  414. if last_compaction_tokens > 0:
  415. effective_floor = max(effective_floor, last_compaction_tokens + floor_tokens)
  416. return tokens > effective_floor
  417. @dataclass
  418. class TurnContext:
  419. """Values produced by the turn prologue and consumed by the turn loop."""
  420. user_message: str # sanitized inbound message (surrogates stripped)
  421. original_user_message: Any # clean text for transcripts / memory queries (no nudges)
  422. messages: list[dict[str, Any]] # working list for this turn (loop appends to it)
  423. conversation_history: Optional[list[dict[str, Any]]] # None after rotation
  424. active_system_prompt: Optional[str] # may be rebuilt by compression
  425. effective_task_id: str
  426. turn_id: str
  427. current_turn_user_idx: int # index of the current user turn within ``messages``
  428. should_review_memory: bool = False # post-turn memory review should fire
  429. plugin_user_context: str = "" # ``pre_llm_call`` context (appended to user message)
  430. plugin_block_message: str = "" # ``pre_llm_call`` veto: the turn ends with this, no inference
  431. ext_prefetch_cache: str = "" # external-memory prefetch, reused across iterations
  432. preflight_compression_blocked: bool = False # immediate retry proved ineffective
  433. def _persist_under_lock(agent: Any, fn, failure_msg: str, pending_cli_message: Any) -> None:
  434. """Run ``fn`` under the session persist lock (when the agent has one), log-and-swallow
  435. failures, then drop staged CLI input — unless it is an unmarked handoff kept for a
  436. close retry (once ``_db_persisted`` the close path must not treat it as pre-worker
  437. UI input). Eager clearing keeps a preflight crash from leaking stale input."""
  438. try:
  439. lock = getattr(agent, "_session_persist_lock", None)
  440. if lock is None:
  441. fn()
  442. else:
  443. with lock:
  444. fn()
  445. except Exception:
  446. logger.warning(failure_msg, agent.session_id or "none", exc_info=True)
  447. finally:
  448. if not isinstance(pending_cli_message, dict) or pending_cli_message.get("_db_persisted"):
  449. agent._pending_cli_user_message = None
  450. def _publish_runtime_main(agent: Any) -> None:
  451. """Tell auxiliary_client the live main provider/model for this turn (after primary
  452. restoration settled the runtime). Never raises: failure loses only the scope."""
  453. with suppress(Exception):
  454. from agent.auxiliary_client import set_runtime_main
  455. from agent.prompt_cache_scope import resolve_prompt_cache_scope_safe
  456. # Rotation-stable prompt-cache scope (lineage root), memoized per segment; a new
  457. # session uses the physical id until build_api_kwargs re-resolves.
  458. # Memoized per segment on the agent, so this is a DB walk at most once per segment — except a
  459. # brand-new session whose row lands later in turn setup (_ensure_db_session); that first turn falls
  460. # back to the physical id here and the first build_api_kwargs re-resolves. Stays valid through a
  461. # mid-turn compression rotation because the lineage root is by definition rotation-invariant
  462. # (#79017). Resolved with the never-raising variant OUTSIDE the argument list, so a resolution
  463. # failure can only lose the scope — never the whole runtime binding.
  464. _cache_scope = resolve_prompt_cache_scope_safe(agent) or ""
  465. set_runtime_main(
  466. _str_attr(agent, "provider"), _str_attr(agent, "model"),
  467. **{k: _str_attr(agent, k) for k in (
  468. "requested_provider", "base_url", "api_key", "api_mode", "auth_mode", "session_id"
  469. )},
  470. cache_scope=_cache_scope,
  471. )
  472. def _refresh_mcp_tools_between_turns(agent: Any) -> None:
  473. """Late-connecting MCP servers land in THIS turn's snapshot, before the first API
  474. call assembles ``tools=``. ``preserve_prefix`` keeps the tool array append-only so a
  475. flapping ``check_fn`` can't fork the cache."""
  476. try:
  477. # An authorization that committed after its connection card closed: same import-cost gate,
  478. # the module is loaded only in a process that ran a connection operation.
  479. if "tools.connectors.mcp" in sys.modules:
  480. from tools.connectors.mcp import adopt_late_connections
  481. adopt_late_connections(agent)
  482. # Import-cost gate: MCP tools are only registered by code that already imported
  483. # ``tools.mcp_tool`` (~0.4s); not in sys.modules => nothing to do.
  484. if not getattr(agent, "_skip_mcp_refresh", False) and "tools.mcp_tool" in sys.modules:
  485. from tools.mcp_tool_discovery import has_registered_mcp_tools
  486. from tools.mcp_tool_agent import refresh_agent_mcp_tools
  487. if has_registered_mcp_tools():
  488. refresh_agent_mcp_tools(agent, quiet_mode=True, preserve_prefix=True)
  489. except Exception:
  490. logger.debug("between-turns MCP tool refresh skipped", exc_info=True)
  491. def _bind_turn_identity(
  492. agent: Any, task_id: Optional[str], stream_callback, persist_user_message: Any,
  493. persist_user_timestamp: Optional[float], persist_user_platform_id: Optional[str],
  494. ) -> tuple[str, str]:
  495. """Stage callback/persist overrides on the agent and bind this turn's task and turn
  496. ids. Returns ``(effective_task_id, turn_id)``."""
  497. agent._stream_callback = stream_callback # picked up by _interruptible_api_call
  498. agent._persist_user_message_idx = None
  499. agent._persist_user_message_override = persist_user_message
  500. agent._persist_user_message_timestamp = persist_user_timestamp
  501. agent._persist_user_message_platform_id = persist_user_platform_id
  502. # Unique task_id when not provided isolates VMs between tasks.
  503. effective_task_id = task_id or str(uuid.uuid4())
  504. agent._current_task_id = effective_task_id
  505. agent._process_owner_task_ids = {*getattr(agent, "_process_owner_task_ids", ()), effective_task_id}
  506. turn_id = str(getattr(agent, "_relay_pending_turn_id", "") or "") or (
  507. f"{agent.session_id or 'session'}:{effective_task_id}:{uuid.uuid4().hex[:8]}"
  508. )
  509. agent._relay_pending_turn_id = None
  510. agent._current_turn_id = turn_id
  511. agent._current_api_request_id = ""
  512. # Tripwire: warn when this turn starts before the previous turn-end persist
  513. # (concurrent turns interleave transcript writes). Cleared in _persist_session.
  514. from agent.agent_runtime_helpers import note_turn_start
  515. note_turn_start(agent, turn_id)
  516. return effective_task_id, turn_id
  517. # Per-turn agent state reset at turn start (retry counters, guardrail halt, file-mutation
  518. # verifier). ``_turns_since_memory`` / ``_iters_since_skill`` are deliberately NOT reset.
  519. _PER_TURN_RESET_STATE: tuple[tuple[str, Any], ...] = (
  520. ("_invalid_tool_retries", 0), ("_invalid_json_retries", 0), ("_empty_content_retries", 0),
  521. ("_incomplete_scratchpad_retries", 0), ("_codex_incomplete_retries", 0),
  522. # Consecutive Codex reasoning-only (no answer, no tool call) responses, kept apart from
  523. # the aggregate incomplete count so a visible partial resets it (#67321).
  524. ("_codex_reasoning_only_streak", 0),
  525. ("_thinking_prefill_retries", 0), ("_post_tool_empty_retried", False),
  526. ("_last_content_with_tools", None), ("_last_content_tools_all_housekeeping", False),
  527. ("_reused_response_text", None),
  528. ("_mute_post_response", False), ("_unicode_sanitization_passes", 0),
  529. ("_tool_guardrail_halt_decision", None),
  530. ("_harness_metrics_turn", None),
  531. ("_iteration_budget_warning_injected", False),
  532. ("_run_budget_wrapup_injected", False), ("_verification_stop_nudges", 0),
  533. ("_pre_verify_nudges", 0), ("_lsp_turn_end_notes", 0),
  534. )
  535. def _reset_per_turn_agent_state(agent: Any) -> None:
  536. """Reset retry counters, guardrails, iteration and run budgets at turn start."""
  537. for name, value in _PER_TURN_RESET_STATE:
  538. setattr(agent, name, value)
  539. agent._turn_failed_file_mutations = {}
  540. agent._turn_file_mutation_paths = set()
  541. agent._tool_guardrails.reset_for_turn()
  542. _reset_consol = getattr(agent._memory_store, "reset_consolidation_failures", None)
  543. if callable(_reset_consol):
  544. _reset_consol()
  545. # Expiry clock for build_api_messages: admission time (not the input's platform-event
  546. # stamp, which can predate admission by minutes), frozen so every request this turn
  547. # sends identical bytes. Distinct from note_turn_start's _inflight_turn_started, a
  548. # tripwire slot cleared at persist.
  549. agent._current_turn_timestamp = time.time()
  550. # Pre-turn connection health check: clean up dead TCP connections.
  551. if agent.api_mode != "anthropic_messages":
  552. with suppress(Exception):
  553. if agent._cleanup_dead_connections():
  554. agent._emit_diagnostic_status(
  555. "🔌 Detected stale connections from a previous provider "
  556. "issue — cleaned up automatically. Proceeding with fresh "
  557. "connection."
  558. )
  559. # A stale streak against a local server that has since recovered must not fail this turn on arrival.
  560. with suppress(Exception):
  561. from agent.chat_completion_local import retry_recovered_local_server
  562. retry_recovered_local_server(agent)
  563. # Replay compression warning through status_callback for gateway platforms.
  564. if agent._compression_warning:
  565. agent._replay_compression_warning()
  566. agent._compression_warning = None # send once
  567. from agent.status_output import deliver_kept_startup_notices
  568. deliver_kept_startup_notices(agent)
  569. if getattr(agent, "_pending_startup_notices", None) or getattr(agent, "_pending_startup_prints", None):
  570. # gateway: init ran before this turn's callbacks / viewer print sink
  571. agent._replay_startup_warnings()
  572. agent.iteration_budget = IterationBudget(agent.max_iterations)
  573. # Wall-clock run budget: stamped only when configured (one wrap-up notice per run).
  574. agent._run_budget_started_at = (
  575. time.time() if getattr(agent, "run_budget_seconds", None) else None
  576. )
  577. # Reset the streaming context / think scrubbers at the top of each turn.
  578. for name in ("_stream_context_scrubber", "_stream_think_scrubber"):
  579. scrubber = getattr(agent, name, None)
  580. if scrubber is not None:
  581. scrubber.reset()
  582. def _stage_turn_user_message(
  583. agent: Any, user_message: Any, persist_user_message: Any,
  584. persist_user_timestamp: Optional[float], persist_user_platform_id: Optional[str],
  585. persist_user_display_kind: Optional[str],
  586. persist_user_display_metadata: Optional[dict[str, Any]],
  587. ) -> tuple[dict[str, Any], Any]:
  588. """Build this turn's user dict, reusing CLI-staged input only when its clean text
  589. matches this turn (a stale handoff must not replace later input; voice turns
  590. compare the clean override). Returns ``(user_msg, pending_cli_message)``."""
  591. pending_cli_message = getattr(agent, "_pending_cli_user_message", None)
  592. expected_persist_content = (
  593. persist_user_message if persist_user_message is not None else user_message
  594. )
  595. if (
  596. isinstance(pending_cli_message, dict)
  597. and pending_cli_message.get("content") == expected_persist_content
  598. ):
  599. user_msg = pending_cli_message
  600. # CLI-staged value is the clean text; restore the API-facing variant (e.g. voice
  601. # prefix) on the same dict, keeping any close-path durable marker.
  602. user_msg["content"] = user_message
  603. else:
  604. user_msg = {"role": "user", "content": user_message}
  605. if isinstance(pending_cli_message, dict):
  606. agent._pending_cli_user_message = None
  607. # CLI input is stamped when staged; gateway input may carry the platform event
  608. # time. Preserve either value and cover any legacy unstamped handoff.
  609. stamp_message_timestamp(user_msg, timestamp=persist_user_timestamp)
  610. # Synthesized turns stamp their transcript type so the crash persist writes a typed
  611. # row; the model still receives role/content unchanged (api_messages strips both).
  612. if persist_user_display_kind:
  613. user_msg["display_kind"] = persist_user_display_kind
  614. if persist_user_display_metadata:
  615. user_msg["display_metadata"] = persist_user_display_metadata
  616. # The platform message id survives the turn-start flush; restart drain-window
  617. # recovery dedups via ``has_platform_message_id`` against this row.
  618. if persist_user_platform_id is not None:
  619. user_msg["platform_message_id"] = persist_user_platform_id
  620. return user_msg, pending_cli_message
  621. def _hydrate_from_history(agent: Any, conversation_history: Optional[list[Any]]) -> None:
  622. """Hydrate process-local state from persisted history on the first resumed turn."""
  623. if not conversation_history:
  624. return
  625. if not agent._todo_store.has_items():
  626. agent._hydrate_todo_store(conversation_history)
  627. # A live native checkpoint arms this latch while its response is captured. A
  628. # restarted agent must recover the same one-response deferral before turn-start
  629. # compression can rewrite the restored opaque checkpoint. Reuse the adapter's
  630. # exact route/issuer/replay filtering and tolerate plugin compressors without the
  631. # optional hook.
  632. if agent._user_turn_count == 0:
  633. # A fresh process has no in-memory anchor; the persisted one is honored only while the
  634. # restored transcript still carries the priced prefix (see agent/usage_anchor.py).
  635. restore_usage_anchor(agent, conversation_history)
  636. note_checkpoint = getattr(
  637. getattr(agent, "context_compressor", None),
  638. "note_native_compaction_checkpoint",
  639. None,
  640. )
  641. if callable(note_checkpoint):
  642. try:
  643. from agent.codex_responses_adapter import (
  644. has_replayable_native_compaction_checkpoint,
  645. )
  646. if has_replayable_native_compaction_checkpoint(
  647. agent, conversation_history
  648. ):
  649. note_checkpoint()
  650. # Restored usage can describe the input that produced this
  651. # checkpoint rather than its compacted replay.
  652. from agent.usage_anchor import set_usage_anchor
  653. set_usage_anchor(agent, None)
  654. except Exception:
  655. logger.debug(
  656. "restored native checkpoint hydration skipped", exc_info=True
  657. )
  658. # Hydrate per-session nudge counters from persisted history.
  659. prior_user_turns = sum(1 for m in conversation_history if m.get("role") == "user")
  660. if prior_user_turns > 0:
  661. agent._user_turn_count = prior_user_turns
  662. if agent._memory_nudge_interval > 0 and agent._turns_since_memory == 0:
  663. agent._turns_since_memory = prior_user_turns % agent._memory_nudge_interval
  664. def _tick_memory_nudge(agent: Any) -> bool:
  665. """Advance the turn-based memory nudge counter; ``True`` when the review should fire."""
  666. if (agent._memory_nudge_interval > 0
  667. and "memory" in agent.valid_tool_names
  668. and agent._memory_store):
  669. agent._turns_since_memory += 1
  670. if agent._turns_since_memory >= agent._memory_nudge_interval:
  671. agent._turns_since_memory = 0
  672. return True
  673. return False
  674. def _emit_reaction(agent: Any, original_user_message: Any, display_kind: Optional[str] = None) -> None:
  675. """Cosmetic side-signal: detect an affection reaction so the host can play hearts.
  676. Token-free, never touches the conversation, never fatal. Only words the user typed
  677. count: a hidden prompt or an expanded skill body is app/skill text, not affection."""
  678. reaction_callback = getattr(agent, "reaction_callback", None)
  679. if reaction_callback is None or display_kind == "hidden":
  680. return
  681. with suppress(Exception):
  682. from agent.reactions import detect_reaction
  683. from agent.skill_commands import describe_skill_invocation
  684. if describe_skill_invocation(original_user_message) is not None:
  685. return
  686. kind = detect_reaction(original_user_message)
  687. if kind:
  688. reaction_callback(kind)
  689. def _ensure_session_row(agent: Any, pending_cli_message: Any) -> None:
  690. """Create the DB row now (system prompt populated => non-NULL) and BEFORE preflight
  691. compression: compaction/rotation INSERTs reference this row under PRAGMA
  692. foreign_keys=ON. Idempotent; the user-turn crash persist runs later."""
  693. _persist_under_lock(
  694. agent, agent._ensure_db_session,
  695. "Turn-start session row creation failed for session=%s", pending_cli_message,
  696. )
  697. # ``turn_exit_reason`` of a turn a ``pre_llm_call`` hook vetoed before any inference request, and
  698. # the stored ``content`` of the vetoed user row (what the user typed is display-only metadata).
  699. PRE_LLM_BLOCK_EXIT_REASON = "blocked_by_plugin_pre_llm_call"
  700. def _withhold_blocked_prompt(agent: Any, turn_user_msg: dict[str, Any], typed: Any) -> None:
  701. """Store a vetoed prompt as the withheld placeholder. ``content`` is what compaction,
  702. session_search, memory providers and background review read, so the placeholder is the row's
  703. content (and the persist override, so no flush restores the typed text); what the user typed is
  704. kept only in ``display_metadata`` for transcript views. A row another writer materialized first
  705. (the TUI/Desktop submit-time row) is rewritten in place under the persist lock. A row merged with
  706. an earlier compaction handoff keeps the handoff and an unanswered earlier message merged into the
  707. row keeps its text; only this turn's ask becomes the placeholder."""
  708. from agent.context_compressor import COMPRESSED_SUMMARY_METADATA_KEY, _handoff_only_content
  709. from agent.message_metadata import WITHHELD_PROMPT
  710. from agent.session_persistence import _content_with_turn_override, _durable_content, _persist_lock
  711. content = turn_user_msg.get("content")
  712. if turn_user_msg.get(COMPRESSED_SUMMARY_METADATA_KEY):
  713. handoff = flatten_message_text(_handoff_only_content(content)).strip()
  714. withheld = f"{handoff}\n\n{PRE_LLM_BLOCK_WITHHELD_PROMPT}" if handoff else PRE_LLM_BLOCK_WITHHELD_PROMPT
  715. else:
  716. typed = _content_with_turn_override(turn_user_msg, content, typed)
  717. withheld = _content_with_turn_override(turn_user_msg, content, PRE_LLM_BLOCK_WITHHELD_PROMPT)
  718. metadata = turn_user_msg.get("display_metadata")
  719. metadata = {**(metadata if isinstance(metadata, dict) else {}), WITHHELD_PROMPT: str(_durable_content(typed) or "")}
  720. agent._persist_user_message_override = PRE_LLM_BLOCK_WITHHELD_PROMPT
  721. with _persist_lock(agent):
  722. turn_user_msg["content"] = withheld
  723. turn_user_msg.pop("api_content", None)
  724. turn_user_msg["display_metadata"] = metadata
  725. _db = getattr(agent, "_session_db", None)
  726. _row_id = turn_user_msg.get("_row_id")
  727. if _db is None or not isinstance(_row_id, int):
  728. return
  729. try:
  730. # A submit-time row is addressed under the session that wrote it (a rotation may follow).
  731. _db.set_user_message_content(turn_user_msg.get("_submit_row_session_id") or agent.session_id,
  732. _row_id, withheld, metadata)
  733. except Exception:
  734. logger.warning("withheld-prompt rewrite failed for session=%s", agent.session_id or "none", exc_info=True)
  735. def _collect_pre_llm_call_context(
  736. agent: Any, *, effective_task_id: str, turn_id: str, original_user_message: Any,
  737. messages: list[Any], conversation_history: Optional[list[Any]], blocks: Optional[list[str]] = None,
  738. ) -> str:
  739. """Run ``pre_llm_call`` plugins; their context is injected into the user message
  740. (never the system prompt). Oversized per-hook context is spilled to disk so a
  741. runaway plugin can't inflate every subsequent turn's prompt. Each
  742. ``{"action": "block", "message": ...}`` veto is appended to ``blocks`` (#57364); one
  743. without a message is ignored, as for ``pre_tool_call``."""
  744. if getattr(agent, "_persist_disabled", False):
  745. return ""
  746. try:
  747. from hermes_cli.lifecycle import invoke_hook as _invoke_hook
  748. _pre_results = _invoke_hook(
  749. "pre_llm_call",
  750. session_id=agent.session_id,
  751. task_id=effective_task_id,
  752. turn_id=turn_id,
  753. user_message=original_user_message,
  754. conversation_history=list(messages),
  755. is_first_turn=(not bool(conversation_history)),
  756. model=agent.model,
  757. platform=getattr(agent, "platform", None) or "",
  758. parent_session_id=getattr(agent, "_parent_session_id", None) or "",
  759. sender_id=getattr(agent, "_user_id", None) or "",
  760. )
  761. try:
  762. # Spill oversized per-hook context to disk so a runaway plugin can't inflate every subsequent
  763. # turn's prompt. Ported from openai/codex PR #21069 ("Spill large hook outputs from context").
  764. from tools.hook_output_spill import (
  765. get_spill_config as _spill_cfg, spill_if_oversized as _spill_if_oversized
  766. )
  767. _spill_config_cached = _spill_cfg()
  768. except Exception:
  769. _spill_if_oversized = None # type: ignore[assignment]
  770. _spill_config_cached = None
  771. _ctx_parts: list[str] = []
  772. for r in _pre_results:
  773. if isinstance(r, dict) and r.get("action") == "block":
  774. _msg = r.get("message")
  775. if blocks is not None and isinstance(_msg, str) and _msg.strip():
  776. blocks.append(_msg.strip())
  777. continue
  778. if isinstance(r, dict) and r.get("context"):
  779. _piece = str(r["context"])
  780. elif isinstance(r, str) and r.strip():
  781. _piece = r
  782. else:
  783. continue
  784. if _spill_if_oversized is not None:
  785. try:
  786. _piece = _spill_if_oversized(
  787. _piece, session_id=agent.session_id, source="plugin hook",
  788. config=_spill_config_cached,
  789. )
  790. except Exception as _spill_exc:
  791. logger.warning("hook context spill failed: %s", _spill_exc)
  792. _ctx_parts.append(_piece)
  793. return "\n\n".join(_ctx_parts)
  794. except Exception as exc:
  795. logger.warning("pre_llm_call hook failed: %s", exc)
  796. return ""
  797. def _merge_gateway_notes(
  798. agent: Any, messages: list[Any], current_turn_user_idx: int, plugin_user_context: str
  799. ) -> str:
  800. """Must-deliver per-turn notes ride the user-message injection channel (one-shot) so the
  801. ephemeral system prompt stays byte-stable: the gateway's staged notes, plugin go-live notices no
  802. tool result carried, then the surface-switch correction. Multimodal (list) content can't take the
  803. string sidecar — append a durable text part instead."""
  804. forward_lsp_verdicts(agent) # late LSP verdicts on last turn's edits ride the plugin-notice queue
  805. _turn_notes = "\n\n".join(
  806. part for part in (consume_gateway_turn_context_notes(agent), pop_plugin_notices(agent),
  807. consume_surface_switch_note(agent),
  808. consume_skills_index_note(agent)) if part
  809. )
  810. if not _turn_notes:
  811. return plugin_user_context
  812. _gw_turn_content = (
  813. messages[current_turn_user_idx].get("content")
  814. if 0 <= current_turn_user_idx < len(messages)
  815. and isinstance(messages[current_turn_user_idx], dict)
  816. else None
  817. )
  818. if isinstance(_gw_turn_content, list):
  819. append_notes_to_multimodal_content(_gw_turn_content, _turn_notes)
  820. return plugin_user_context
  821. return (
  822. plugin_user_context + "\n\n" + _turn_notes if plugin_user_context else _turn_notes
  823. )
  824. def _bind_interrupt_scope(agent: Any, ra) -> None:
  825. """Record the execution thread so interrupt()/clear_interrupt() scope the tool-level
  826. signal to THIS agent's thread; clear stale state, preserving a pending interrupt."""
  827. agent._execution_thread_id = threading.current_thread().ident
  828. ra()._set_interrupt(False, agent._execution_thread_id)
  829. if agent._interrupt_requested:
  830. ra()._set_interrupt(
  831. True, agent._execution_thread_id, reason=getattr(agent, "_tool_interrupt_reason", None)
  832. )
  833. else:
  834. agent._interrupt_message = None
  835. agent._tool_interrupt_reason = None
  836. agent._interrupt_thread_signal_pending = False
  837. def _memory_query_text(original_user_message: Any) -> str:
  838. """Semantic text of the turn for memory queries: a multimodal (list) turn carries its text
  839. in parts, so keying off ``isinstance(str)`` collapsed it to ``""`` and ``is_trivial_prompt``
  840. skipped prefetch entirely. An image-only turn still flattens to ``""`` (trivial)."""
  841. if isinstance(original_user_message, (str, list)):
  842. return flatten_message_text(original_user_message)
  843. return ""
  844. def _memory_turn_start_and_prefetch(
  845. agent: Any, original_user_message: Any, turn_author: Optional[dict[str, Any]] = None,
  846. ) -> str:
  847. """Notify memory providers of the new turn, then prefetch external memory once
  848. before the tool loop (skipped on trivial prompts with no semantic signal).
  849. Returns the prefetch text (``""`` when nothing was injected)."""
  850. if not agent._memory_manager:
  851. return ""
  852. _query = _memory_query_text(original_user_message)
  853. # The author rides along so a provider can attribute THIS turn, not whoever opened the session.
  854. _author = turn_author if isinstance(turn_author, dict) else {}
  855. with suppress(Exception):
  856. agent._memory_manager.on_turn_start(
  857. agent._user_turn_count, _query,
  858. author_id=_author.get("id") or None, author_name=_author.get("name") or None,
  859. author_is_bot=bool(_author.get("is_bot")),
  860. )
  861. ext_prefetch_cache = ""
  862. with suppress(Exception):
  863. if not is_trivial_prompt(_query):
  864. ext_prefetch_cache = agent._memory_manager.prefetch_all(_query, session_id=agent.session_id) or ""
  865. # Deterministic recall indicator via _emit_status so the model can't silently
  866. # drop injected memory.
  867. if ext_prefetch_cache:
  868. with suppress(Exception):
  869. _recall_indicator = agent._memory_manager.describe_recall()
  870. if _recall_indicator:
  871. agent._emit_status(_recall_indicator)
  872. return ext_prefetch_cache
  873. def _stamp_api_content_sidecar(
  874. agent: Any, messages: list[Any], current_turn_user_idx: int, ext_prefetch_cache: str,
  875. plugin_user_context: str, *, preflight_compressed: bool,
  876. ) -> None:
  877. """api_content sidecar — persist what you send: injected context lives only in the
  878. API copy, so stamp the exact sent bytes on the live dict for replay."""
  879. _turn_user_msg = messages[current_turn_user_idx]
  880. live_content = _turn_user_msg.get("content")
  881. from agent.session_persistence import _persist_lock, durable_user_row_content
  882. # Match the row the flush wrote (persist override = clean transcript), not the live bytes.
  883. durable_content, _api_content = durable_user_row_content(
  884. agent, _turn_user_msg, live_content,
  885. compose_user_api_content(live_content or "", ext_prefetch_cache, plugin_user_context),
  886. )
  887. if _api_content is None or _api_content == durable_content:
  888. return
  889. _turn_user_msg["api_content"] = _api_content
  890. # When another writer materialized this turn's user row BEFORE the sidecar existed — in-place
  891. # preflight compaction, or a close/early flush that raced the prologue (#102194) — the crash
  892. # persist marker-skips the message and the stamp never reaches the DB, so the next turn replays
  893. # clean content and the request prefix diverges here. Both writers stamp ``_row_id`` on the live
  894. # dict, which is at once the proof a row exists and the address to update.
  895. #
  896. # Never widen this to an unconditional positional backfill — see set_latest_user_api_content.
  897. #
  898. # ``_row_id`` is read under ``_session_persist_lock``: a close flush holds it while it commits
  899. # the row and only then writes ``_row_id`` back (``sync_flushed_message_markers``). Read outside
  900. # it, the stamp can land in between, see no id, return — and the flush then marks the message
  901. # persisted with ``api_content = NULL``, leaving no writer to correct the row.
  902. with _persist_lock(agent):
  903. _row_id = _turn_user_msg.get("_row_id")
  904. _in_place_compacted = preflight_compressed and bool(getattr(agent, "_last_compaction_in_place", False))
  905. _db = getattr(agent, "_session_db", None)
  906. if _db is None or not (isinstance(_row_id, int) or _in_place_compacted):
  907. return
  908. try:
  909. if isinstance(_row_id, int):
  910. _db.set_message_api_content(agent.session_id, _row_id, durable_content, _api_content)
  911. else:
  912. # Compacted copies carry no row id; positional is safe only because
  913. # archive_and_compact just made this message the newest active user row.
  914. _db.set_latest_user_api_content(agent.session_id, durable_content, _api_content)
  915. except Exception:
  916. logger.warning("api_content backfill failed for session=%s", agent.session_id or "none", exc_info=True)
  917. def _append_multimodal_context(
  918. agent: Any, turn_user_msg: dict[str, Any], ext_prefetch_cache: str, plugin_user_context: str,
  919. *, preflight_compressed: bool,
  920. ) -> None:
  921. """Multimodal (list) content takes no string sidecar: the turn's context becomes a durable
  922. text part on the current turn's live list (the gateway must-deliver-note channel, #71998),
  923. so wire, persisted row, compaction and replay all carry the same parts. Runs once per turn,
  924. before the first request; historical rows are never touched.
  925. A user row another writer materialized BEFORE the prologue (in-place preflight compaction,
  926. a close/early flush that raced it) is updated in place: the crash persist marker-skips that
  927. message, so without this a resumed session replays a view the model never saw. Same
  928. ``_row_id``-under-lock protocol as the string sidecar backfill; the row keeps its writer's
  929. shape (compaction inserted the raw parts, a flush the text projection)."""
  930. _mm_ctx = compose_multimodal_context_part(ext_prefetch_cache, plugin_user_context)
  931. if not append_notes_to_multimodal_content(turn_user_msg.get("content"), _mm_ctx):
  932. return
  933. from agent.session_persistence import _durable_content, _persist_lock
  934. with _persist_lock(agent):
  935. _row_id = turn_user_msg.get("_row_id")
  936. _db = getattr(agent, "_session_db", None)
  937. if _db is None or not isinstance(_row_id, int):
  938. return
  939. _in_place_compacted = preflight_compressed and bool(getattr(agent, "_last_compaction_in_place", False))
  940. content = turn_user_msg["content"] if _in_place_compacted else _durable_content(turn_user_msg["content"])
  941. try:
  942. _db.set_user_message_content(agent.session_id, _row_id, content)
  943. except Exception:
  944. logger.warning("multimodal context backfill failed for session=%s", agent.session_id or "none", exc_info=True)
  945. def _persist_turn_start(
  946. agent: Any, messages: list[Any], conversation_history: Optional[list[Any]],
  947. pending_cli_message: Any,
  948. ) -> None:
  949. """Crash-resilience: persist the inbound user turn once, with final api_content,
  950. before the first LLM call. Same critical section as CLI close persistence; retries
  951. the row create if the pre-compression attempt failed transiently."""
  952. def _ensure_and_persist() -> None:
  953. agent._ensure_db_session()
  954. agent._persist_session(messages, conversation_history)
  955. _persist_under_lock(
  956. agent, _ensure_and_persist,
  957. "Early turn-start session persistence failed for session=%s", pending_cli_message,
  958. )
  959. def build_turn_context(
  960. agent, user_message: Any, system_message: Optional[str],
  961. conversation_history: Optional[list[dict[str, Any]]], task_id: Optional[str], stream_callback,
  962. persist_user_message: Optional[Any], persist_user_timestamp: Optional[float]=None,
  963. persist_user_platform_id: Optional[str]=None, *, persist_user_display_kind: Optional[str]=None,
  964. persist_user_display_metadata: Optional[dict[str, Any]]=None, turn_author: Optional[dict[str, Any]]=None,
  965. restore_or_build_system_prompt,
  966. install_safe_stdio, sanitize_surrogates, summarize_user_message_for_log, set_session_context,
  967. set_current_write_origin, ra, moa_active: bool=False,
  968. title_user_message: Optional[str]=None,
  969. ) -> TurnContext:
  970. """Run the once-per-turn setup and return the loop's input context.
  971. Helpers are passed in to avoid an import cycle with ``agent.conversation_loop``.
  972. Order matters: the DB session row is created only AFTER the system prompt is built
  973. (else it persists system_prompt=NULL and costs a cache miss) and BEFORE preflight
  974. compression."""
  975. from agent.turn_context_compaction import CompactionOutcome, run_turn_start_compaction
  976. # Guard stdio against OSError from broken pipes (systemd/headless/daemon).
  977. install_safe_stdio()
  978. # Reset first: a cached gateway agent must never carry the previous turn's bot author into a human turn.
  979. turn_author = parse_turn_author(turn_author)
  980. agent._turn_author = turn_author
  981. # Recover a rotated session before binding log/turn ids or copying client history so
  982. # everything in this turn belongs to the canonical child.
  983. recovered_history = recover_rotated_compression_session(agent)
  984. if recovered_history is not None:
  985. conversation_history = recovered_history
  986. # After recovery, so the bot-to-bot chain is keyed by the session id this turn's sends use.
  987. from agent.bot_chain import on_turn_start as _bot_chain_turn_start
  988. _bot_chain_turn_start(agent, turn_author, persist_user_display_kind, persist_user_message or user_message)
  989. # Tag log records on this thread with the session ID for ``hermes logs``; bind the
  990. # skill write-origin ContextVar; restore the primary runtime after a fallback turn.
  991. # NOTE: the DB session row is created later, AFTER the system prompt is restored/built (see
  992. # _ensure_db_session() below the system-prompt block). Creating it here — before _cached_system_prompt
  993. # is populated — inserts a row with system_prompt=NULL on a fresh API/gateway agent that carries
  994. # client-managed history, which then trips the "stored system prompt is null; rebuilding from scratch"
  995. # warning and a needless first-turn prefix cache miss. (Issue #45499.)
  996. set_session_context(agent.session_id)
  997. set_current_write_origin(getattr(agent, "_memory_write_origin", "assistant_tool"))
  998. from tools.skill_provenance import set_review_attended
  999. set_review_attended(getattr(agent, "_review_attended", False))
  1000. agent._restore_primary_runtime()
  1001. _publish_runtime_main(agent)
  1002. _refresh_mcp_tools_between_turns(agent)
  1003. if isinstance(user_message, str):
  1004. user_message = sanitize_surrogates(user_message)
  1005. if isinstance(persist_user_message, str):
  1006. persist_user_message = sanitize_surrogates(persist_user_message)
  1007. effective_task_id, turn_id = _bind_turn_identity(
  1008. agent, task_id, stream_callback, persist_user_message,
  1009. persist_user_timestamp, persist_user_platform_id,
  1010. )
  1011. _reset_per_turn_agent_state(agent)
  1012. _preview_text = summarize_user_message_for_log(user_message)
  1013. _msg_preview = _preview_text[:80] + ("..." if len(_preview_text) > 80 else "")
  1014. _turn_fmt = (
  1015. "conversation turn: session=%s model=%s provider=%s platform=%s history=%d msg=%r"
  1016. )
  1017. _turn_args = [
  1018. agent.session_id or "none", agent.model, agent.provider or "unknown",
  1019. agent.platform or "unknown", len(conversation_history or []),
  1020. _msg_preview.replace("\n", " "),
  1021. ]
  1022. # Fork turns (background review, side questions) reuse the parent's session_id and
  1023. # model; tag their turn-start line so logs can tell them apart (#118693).
  1024. if (_turn_origin := getattr(agent, "_turn_origin", None)):
  1025. _turn_fmt += " origin=%s"
  1026. _turn_args.append(_turn_origin)
  1027. logger.info(_turn_fmt, *_turn_args)
  1028. # Copy so the caller's list is never mutated.
  1029. messages = list(conversation_history) if conversation_history else []
  1030. user_msg, pending_cli_message = _stage_turn_user_message(
  1031. agent, user_message, persist_user_message, persist_user_timestamp,
  1032. persist_user_platform_id, persist_user_display_kind, persist_user_display_metadata,
  1033. )
  1034. _hydrate_from_history(agent, conversation_history)
  1035. # Every estimator this turn prices images at the cost learned from this model's real usage.
  1036. bind_image_token_cost(agent)
  1037. # Append the user message now that close persistence is safe.
  1038. append_message(messages, user_msg)
  1039. current_turn_user_idx = len(messages) - 1
  1040. agent._persist_user_message_idx = current_turn_user_idx
  1041. agent._user_turn_count += 1
  1042. # Turn-initiator state for per-request provider headers: the first API call of this
  1043. # user turn is user-initiated; tool-loop follow-ups are agent-initiated.
  1044. agent._is_user_initiated_turn = True
  1045. # Preserve the original user message (no nudge injection).
  1046. original_user_message = persist_user_message if persist_user_message is not None else user_message
  1047. should_review_memory = _tick_memory_nudge(agent)
  1048. _emit_reaction(agent, original_user_message, persist_user_display_kind)
  1049. if not agent.quiet_mode:
  1050. agent._safe_print(
  1051. f"💬 Starting conversation: '{_preview_text[:60]}"
  1052. f"{'...' if len(_preview_text) > 60 else ''}'"
  1053. )
  1054. # System prompt is cached per session for prefix caching. A warm agent (kept across turns)
  1055. # first adopts any `hermes sessions refresh-prompts` request recorded since it set its prompt.
  1056. refresh_warm_prompt(agent, system_message, conversation_history)
  1057. if agent._cached_system_prompt is None:
  1058. restore_or_build_system_prompt(agent, system_message, conversation_history)
  1059. active_system_prompt = agent._cached_system_prompt
  1060. # `/delegation <backend> --now`: after the pin restore, so a fresh agent rebuilds too.
  1061. from agent.delegation_backends import apply_requested_tool_rebuild
  1062. apply_requested_tool_rebuild(agent)
  1063. # Bot Mode DM tool — injected ONLY into a bot's canonical "Bot Chat" session (same
  1064. # gate as the protocol section); gate is session-stable, so cache-safe.
  1065. try:
  1066. from tools.bot_mode_dm import ensure_message_agent_tool
  1067. ensure_message_agent_tool(agent)
  1068. except Exception:
  1069. logger.debug("message_agent injection skipped", exc_info=True)
  1070. _ensure_session_row(agent, pending_cli_message)
  1071. # A turn interrupted before admission could not write its accepted input because
  1072. # it did not own the session lease. Persist that carried-forward row now, before
  1073. # compaction can rewrite or drop it.
  1074. from agent.session_persistence import _PERSIST_AFTER_ADMISSION_INTERRUPT
  1075. if conversation_history and any(
  1076. isinstance(msg, dict) and msg.get(_PERSIST_AFTER_ADMISSION_INTERRUPT)
  1077. for msg in conversation_history
  1078. ):
  1079. agent._flush_messages_to_session_db(conversation_history, conversation_history)
  1080. # Before turn-start compaction: its summary request quotes recent user turns, this one included,
  1081. # so a vetoed prompt skips it (the turn makes no model call at all).
  1082. _blocks: list[str] = []
  1083. plugin_user_context = _collect_pre_llm_call_context(
  1084. agent, effective_task_id=effective_task_id, turn_id=turn_id,
  1085. original_user_message=original_user_message, messages=messages,
  1086. conversation_history=conversation_history, blocks=_blocks,
  1087. )
  1088. plugin_block_message = _blocks[0] if _blocks else "" # first veto wins
  1089. compaction = CompactionOutcome(
  1090. messages=messages, active_system_prompt=active_system_prompt,
  1091. conversation_history=conversation_history, current_turn_user_idx=current_turn_user_idx,
  1092. ) if plugin_block_message else run_turn_start_compaction(
  1093. agent, messages=messages, system_message=system_message,
  1094. active_system_prompt=active_system_prompt, conversation_history=conversation_history,
  1095. current_turn_user_idx=current_turn_user_idx, user_message=user_message,
  1096. effective_task_id=effective_task_id,
  1097. )
  1098. messages = compaction.messages
  1099. active_system_prompt = compaction.active_system_prompt
  1100. conversation_history = compaction.conversation_history
  1101. current_turn_user_idx = compaction.current_turn_user_idx
  1102. # Every turn, not only on a prompt restore: a long-lived agent (CLI, TUI, Desktop) keeps its
  1103. # prompt in memory for the whole conversation and would never re-check its skills index.
  1104. stage_skills_index_note(agent, active_system_prompt, messages)
  1105. plugin_user_context = _merge_gateway_notes(
  1106. agent, messages, current_turn_user_idx, plugin_user_context
  1107. )
  1108. _bind_interrupt_scope(agent, ra)
  1109. # A vetoed prompt never leaves the host: no external-memory prefetch, no titling call.
  1110. ext_prefetch_cache = "" if plugin_block_message else _memory_turn_start_and_prefetch(
  1111. agent, original_user_message, turn_author)
  1112. # Title the session now: titling depends only on the user's ask (before any injected
  1113. # context lands on list content), so it runs concurrently with the turn. Daemon thread,
  1114. # no-op once titled; it ensures the session row itself.
  1115. if not plugin_block_message:
  1116. _maybe_title_session_at_turn_start(agent, messages, title_user_message)
  1117. # Sidecar skipped for codex_app_server/MoA; list content carries its context as a part in every mode.
  1118. if 0 <= current_turn_user_idx < len(messages) and messages[current_turn_user_idx].get("role") == "user":
  1119. if plugin_block_message:
  1120. _withhold_blocked_prompt(agent, messages[current_turn_user_idx], original_user_message)
  1121. elif isinstance(messages[current_turn_user_idx].get("content"), list):
  1122. _append_multimodal_context(
  1123. agent, messages[current_turn_user_idx], ext_prefetch_cache, plugin_user_context,
  1124. preflight_compressed=compaction.compressed,
  1125. )
  1126. elif not moa_active and getattr(agent, "api_mode", None) != "codex_app_server":
  1127. _stamp_api_content_sidecar(
  1128. agent, messages, current_turn_user_idx, ext_prefetch_cache,
  1129. plugin_user_context, preflight_compressed=compaction.compressed,
  1130. )
  1131. _persist_turn_start(agent, messages, conversation_history, pending_cli_message)
  1132. return TurnContext(
  1133. user_message=user_message, original_user_message=original_user_message, messages=messages,
  1134. conversation_history=conversation_history, active_system_prompt=active_system_prompt,
  1135. effective_task_id=effective_task_id, turn_id=turn_id,
  1136. current_turn_user_idx=current_turn_user_idx, should_review_memory=should_review_memory,
  1137. plugin_user_context=plugin_user_context, plugin_block_message=plugin_block_message,
  1138. ext_prefetch_cache=ext_prefetch_cache, preflight_compression_blocked=compaction.blocked,
  1139. )
  1140. def _sanitize_model_for(agent: Any, moa_config: Any) -> Any:
  1141. """Model name for strict-API tool-call sanitization. In MoA mode ``agent.model`` is
  1142. the virtual preset name; use the resolved aggregator so Gemini keeps
  1143. thought_signature (extra_content)."""
  1144. _sanitize_model = agent.model
  1145. if agent.provider == "moa":
  1146. if moa_config:
  1147. _agg = moa_config.get("aggregator") or {}
  1148. if _agg.get("model"):
  1149. _sanitize_model = _agg["model"]
  1150. if _sanitize_model == agent.model:
  1151. # Virtual-provider mode: no moa_config is threaded through; ask the facade
  1152. # for the aggregator slot from the previous create().
  1153. _agg_slot = getattr(getattr(agent, "client", None), "last_aggregator_slot", None)
  1154. if _agg_slot and _agg_slot.get("model"):
  1155. _sanitize_model = _agg_slot["model"]
  1156. return _sanitize_model
  1157. def build_api_messages(
  1158. agent: Any, messages: list[dict[str, Any]], *, current_turn_user_idx: Any,
  1159. ext_prefetch_cache: Any, plugin_user_context: Any, moa_config: Any, active_system_prompt: Any,
  1160. ) -> tuple[list[dict[str, Any]], str]:
  1161. """Build the wire copy of ``messages`` for one API call plus the effective system
  1162. message. Returns ``(api_messages, effective_system)``.
  1163. Prompt-cache invariant: historical user/assistant rows replay their ``api_content``
  1164. sidecar (the exact bytes sent live) so the prefix stays byte-stable; the current
  1165. user turn reuses the prologue's stamp (or composes live when a caller bypassed the
  1166. prologue). Ephemeral context (prefetch, ``pre_llm_call`` hooks,
  1167. ``ephemeral_system_prompt``) is added at API time only — ``messages`` stays untouched
  1168. beyond the sidecar stamp, and the system prompt is built ONCE per session and
  1169. replayed verbatim."""
  1170. from agent.agent_runtime_helpers import fill_empty_non_final_wire_payload
  1171. from agent.conversation_loop import _clone_message_for_send
  1172. from agent.replay_cleanup import canonicalize_replay_history
  1173. has_current = isinstance(current_turn_user_idx, int) and 0 <= current_turn_user_idx < len(messages)
  1174. current_turn_message = messages[current_turn_user_idx] if has_current else None
  1175. # Replay consumers canonicalize the persisted prefix on read; the request copy must
  1176. # carry the same bytes or a resume diverges mid-prefix. Only the rows BEFORE this
  1177. # turn's user message are the replayed prefix — rows this turn appended (its tool
  1178. # calls/results) are live and must never be rewritten between iterations. The
  1179. # expiry clock is the turn's admission time, frozen in _reset_per_turn_agent_state.
  1180. # Without an anchor (compaction found no surviving user row) there is no provable
  1181. # persisted prefix, so nothing is canonicalized. The clock is stamped once per turn in
  1182. # _reset_per_turn_agent_state; a caller that skipped the prologue fails loudly here
  1183. # rather than silently un-freezing it.
  1184. turn_now = agent._current_turn_timestamp
  1185. split = current_turn_user_idx if has_current else 0
  1186. canonical_messages = canonicalize_replay_history(messages[:split], now=turn_now) + messages[split:]
  1187. api_messages = []
  1188. for idx, msg in enumerate(canonical_messages):
  1189. # Structural clone, NOT msg.copy(): in-place transforms below must not reach
  1190. # persisted history via nested containers; see _clone_message_for_send.
  1191. api_msg = _clone_message_for_send(msg)
  1192. # api_content is bookkeeping (exact bytes sent), never a provider field — pop
  1193. # it from EVERY outgoing copy. Persistence/display fields (display_*, _row_id,
  1194. # timestamp) are local bookkeeping: strict OpenAI backends reject unknown keys
  1195. # and only chat-completions strips underscore keys. The token estimator drops
  1196. # the same set, so it never prices bytes the provider never receives.
  1197. _api_content = api_msg.pop("api_content", None)
  1198. for key in PERSISTENCE_ONLY_MESSAGE_FIELDS:
  1199. api_msg.pop(key, None)
  1200. # Inject ephemeral context (memory prefetch + pre_llm_call user hooks)
  1201. # at API time only; `messages` is untouched beyond the api_content stamp.
  1202. if msg is current_turn_message and msg.get("role") == "user":
  1203. if isinstance(_api_content, str) and _api_content:
  1204. # Reuse the prologue's stamp so sidecar and wire cannot drift
  1205. # and every pass this turn sends identical bytes.
  1206. api_msg["content"] = _api_content
  1207. else:
  1208. # Callers that bypass the prologue stamping: compose live.
  1209. _composed = compose_user_api_content(
  1210. api_msg.get("content", ""), ext_prefetch_cache, plugin_user_context
  1211. )
  1212. if _composed is not None:
  1213. api_msg["content"] = _composed
  1214. elif (
  1215. isinstance(_api_content, str) and _api_content
  1216. and msg.get("role") in ("user", "assistant")
  1217. ):
  1218. # Historical row: replay the exact bytes sent live so the prompt-cache
  1219. # prefix stays byte-stable. User rows carry the injection sidecar; user
  1220. # and assistant rows may carry a sanitize-divergence sidecar.
  1221. api_msg["content"] = _api_content
  1222. # Replay stored reasoning on every carrier the active route reads (and strip the
  1223. # rest): message_sanitization.reasoning_replay_route owns the decision.
  1224. agent._copy_reasoning_content_for_api(msg, api_msg)
  1225. # finish_reason is rejected by strict APIs (e.g. Mistral).
  1226. api_msg.pop("finish_reason", None)
  1227. # Fill empty non-final user/assistant wire copies so the pre-call sanitizer
  1228. # stops re-healing and flooding errors.log; durable history is untouched.
  1229. # After the reasoning copy so thinking-only turns keep payload.
  1230. fill_empty_non_final_wire_payload(api_msg, is_final=(idx == len(canonical_messages) - 1))
  1231. # _thinking_prefill survives intentionally: the drop pass below needs it.
  1232. # Strip length-continuation marks; some transports keep underscore keys.
  1233. api_msg.pop("_length_continuation_fragment", None)
  1234. api_msg.pop("_length_continuation_nudge", None)
  1235. # Strip Codex Responses fields (call_id, response_item_id): strict providers
  1236. # reject unknown fields. New dicts keep the internal list intact for Codex.
  1237. if agent._should_sanitize_tool_calls():
  1238. agent._sanitize_tool_calls_for_strict_api(
  1239. api_msg, model=_sanitize_model_for(agent, moa_config),
  1240. base_url=agent.base_url, provider=agent.provider,
  1241. )
  1242. # 'reasoning_details' is shaped by the replay policy above on chat_completions and
  1243. # left intact for the native adapters (anthropic/bedrock rebuild signed blocks from it).
  1244. api_messages.append(api_msg)
  1245. # Rows rebuilt from the session DB carry ``[screenshot]`` lines: re-attach the newest retained
  1246. # images on this wire copy (vision.replay_recent_images; native image input only).
  1247. from agent.image_replay import replay_for_agent
  1248. replay_for_agent(agent, api_messages)
  1249. # A provider-rejected Anthropic signature is suppressed outside canonical history and
  1250. # survives fresh request construction / process resume via session model_config.
  1251. from agent.anthropic_thinking_replay import apply_rejected_thinking_suppression
  1252. apply_rejected_thinking_suppression(agent, api_messages)
  1253. # Final system message = cached prompt + ephemeral additions (API-time only).
  1254. # Plugin/recall context goes into the user message, never the system prompt: the
  1255. # prompt is built ONCE per session and replayed verbatim (stable cache prefix).
  1256. effective_system = active_system_prompt or ""
  1257. if agent.ephemeral_system_prompt:
  1258. effective_system = (effective_system + "\n\n" + agent.ephemeral_system_prompt).strip()
  1259. if effective_system:
  1260. api_messages = [{"role": "system", "content": effective_system}] + api_messages
  1261. return api_messages, effective_system