run_agent.py 87 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571
  1. #!/usr/bin/env python3
  2. """AIAgent: the tool-calling agent runner (conversation loop, tool execution, session lifecycle).
  3. from run_agent import AIAgent
  4. agent = AIAgent(base_url="http://localhost:30000/v1", model="claude-opus-4-20250514")
  5. response = agent.run_conversation("Tell me about the latest Python updates")
  6. """
  7. # hermes_bootstrap must be the very first import (UTF-8 stdio on Windows; no-op on POSIX).
  8. try:
  9. import hermes_bootstrap
  10. except ModuleNotFoundError as exc: # partial `hermes update` left the bootstrap unregistered
  11. if exc.name != "hermes_bootstrap":
  12. raise # the bootstrap exists but cannot load: skipping it would skip PM activation
  13. import sys
  14. # `hermes-agent` runs this module without hermes_cli.main, which repairs a `hermes update` killed
  15. # while git wrote the new tree; do it here, before importing anything else from the checkout.
  16. if "hermes_cli.main" not in sys.modules:
  17. from hermes_cli import _early_recovery
  18. if _early_recovery.restore_interrupted_pull():
  19. _early_recovery.relaunch_after_restore()
  20. import json
  21. import logging
  22. logger = logging.getLogger(__name__)
  23. import os
  24. import re
  25. import time
  26. import threading
  27. import uuid
  28. import warnings
  29. from typing import List, Dict, Any, Optional, Callable
  30. from datetime import datetime
  31. from pathlib import Path
  32. from agent.session_source import CLI_FAMILY_SOURCES, session_source_for
  33. from hermes_constants import get_hermes_home
  34. def _launch_cwd_for_session(source: str) -> Optional[str]:
  35. """cwd to stamp on a new session row (``hermes -c`` / ``--resume``), or None.
  36. Only local CLI sessions record one: gateway/cron/remote backends (non-"local" ``TERMINAL_ENV``) have no
  37. stable host cwd for the agent's tools.
  38. """
  39. if source not in CLI_FAMILY_SOURCES or (os.environ.get("TERMINAL_ENV") or "local").strip().lower() not in ("", "local"):
  40. return None
  41. try:
  42. return os.getcwd()
  43. except OSError: # cwd was unlinked out from under us
  44. return None
  45. def _gateway_origin_json(agent: "AIAgent") -> Optional[str]:
  46. """Gateway routing ``origin_json`` for a session row; None when the agent carries no gateway identity.
  47. Mirrors ``SessionSource.to_dict()`` so state.db consumers see the same fields ``record_gateway_session_peer`` writes.
  48. """
  49. chat_id = getattr(agent, "_chat_id", None)
  50. session_key = getattr(agent, "_gateway_session_key", None)
  51. user_id = getattr(agent, "_user_id", None)
  52. if not (chat_id or session_key or user_id):
  53. return None
  54. origin: dict[str, Any] = {
  55. "platform": getattr(agent, "platform", None) or "", "chat_id": chat_id,
  56. "chat_name": getattr(agent, "_chat_name", None), "chat_type": getattr(agent, "_chat_type", None) or "dm",
  57. "user_id": user_id, "user_name": getattr(agent, "_user_name", None), "thread_id": getattr(agent, "_thread_id", None),
  58. }
  59. if getattr(agent, "_user_id_alt", None):
  60. origin["user_id_alt"] = agent._user_id_alt
  61. profile = getattr(agent, "_profile_name", None)
  62. if not profile:
  63. try:
  64. from hermes_cli.profiles import get_active_profile_name
  65. profile = get_active_profile_name()
  66. except Exception:
  67. profile = None
  68. if profile == "default":
  69. profile = None
  70. if profile:
  71. origin["profile"] = profile
  72. try:
  73. return json.dumps(origin)
  74. except Exception:
  75. return None
  76. from agent.iteration_budget import IterationBudget
  77. from hermes_cli.env_loader import load_hermes_dotenv
  78. from hermes_cli.timeouts import get_provider_request_timeout, get_provider_stale_timeout
  79. _hermes_home = get_hermes_home() # read by agent_init via _ra()._hermes_home
  80. _loaded_env_paths = load_hermes_dotenv(hermes_home=_hermes_home, project_env=Path(__file__).parent / '.env')
  81. for _env_path in _loaded_env_paths:
  82. logger.info("Loaded environment variables from %s", _env_path)
  83. if not _loaded_env_paths:
  84. logger.info("No .env file found. Using system environment variables.")
  85. from model_tools import get_toolset_for_tool
  86. from tools.terminal_tool_lifecycle import cleanup_vm, get_active_env
  87. from tools.interrupt import set_interrupt as _set_interrupt
  88. from tools.browser_session_lifecycle import cleanup_browser
  89. from tools.connectors.turn import agent_connection_surface, scoped_connection_surface
  90. from agent.memory_provider import is_trivial_prompt
  91. from agent.client_lifecycle import ClientLifecycleMixin
  92. from agent.stream_delivery import StreamDeliveryMixin
  93. from agent.status_output import StatusOutputMixin
  94. from agent.api_request_hooks import ApiRequestHooksMixin
  95. from agent.api_error_summary import ApiErrorSummaryMixin, is_provider_stream_parse_error
  96. from agent.interrupt_control import InterruptControlMixin
  97. from agent.turn_explainers import TurnExplainersMixin
  98. from agent.activity_tracking import ActivityTrackingMixin
  99. from agent.rate_limit_credits import RateLimitCreditsMixin
  100. from agent.session_persistence import SessionPersistenceMixin
  101. from agent.compression_facade import CompressionFacadeMixin
  102. from agent.turn_facade import TurnFacadeMixin
  103. from agent.vision_message_prep import VisionMessagePrepMixin
  104. from agent.reasoning_params import ReasoningParamsMixin
  105. from agent.lazy_forward import forward as _forward, forward_static as _forward_static
  106. from agent.session_activity import ActivityProvenance
  107. from agent.model_metadata import is_local_endpoint
  108. from agent.message_sanitization import (
  109. coalesce_tool_call_id as _sanitize_coalesce_tool_call_id,
  110. deterministic_call_id as _codex_deterministic_call_id,
  111. uniquify_tool_call_ids as _sanitize_uniquify_tool_call_ids,
  112. )
  113. from agent.codex_responses_adapter import (
  114. _derive_responses_function_call_id as _codex_derive_responses_function_call_id,
  115. _split_responses_tool_id as _codex_split_responses_tool_id,
  116. _summarize_user_message_for_log,
  117. )
  118. from agent.tool_guardrails import ToolGuardrailDecision, append_toolguard_guidance, toolguard_synthetic_result
  119. from hermes_cli.observability.shared_metrics_harness import record_guardrail_decision, record_guardrail_warnings
  120. from utils import base_url_host_matches, base_url_hostname, env_float, model_forces_max_completion_tokens
  121. _MAX_TOOL_WORKERS = 8
  122. # Spawn the OpenRouter pre-warm thread once per process, not per AIAgent (gateway thread leak).
  123. _openrouter_prewarm_done = threading.Event()
  124. def _quietly(fn: Callable, *args, **kwargs) -> None:
  125. """Run one teardown step, swallowing any exception so sibling steps still run."""
  126. try:
  127. fn(*args, **kwargs)
  128. except Exception:
  129. pass
  130. def _call_engine_hook(engine: Any, hook: str, *args, **kwargs) -> None:
  131. """Invoke an optional context-engine lifecycle hook; failures are logged, never raised."""
  132. if not hasattr(engine, hook):
  133. return
  134. try:
  135. getattr(engine, hook)(*args, **kwargs)
  136. except Exception as exc:
  137. logger.debug("context engine %s during transition: %s", hook, exc)
  138. def _positive_int(value: Any) -> Optional[int]:
  139. """``value`` when it is a real positive int (bools excluded), else None."""
  140. return value if isinstance(value, int) and not isinstance(value, bool) and value > 0 else None
  141. def _review_should_defer(agent: Any, task_cfg: Optional[dict[str, Any]]) -> bool:
  142. """True when an automatic background review targets the managed local runtime under ``defer: auto``."""
  143. from agent.review_idle_queue import defer_mode, review_targets_managed_local
  144. return defer_mode(task_cfg) == "auto" and review_targets_managed_local(agent, task_cfg)
  145. def _review_queue_key(agent: Any) -> str:
  146. return str(getattr(agent, "session_id", None) or id(agent))
  147. def _notify_context_engine_session_end(agent: Any, messages: Optional[list]) -> None:
  148. """Tell the context engine the session ended (flush DAG, close DBs) at the same lifecycle moment as the
  149. memory manager, so per-session engine state never leaks into the next session."""
  150. engine = getattr(agent, "context_compressor", None)
  151. if engine:
  152. _quietly(lambda: engine.on_session_end(agent.session_id or "", messages or []))
  153. def _pool_may_recover_from_rate_limit(pool) -> bool:
  154. """Wait for credential-pool rotation (True) or fall back to ``fallback_model`` (False) after a 429.
  155. Rotation only helps when the pool has somewhere to go; a single-credential pool would retry the same quota.
  156. See issues #11314 and #13636.
  157. """
  158. return pool is not None and pool.has_available() and len(pool.entries()) > 1
  159. class _StreamErrorEvent(Exception):
  160. """Provider error synthesized from a standalone Responses ``type=error`` SSE frame (Codex-style backends).
  161. Gives ``_summarize_api_error`` / the entitlement detector the familiar ``.body`` / ``.status_code`` shape.
  162. """
  163. def __init__(self, message: str, *, code: Optional[str] = None, param: Optional[str] = None,
  164. status_code: Optional[int] = None) -> None:
  165. super().__init__(message)
  166. self.message, self.code, self.param, self.status_code = message, code, param, status_code
  167. # OpenAI SDK-shaped body so _extract_api_error_context / _summarize_api_error / classify_api_error pick it up.
  168. self.body: dict[str, Any] = {"error": {"message": message, "code": code, "param": param, "type": "error"}}
  169. class AIAgent(
  170. ClientLifecycleMixin, StreamDeliveryMixin, StatusOutputMixin, ApiRequestHooksMixin, ApiErrorSummaryMixin,
  171. InterruptControlMixin, TurnExplainersMixin, ActivityTrackingMixin, RateLimitCreditsMixin,
  172. SessionPersistenceMixin, CompressionFacadeMixin, TurnFacadeMixin, VisionMessagePrepMixin, ReasoningParamsMixin,
  173. ):
  174. """AI Agent with tool calling capabilities."""
  175. _TOOL_CALL_ARGUMENTS_CORRUPTION_MARKER = (
  176. "[hermes-agent: tool call arguments were corrupted in this session and "
  177. "have been dropped to keep the conversation alive. See issue #15236.]"
  178. )
  179. @property
  180. def base_url(self) -> str:
  181. return self._base_url
  182. @base_url.setter
  183. def base_url(self, value: str) -> None:
  184. self._base_url = value
  185. self._base_url_lower = value.lower() if value else ""
  186. self._base_url_hostname = base_url_hostname(value)
  187. def __init__(
  188. self,
  189. base_url: str | None = None, api_key: str | None = None, provider: str | None = None, api_mode: str | None = None,
  190. acp_command: str | None = None, acp_args: list[str] | None = None, command: str | None = None, args: list[str] | None = None,
  191. model: str = "",
  192. max_iterations: int = sys.maxsize, # unlimited tool-calling iterations by default (shared with subagents)
  193. tool_delay: float | None = None, # deprecated: accepted for compatibility, ignored
  194. enabled_toolsets: list[str] | None = None, disabled_toolsets: list[str] | None = None,
  195. save_trajectories: bool = False, verbose_logging: bool = False, quiet_mode: bool = False,
  196. tool_progress_mode: str = "all", ephemeral_system_prompt: str | None = None,
  197. log_prefix_chars: int = 100, log_prefix: str = "",
  198. providers_allowed: list[str] | None = None, providers_ignored: list[str] | None = None, providers_order: list[str] | None = None,
  199. provider_sort: str | None = None, provider_require_parameters: bool = False, provider_data_collection: str | None = None,
  200. openrouter_min_coding_score: Optional[float] = None,
  201. session_id: str | None = None,
  202. tool_progress_callback: Callable[..., Any] | None = None, tool_start_callback: Callable[..., Any] | None = None,
  203. tool_complete_callback: Callable[..., Any] | None = None, thinking_callback: Callable[..., Any] | None = None,
  204. reasoning_callback: Callable[..., Any] | None = None, clarify_callback: Callable[..., Any] | None = None,
  205. read_terminal_callback: Callable[..., Any] | None = None, read_preview_callback: Callable[..., Any] | None = None,
  206. drive_preview_callback: Callable[..., Any] | None = None, read_window_below_callback: Callable[..., Any] | None = None,
  207. connection_callback: Callable[..., Any] | None = None, tour_callback: Callable[..., Any] | None = None,
  208. theme_callback: Callable[..., Any] | None = None,
  209. setup_beat_callback: Callable[..., Any] | None = None,
  210. step_callback: Callable[..., Any] | None = None,
  211. stream_delta_callback: Callable[..., Any] | None = None, interim_assistant_callback: Callable[..., Any] | None = None,
  212. tool_gen_callback: Callable[..., Any] | None = None, status_callback: Callable[..., Any] | None = None,
  213. notice_callback: Callable[..., Any] | None = None, notice_clear_callback: Callable[..., Any] | None = None,
  214. event_callback: Optional[Callable[[str, dict], None]] = None,
  215. reaction_callback: Optional[Callable[[str], None]] = None,
  216. max_tokens: int | None = None, reasoning_config: dict[str, Any] | None = None, service_tier: str | None = None,
  217. request_overrides: dict[str, Any] | None = None, prefill_messages: list[dict[str, Any]] | None = None,
  218. platform: str | None = None, user_id: str | None = None, user_id_alt: str | None = None, user_name: str | None = None,
  219. chat_id: str | None = None, chat_name: str | None = None, chat_type: str | None = None, thread_id: str | None = None,
  220. gateway_session_key: str | None = None,
  221. skip_context_files: bool = False, load_soul_identity: bool = False,
  222. skip_memory: bool = False, skip_background_review: bool = False,
  223. session_db=None, parent_session_id: str | None = None,
  224. iteration_budget: IterationBudget = None, run_budget_seconds: Optional[float] = None,
  225. fallback_model: dict[str, Any] | None = None, credential_pool=None,
  226. checkpoints_enabled: bool = False, checkpoint_max_snapshots: int = 20,
  227. checkpoint_max_total_size_mb: int = 500, checkpoint_max_file_size_mb: int = 10,
  228. pass_session_id: bool = False, requested_provider: str | None = None,
  229. capabilities: dict[str, bool] | None = None, cwd: str | None = None,
  230. side_agent: bool = False, memory_manager=None,
  231. tool_result_metadata_callback: Optional[Callable[..., dict]] = None,
  232. ):
  233. """Forwarder — see ``agent.agent_init.init_agent`` (same keyword parameters, minus ``tool_delay``)."""
  234. init_kwargs = {k: v for k, v in locals().items() if k not in ("self", "tool_delay")}
  235. if tool_delay is not None:
  236. warnings.warn("tool_delay is deprecated and ignored; sequential tool calls "
  237. "no longer sleep between executions.", DeprecationWarning, stacklevel=2)
  238. from agent.agent_init import init_agent
  239. init_agent(self, **init_kwargs)
  240. def _get_session_db_for_recall(self):
  241. """SessionDB for recall, opening the default state DB when no ``session_db`` was passed so the
  242. advertised ``session_search`` tool stays usable."""
  243. # Persistence-isolated forks (background review) must not lazily open the canonical state DB —
  244. # that would re-arm the flush to write the fork's harness turn into the user's real session.
  245. if getattr(self, "_persist_disabled", False):
  246. return None
  247. if self._session_db is not None:
  248. return self._session_db
  249. try:
  250. from hermes_state_registry import acquire
  251. self._session_db = acquire()
  252. self._owns_session_db = True # we opened it, so close() must release it
  253. return self._session_db
  254. except Exception:
  255. logger.debug("SessionDB unavailable for recall", exc_info=True)
  256. return None
  257. def _session_row_model_config(self) -> Any:
  258. """``model_config`` for the lazily created session row: the init config plus a live /yolo toggled
  259. before the first turn (``hermes --resume`` restores it)."""
  260. from tools.approval_yolo import with_session_yolo
  261. return with_session_yolo(self._session_init_model_config, self.session_id)
  262. def _ensure_db_session(self) -> None:
  263. """Create the session DB row on first use; a transient failure leaves it to retry next turn."""
  264. if getattr(self, "_persist_disabled", False) or self._session_db_created or not self._session_db:
  265. return
  266. source = session_source_for(self.platform)
  267. try:
  268. # Persist the profile name explicitly, including "default": profile-keyed consumers treat NULL
  269. # as unowned.
  270. try:
  271. from hermes_cli.profiles import get_active_profile_name
  272. profile_for_session = get_active_profile_name()
  273. except Exception:
  274. # Persist the profile name EXPLICITLY, including "default". NULL used to stand in for the
  275. # default profile, but the #94724 legacy-owner backfill already stamps literal "default"
  276. # onto old rows, and profile-keyed consumers (sidebar scope matching,
  277. # @session:<profile>/<id> deep links) treat NULL as unowned — rows minted NULL after the
  278. # one-shot backfill vanished from the sidebar (#99222).
  279. profile_for_session = None
  280. # Carry the gateway routing identity: when the gateway SessionStore degraded to JSONL (corrupt
  281. # state.db) this lazy create is the ONLY durable write, and an identity-less row is unrecoverable.
  282. self._session_db.create_session(
  283. session_id=self.session_id, source=source, model=self.model,
  284. model_config=self._session_row_model_config(), system_prompt=self._cached_system_prompt,
  285. user_id=getattr(self, "_user_id", None), session_key=getattr(self, "_gateway_session_key", None),
  286. chat_id=getattr(self, "_chat_id", None), chat_type=getattr(self, "_chat_type", None),
  287. thread_id=getattr(self, "_thread_id", None),
  288. display_name=getattr(self, "_chat_name", None) or getattr(self, "_user_name", None),
  289. origin_json=_gateway_origin_json(self), parent_session_id=self._parent_session_id,
  290. cwd=_launch_cwd_for_session(source), profile_name=profile_for_session,
  291. )
  292. self._session_db_created = True
  293. except Exception as e:
  294. # Transient failure (e.g. SQLite lock): _session_db_created stays False so the next turn retries.
  295. logger.warning("Session DB creation failed (will retry next turn): %s", e)
  296. def _transition_context_engine_session(
  297. self, *, old_session_id: Optional[str] = None, new_session_id: Optional[str] = None,
  298. previous_messages: Optional[list] = None, carry_over_context: bool = False, reset_engine: bool = True,
  299. **extra_context,
  300. ) -> None:
  301. """Drive the context engine's session transition: on_session_end → on_session_reset → on_session_start
  302. → carry_over_new_session_context. Each hook is optional (the built-in compressor only resets)."""
  303. engine = getattr(self, "context_compressor", None)
  304. if not engine:
  305. return
  306. if old_session_id and previous_messages is not None:
  307. _call_engine_hook(engine, "on_session_end", old_session_id, previous_messages)
  308. if reset_engine:
  309. _call_engine_hook(engine, "on_session_reset")
  310. should_start = bool(old_session_id or previous_messages is not None or carry_over_context or extra_context)
  311. target_session_id = new_session_id or getattr(self, "session_id", "") or ""
  312. if should_start and target_session_id and hasattr(engine, "on_session_start"):
  313. start_context = {
  314. "old_session_id": old_session_id, "carry_over_context": carry_over_context,
  315. "platform": session_source_for(getattr(self, "platform", None)),
  316. "model": getattr(self, "model", ""), "context_length": getattr(engine, "context_length", None),
  317. "conversation_id": getattr(self, "_gateway_session_key", None), **extra_context,
  318. }
  319. start_context = {k: v for k, v in start_context.items() if v not in (None, "")}
  320. _call_engine_hook(engine, "on_session_start", target_session_id, **start_context)
  321. if carry_over_context and old_session_id and target_session_id:
  322. _call_engine_hook(engine, "carry_over_new_session_context", old_session_id, target_session_id)
  323. def reset_session_state(self, previous_messages: Optional[list] = None, old_session_id: Optional[str] = None,
  324. carry_over_context: bool = False):
  325. """Reset session-scoped token/cost counters and compressor state for a fresh session.
  326. With ``previous_messages`` / ``old_session_id`` / ``carry_over_context`` the context engine gets the
  327. full transition lifecycle instead of a bare reset.
  328. """
  329. for counter in (
  330. "session_total_tokens", "session_input_tokens", "session_output_tokens", "session_prompt_tokens",
  331. "session_completion_tokens", "session_cache_read_tokens", "session_cache_write_tokens",
  332. "session_reasoning_tokens", "session_api_calls",
  333. ):
  334. setattr(self, counter, 0)
  335. self.session_estimated_cost_usd = 0.0
  336. self.session_cost_status = "unknown"
  337. self.session_cost_source = "none"
  338. # Session boundary: the usage anchor describes the OLD transcript; fall back to full estimation.
  339. self._usage_anchor = None
  340. self._turn_base_usage_anchor = None
  341. # The workspace snapshot is pinned per session (agent/system_prompt.py::_coding_parts); a
  342. # /new, /resume or /branch on the same agent must re-snapshot at its own session start.
  343. self._frozen_workspace_snapshot = None
  344. # Turn counter (added after reset_session_state was first written — #2635)
  345. self._user_turn_count = 0
  346. # The drifted-prompt compaction INFO is once per session, so a /new or /resume re-arms it.
  347. self._compaction_prompt_drift_logged = False
  348. # Who wrote the current turn. build_turn_context() sets it at the start of every turn.
  349. self._turn_author = None
  350. # Provider hooks that failed in the old session (agent.provider_route_hooks) are asked again.
  351. self._provider_hook_failures = set()
  352. # True for the first API call of a user turn, False for tool-loop follow-ups (provider request_headers).
  353. self._is_user_initiated_turn = False
  354. self._transition_context_engine_session(
  355. old_session_id=old_session_id, new_session_id=getattr(self, "session_id", None),
  356. previous_messages=previous_messages, carry_over_context=carry_over_context, reset_engine=True,
  357. )
  358. # Reset-only switches (/new, /resume, /branch) change session_id before this call; rebind the
  359. # built-in compressor's session-keyed cooldown state when no full start hook ran.
  360. engine = getattr(self, "context_compressor", None)
  361. target_session_id = getattr(self, "session_id", "") or ""
  362. if (engine is not None and hasattr(engine, "bind_session_state") and target_session_id
  363. and target_session_id != getattr(engine, "_session_id", "")):
  364. try:
  365. engine.bind_session_state(getattr(self, "_session_db", None), target_session_id)
  366. except Exception as exc:
  367. logger.debug("context engine bind_session_state during reset: %s", exc)
  368. @staticmethod
  369. def _effective_lmstudio_context_length(config_context_length: Optional[int], runtime_context_length: Any) -> Optional[int]:
  370. """Return a safe context budget from explicit intent and verified runtime."""
  371. explicit = _positive_int(config_context_length)
  372. runtime = _positive_int(getattr(runtime_context_length, "context_length", runtime_context_length))
  373. if bool(getattr(runtime_context_length, "rejected", False)) or (
  374. bool(getattr(runtime_context_length, "load_attempted", False)) and runtime is None
  375. ):
  376. return None
  377. if runtime is not None and explicit is not None:
  378. return min(runtime, explicit)
  379. return runtime if runtime is not None else explicit
  380. @staticmethod
  381. def _lmstudio_load_was_unverified(load_result: Any) -> bool:
  382. """Return true when a management load was rejected or unverifiable."""
  383. return bool(getattr(load_result, "rejected", False)) or (
  384. bool(getattr(load_result, "load_attempted", False)) and getattr(load_result, "context_length", None) is None
  385. )
  386. def _ensure_lmstudio_runtime_loaded(self, config_context_length: Optional[int] = None) -> Any:
  387. """Preload LM Studio unless configured to rely on JIT loading."""
  388. if (self.provider or "").strip().lower() != "lmstudio":
  389. return None
  390. if (getattr(self, "lmstudio_load_mode", "explicit") or "explicit").strip().lower() == "jit":
  391. logger.debug("LM Studio explicit preload skipped: lmstudio_load_mode=jit")
  392. return None
  393. from hermes_cli.models_local import ensure_lmstudio_model_loaded
  394. if config_context_length is None:
  395. config_context_length = getattr(self, "_config_context_length", None)
  396. return ensure_lmstudio_model_loaded(
  397. self.model, self.base_url, getattr(self, "api_key", ""), config_context_length, return_load_result=True,
  398. )
  399. switch_model = _forward("agent.agent_runtime_helpers", "switch_model")
  400. def _disable_codex_reasoning_replay(
  401. self, messages: Optional[list[dict[str, Any]]] = None, *, keep_replay: bool = False,
  402. ) -> dict[str, int]:
  403. """On HTTP 400 ``invalid_encrypted_content``: pop ``codex_reasoning_items`` from every assistant
  404. message and, unless ``keep_replay``, disable Responses reasoning replay. Returns
  405. ``{"messages", "items"}`` counts."""
  406. stripped_messages = stripped_items = 0
  407. for msg in (messages if isinstance(messages, list) else []):
  408. if not isinstance(msg, dict) or msg.get("role") != "assistant":
  409. continue
  410. items = msg.pop("codex_reasoning_items", None)
  411. if isinstance(items, list) and items:
  412. stripped_messages += 1
  413. stripped_items += len(items)
  414. if not keep_replay:
  415. self._codex_reasoning_replay_enabled = False
  416. return {"messages": stripped_messages, "items": stripped_items}
  417. _stream_diag_init = _forward_static("agent.stream_diag", "stream_diag_init")
  418. _stream_diag_capture_response = _forward("agent.stream_diag", "stream_diag_capture_response")
  419. _flatten_exception_chain = _forward_static("agent.stream_diag", "flatten_exception_chain")
  420. def _is_provider_stream_parse_error(self, error: BaseException) -> bool:
  421. """True for a malformed Anthropic event-stream frame (surfaced by the SDK as a plain ``ValueError``);
  422. that is wire trouble, not local validation, so it follows the truncated-JSON retry path."""
  423. return getattr(self, "api_mode", None) == "anthropic_messages" and is_provider_stream_parse_error(error)
  424. _log_stream_retry = _forward("agent.stream_diag", "log_stream_retry")
  425. _emit_stream_drop = _forward("agent.stream_diag", "emit_stream_drop")
  426. def _emit_auxiliary_failure(self, task: str, exc: BaseException) -> None:
  427. """Surface a compact warning for failed auxiliary work."""
  428. try:
  429. detail = self._summarize_api_error(exc)
  430. except Exception:
  431. detail = str(exc)
  432. detail = (detail or exc.__class__.__name__).strip()
  433. if len(detail) > 220:
  434. detail = detail[:217].rstrip() + "..."
  435. self._emit_warning(f"⚠ Auxiliary {task} failed: {detail}")
  436. def _current_main_runtime(self) -> dict[str, str]:
  437. """Return the live main runtime for session-scoped auxiliary routing."""
  438. return {
  439. key: getattr(self, key, "") or ""
  440. for key in ("model", "provider", "base_url", "api_key", "api_mode", "auth_mode", "session_id")
  441. }
  442. _check_compression_model_feasibility = _forward("agent.conversation_compression", "check_compression_model_feasibility")
  443. _replay_compression_warning = _forward("agent.conversation_compression", "replay_compression_warning")
  444. def _hostname_for(self, base_url: Optional[str]) -> str:
  445. """Hostname of ``base_url``, or of the agent's own base URL when None."""
  446. if base_url is not None:
  447. return base_url_hostname(base_url)
  448. return getattr(self, "_base_url_hostname", "") or base_url_hostname(getattr(self, "_base_url_lower", ""))
  449. def _is_direct_openai_url(self, base_url: str | None = None) -> bool:
  450. """Return True when a base URL targets OpenAI's native API."""
  451. return self._hostname_for(base_url) == "api.openai.com"
  452. def _is_azure_openai_url(self, base_url: str | None = None) -> bool:
  453. """True when a base URL targets Azure OpenAI (standard client, but NO Responses API support)."""
  454. url = str(base_url).lower() if base_url is not None else (getattr(self, "_base_url_lower", "") or "")
  455. return base_url_host_matches(url, "openai.azure.com")
  456. def _resolved_api_call_timeout(self) -> float:
  457. """Per-call request timeout: per-model ``timeout_seconds`` > provider ``request_timeout_seconds`` >
  458. ``HERMES_API_TIMEOUT`` > 1800s."""
  459. cfg = get_provider_request_timeout(self.provider, self.model)
  460. return cfg if cfg is not None else env_float("HERMES_API_TIMEOUT", 1800.0)
  461. def _resolved_api_call_stale_timeout_base(self) -> tuple[float, bool]:
  462. """Base non-stream stale timeout: per-model ``stale_timeout_seconds`` > provider-wide >
  463. ``HERMES_API_CALL_STALE_TIMEOUT`` > reasoning floor > 90s.
  464. Returns ``(seconds, uses_implicit_default)``; the implicit flag lets callers auto-disable the detector
  465. for local endpoints only when the user configured nothing.
  466. """
  467. cfg = get_provider_stale_timeout(self.provider, self.model)
  468. if cfg is not None:
  469. return cfg, False
  470. env_timeout = os.getenv("HERMES_API_CALL_STALE_TIMEOUT")
  471. if env_timeout is not None:
  472. return float(env_timeout), False
  473. # Reasoning-model floor (cloud gateways idle-kill mid-think); not "implicit" so the local-endpoint
  474. # short-circuit does not disable stale detection here.
  475. from agent.reasoning_timeouts import get_reasoning_stale_timeout_floor
  476. reasoning_floor = get_reasoning_stale_timeout_floor(self.model)
  477. if reasoning_floor is not None:
  478. return reasoning_floor, False
  479. return 90.0, True
  480. def _compute_non_stream_stale_timeout(self, api_payload: Any) -> float:
  481. """Effective non-stream stale timeout for ``api_payload`` (an ``api_kwargs`` dict or legacy ``messages``
  482. list), scaled by estimated context size and capped by the run budget."""
  483. stale_base, uses_implicit_default = self._resolved_api_call_stale_timeout_base()
  484. base_url = getattr(self, "_base_url", None) or self.base_url or ""
  485. if uses_implicit_default and base_url and is_local_endpoint(base_url):
  486. return float("inf")
  487. from agent.chat_completion_helpers import _high_effort_silence_floor, cap_to_run_budget, estimate_request_context_tokens
  488. from agent.gemini_long_decode import long_decode_stale_multiplier
  489. est_tokens = estimate_request_context_tokens(api_payload)
  490. timeout = max(stale_base, 240.0) if est_tokens > 100_000 else max(stale_base, 150.0) if est_tokens > 50_000 else stale_base
  491. explicit = self._stale_timeout_is_explicit()
  492. # High-effort Codex reasoning (#112909) floors the IMPLICIT stale timeout before the run-budget
  493. # cap below, so the floor can never outlive the run budget.
  494. if self.api_mode == "codex_responses" and not explicit:
  495. timeout = max(timeout, _high_effort_silence_floor(self))
  496. if not explicit:
  497. timeout *= long_decode_stale_multiplier(api_payload)
  498. # Run-budget cap: an implicit stale timeout is capped at half the remaining budget (>= 60s) so one
  499. # hung call cannot eat the run. Never raises the timeout; explicit user config still wins.
  500. if not explicit:
  501. timeout = cap_to_run_budget(self, timeout)
  502. return timeout
  503. def _stale_timeout_is_explicit(self) -> bool:
  504. """True when the user explicitly configured the stale timeout (config or env var); implicit values
  505. (reasoning floors, the 90s default) yield to the run-budget cap, explicit ones never do."""
  506. return (get_provider_stale_timeout(self.provider, self.model) is not None
  507. or os.getenv("HERMES_API_CALL_STALE_TIMEOUT") is not None)
  508. def _codex_silent_hang_hint(self, model: Optional[str] = None) -> Optional[str]:
  509. """Actionable hint when the request matches a known Codex silent-reject shape (currently the ``gpt-5.5``
  510. family: connection accepted, no events, no error), else None. Makes the stale timeout actionable."""
  511. if self.api_mode != "codex_responses":
  512. return None
  513. from agent.codex_responses_adapter import classify_responses_route
  514. if not classify_responses_route(self).is_codex_backend:
  515. return None
  516. eff_model = (model if model is not None else self.model) or ""
  517. # Match the gpt-5.5 family at word boundaries (bare, -codex, vendor-prefixed) but not gpt-5.50.
  518. if not re.search(r"(?:^|[/\-_])gpt-5\.5(?:$|[\-_])", eff_model.lower()):
  519. return None
  520. return (
  521. f"Codex backend appears to be silently rejecting {eff_model!r} "
  522. "on chatgpt.com/backend-api/codex (no stream events, no error). "
  523. "This is a known backend-side pattern that has affected ChatGPT "
  524. "Plus accounts intermittently. "
  525. "Workaround: try `gpt-5.4` on the same OAuth profile, "
  526. "or switch to a different model/provider in your fallback chain. "
  527. "Some ChatGPT Codex accounts do not support `gpt-5.4-codex`. "
  528. "See hermes-agent#21444 for symptom history."
  529. )
  530. def _is_openrouter_url(self) -> bool:
  531. """Return True when the base URL targets OpenRouter."""
  532. return base_url_host_matches(self._base_url_lower, "openrouter.ai")
  533. def _is_codex_backend(self) -> bool:
  534. """Return True for the ChatGPT OAuth Codex Responses backend."""
  535. return (getattr(self, "api_mode", None) == "codex_responses"
  536. and getattr(self, "_base_url_hostname", "") == "chatgpt.com"
  537. and "/backend-api/codex" in (getattr(self, "_base_url_lower", "") or ""))
  538. _anthropic_prompt_cache_policy = _forward("agent.agent_runtime_helpers", "anthropic_prompt_cache_policy")
  539. _direct_native_anthropic_tool_cache_capability = _forward("agent.agent_runtime_helpers", "_direct_native_anthropic_tool_cache_capability")
  540. @staticmethod
  541. def _model_requires_responses_api(model: str) -> bool:
  542. """True for GPT-5.x, which OpenAI and OpenRouter reject on /v1/chat/completions
  543. (``unsupported_api_for_model``)."""
  544. return model.lower().rsplit("/", 1)[-1].startswith("gpt-5") # strip vendor prefix ("openai/gpt-5.4")
  545. @staticmethod
  546. def _provider_model_requires_responses_api(model: str, *, provider: Optional[str] = None) -> bool:
  547. """Return True when this provider/model pair should use Responses API."""
  548. from hermes_cli.providers import is_actual_route
  549. normalized_provider = (provider or "").strip().lower()
  550. # Nous serves GPT-5.x via chat completions (its /v1/responses returns 404); generic custom endpoints
  551. # may relay GPT-5 without full Responses semantics — only direct OpenAI/xAI URLs auto-upgrade.
  552. if normalized_provider in ("nous", "custom") or is_actual_route(provider):
  553. return False
  554. # ACP facades expose the OpenAI-compatible chat.completions shape regardless of model
  555. # family and have no ``responses`` attribute, so neither primary routing nor GPT-5
  556. # fallback activation may upgrade them. Keyed on the profile's auth_type: every
  557. # external-process provider, not one vendor's names.
  558. from hermes_cli.runtime_provider_backends import _is_external_process_provider
  559. if _is_external_process_provider(normalized_provider):
  560. return False
  561. # A provider serving several wires behind one endpoint decides per model (pure, no I/O).
  562. from providers import get_provider_profile
  563. profile = get_provider_profile(normalized_provider) if normalized_provider else None
  564. from agent.provider_route_hooks import model_api_mode
  565. derived = model_api_mode(profile, model) if profile is not None else None
  566. if derived is not None:
  567. return derived == "codex_responses"
  568. return AIAgent._model_requires_responses_api(model)
  569. def _max_tokens_param(self, value: int) -> dict:
  570. """``max_completion_tokens`` for newer OpenAI families (and Azure / provider routes declaring it),
  571. else ``max_tokens``. URL-first, then model-name fallback for third-party endpoints fronting those models."""
  572. if self._is_direct_openai_url() or self._is_azure_openai_url():
  573. return {"max_completion_tokens": value}
  574. from agent.provider_route_hooks import route_answer
  575. declared = route_answer("max_tokens_param", provider=getattr(self, "provider", "") or "", scope=self,
  576. base_url=getattr(self, "base_url", "") or "", model=self.model or "")
  577. if declared:
  578. return {declared: value}
  579. if model_forces_max_completion_tokens(self.model):
  580. return {"max_completion_tokens": value}
  581. return {"max_tokens": value}
  582. @staticmethod
  583. def _requested_output_cap_from_api_kwargs(api_kwargs: Any) -> Optional[int]:
  584. """Extract the outgoing response token cap from a prepared request."""
  585. if not isinstance(api_kwargs, dict):
  586. return None
  587. for key in ("max_output_tokens", "max_completion_tokens", "max_tokens"):
  588. try:
  589. value = int(api_kwargs.get(key))
  590. except (TypeError, ValueError):
  591. continue
  592. if value > 0:
  593. return value
  594. return None
  595. def _has_content_after_think_block(self, content: str) -> bool:
  596. """True when text remains after stripping reasoning blocks (reasoning-only output is retried)."""
  597. return bool(content) and bool(self._strip_think_blocks(content).strip())
  598. _strip_think_blocks = _forward("agent.agent_runtime_helpers", "strip_think_blocks")
  599. @staticmethod
  600. def _has_natural_response_ending(content: str) -> bool:
  601. """Heuristic: does visible assistant text look intentionally finished?"""
  602. stripped = (content or "").rstrip()
  603. if not stripped:
  604. return False
  605. last = stripped[-1]
  606. # Closing punctuation/brackets, a fenced-code close, or an emoji (Misc Symbols, Dingbats, Emoticons, ...).
  607. return stripped.endswith("```") or last in '.!?:)"\']}。!?:)】」』》^' or ord(last) >= 0x1F300
  608. def _is_ollama_glm_backend(self) -> bool:
  609. """Ollama-hosted GLM models misreport finish_reason='stop'. Matches only explicit Ollama signatures
  610. (port 11434, "ollama" in URL, provider ollama), never arbitrary local proxies; excludes Ollama Cloud
  611. (``ollama.com`` / ``:cloud``), which reports faithfully — rewriting it would manufacture truncations.
  612. Crucially it does NOT match arbitrary local/private endpoints (LiteLLM/sglang/vLLM/LM Studio
  613. proxies, Tailscale boxes), which report finish_reason correctly and were the source of #13971's
  614. false-positive truncation continuations.
  615. Two signatures identify it: the ``ollama.com`` host (provider ``ollama-cloud``) and the ``:cloud``
  616. model suffix (cloud generation proxied through a local 11434 endpoint, #98406). Applying the
  617. stop→length rewrite to them manufactures false truncations and causes the continuation nudge to
  618. consume the model's output budget on the next retry, making further false-positives more likely.
  619. """
  620. model_lower = (self.model or "").lower()
  621. provider_lower = (self.provider or "").lower()
  622. if "glm" not in model_lower and provider_lower != "zai":
  623. return False
  624. base = self._base_url_lower
  625. # Ollama Cloud (hosted service or :cloud proxy) forwards finish_reason faithfully — do not rewrite.
  626. if "ollama.com" in base or ":cloud" in model_lower:
  627. return False
  628. if "ollama" in base or ":11434" in base:
  629. return True
  630. return provider_lower == "ollama"
  631. def _should_treat_stop_as_truncated(self, finish_reason: str, assistant_message, messages: Optional[list] = None) -> bool:
  632. """Detect conservative stop->length misreports for Ollama-hosted GLM models."""
  633. if finish_reason != "stop" or self.api_mode != "chat_completions" or not self._is_ollama_glm_backend():
  634. return False
  635. if not any(isinstance(msg, dict) and msg.get("role") == "tool" for msg in (messages or [])):
  636. return False
  637. if assistant_message is None or getattr(assistant_message, "tool_calls", None):
  638. return False
  639. content = getattr(assistant_message, "content", None)
  640. if not isinstance(content, str):
  641. return False
  642. visible_text = self._strip_think_blocks(content).strip()
  643. if len(visible_text) < 20 or not re.search(r"\s", visible_text):
  644. return False
  645. return not self._has_natural_response_ending(visible_text)
  646. _looks_like_codex_intermediate_ack = _forward("agent.agent_runtime_helpers", "looks_like_codex_intermediate_ack")
  647. _extract_reasoning = _forward("agent.agent_runtime_helpers", "extract_reasoning")
  648. _cleanup_task_resources = _forward("agent.chat_completion_helpers", "cleanup_task_resources")
  649. # Background memory/skill review — prompts live in agent.background_review.
  650. from agent.background_review import _MEMORY_REVIEW_PROMPT, _SKILL_REVIEW_PROMPT, _COMBINED_REVIEW_PROMPT
  651. _summarize_background_review_actions = _forward_static("agent.background_review", "summarize_background_review_actions")
  652. def _spawn_background_review(self, messages_snapshot: list[dict], review_memory: bool = False,
  653. review_skills: bool = False, focus: Optional[str] = None, explicit: bool = False) -> None:
  654. """Post-turn review entry point: decide WHEN, then spawn.
  655. A review whose runtime is the MANAGED LOCAL llama-server is queued for machine idle (``defer: auto``)
  656. instead of hitting the user's GPU mid-session; everything else spawns immediately. ``explicit``
  657. (/refine, with or without focus) is user-initiated: it bypasses the automatic-only delegate,
  658. ``enabled`` and idle-defer gates (#87250: ``enabled: false`` stops only automatic forks).
  659. """
  660. # Automatic-review gates run at enqueue/spawn time; the idle dispatcher re-checks `enabled` at dispatch time.
  661. if not explicit and focus is None and getattr(self, "_delegate_depth", 0) > 0:
  662. return
  663. from agent.runtime_context import current, dispatch
  664. context = current()
  665. if context is not None:
  666. if context.get("review") is None and context.get("config", {}).get("memory", {}).get("automatic", True):
  667. dispatch("yaovi_learning_enqueue", {"messages": messages_snapshot, "focus": focus})
  668. return
  669. task_cfg = None
  670. if not explicit and focus is None:
  671. from agent.background_review import load_background_review_settings
  672. enabled, task_cfg = load_background_review_settings()
  673. if not enabled:
  674. return
  675. # Structural clone at the single chokepoint: the fork sanitizes in place, and a shallow copy would
  676. # alias the live history's nested tool_calls/content.
  677. # Structural clone at the single chokepoint every review path (automatic, /refine, idle-queue
  678. # deferral) goes through. See #100795.
  679. from agent.turn_finalizer import _clone_background_review_messages
  680. kwargs = dict(messages_snapshot=_clone_background_review_messages(messages_snapshot),
  681. review_memory=review_memory, review_skills=review_skills, focus=focus, task_cfg=task_cfg,
  682. explicit=explicit)
  683. if focus is None and not explicit and _review_should_defer(self, task_cfg):
  684. from agent.review_idle_queue import QUEUE
  685. QUEUE.enqueue(self, _review_queue_key(self), kwargs)
  686. return
  687. self._spawn_background_review_now(**kwargs)
  688. def _spawn_background_review_now(self, messages_snapshot: list[dict], review_memory: bool = False,
  689. review_skills: bool = False, focus: Optional[str] = None,
  690. task_cfg: Optional[dict[str, Any]] = None, _requeue_attempts: int = 0,
  691. explicit: bool = False) -> None:
  692. """Spawn the background memory/skill review thread.
  693. ``threading.Thread`` is constructed here so tests patching ``run_agent.threading.Thread`` keep working.
  694. ``focus`` is /refine steering text; ``task_cfg`` is the pre-loaded config block (None on direct calls).
  695. ``explicit`` (/refine) forks under the ``refine_review`` write origin, keeping the full
  696. memory operation set. A deferred review preempted by a live turn is requeued (bounded)
  697. rather than lost.
  698. """
  699. from agent.background_review import (
  700. finish_background_review_run, prepare_background_review_run, spawn_background_review_thread,
  701. )
  702. from tools.thread_context import propagate_context_to_thread
  703. review_run = prepare_background_review_run(self)
  704. if review_run is None:
  705. return
  706. try:
  707. target, _prompt = spawn_background_review_thread(
  708. self, messages_snapshot, review_memory=review_memory, review_skills=review_skills,
  709. focus=focus, task_cfg=task_cfg, review_run=review_run, explicit=explicit,
  710. )
  711. def _target_with_requeue() -> None:
  712. target()
  713. self._maybe_requeue_preempted_review(review_run, dict(
  714. messages_snapshot=messages_snapshot, review_memory=review_memory, review_skills=review_skills,
  715. focus=focus, task_cfg=task_cfg, _requeue_attempts=_requeue_attempts + 1,
  716. explicit=explicit))
  717. # Carry the active profile into the review thread so MEMORY.md / skill review writes land in the
  718. # right profile.
  719. threading.Thread(target=propagate_context_to_thread(_target_with_requeue), daemon=True, name="bg-review").start()
  720. except Exception:
  721. finish_background_review_run(self, review_run)
  722. raise
  723. _REVIEW_REQUEUE_MAX_ATTEMPTS = 3
  724. def _maybe_requeue_preempted_review(self, review_run, kwargs) -> None:
  725. """Requeue a deferred-mode review that a live turn cancelled.
  726. Only for automatic reviews on the managed local runtime; bounded attempts stop a busy box cycling
  727. forever.
  728. """
  729. try:
  730. # Not cancelled == ran to completion (or was never admitted).
  731. if not review_run.cancel_requested.is_set() or kwargs.get("focus") is not None or kwargs.get("explicit"):
  732. return
  733. if kwargs.get("_requeue_attempts", 0) > self._REVIEW_REQUEUE_MAX_ATTEMPTS:
  734. logger.info("Preempted background review dropped after %d requeues", self._REVIEW_REQUEUE_MAX_ATTEMPTS)
  735. return
  736. if not _review_should_defer(self, kwargs.get("task_cfg")):
  737. return
  738. from agent.review_idle_queue import QUEUE
  739. # kwargs carries the incremented _requeue_attempts through the queue so the cap survives.
  740. QUEUE.enqueue(self, _review_queue_key(self), dict(kwargs))
  741. except Exception:
  742. logger.debug("Preempted-review requeue failed", exc_info=True)
  743. _build_memory_write_metadata = _forward("agent.background_review", "build_memory_write_metadata")
  744. _apply_pending_steer_to_tool_results = _forward("agent.agent_runtime_helpers", "apply_pending_steer_to_tool_results")
  745. def get_activity_summary(self) -> dict:
  746. """Diagnostic snapshot: ``last_activity_*`` plus the short aliases gateway and delegate readers use."""
  747. from agent.session_activity import build_activity_snapshot
  748. provenance = getattr(self, "_last_activity_provenance", None)
  749. return build_activity_snapshot(
  750. last_activity_at=getattr(self, "_last_activity_ts", None),
  751. last_activity_description=getattr(self, "_last_activity_desc", None) or "",
  752. last_activity_provenance=provenance if provenance is not None else ActivityProvenance.UNKNOWN,
  753. extra={
  754. "current_tool": self._current_tool, "api_call_count": self._api_call_count,
  755. "max_iterations": self.max_iterations, "budget_used": self.iteration_budget.used,
  756. "budget_max": self.iteration_budget.max_total,
  757. },
  758. )
  759. def shutdown_memory_provider(self, messages: list | None = None) -> None:
  760. """Shut down the memory provider and context engine at session end (idempotent: gateway cleanup and
  761. ``close()`` may both call it)."""
  762. if getattr(self, "_memory_provider_shutdown", False):
  763. return
  764. self._memory_provider_shutdown = True
  765. if self._memory_manager and self._memory_manager.claim_teardown(session_end=True):
  766. try:
  767. self._memory_manager.on_session_end(messages or [])
  768. except Exception as e:
  769. logger.warning("Memory provider on_session_end failed during shutdown: %s", e, exc_info=True)
  770. _quietly(lambda: self._memory_manager.shutdown_all())
  771. _notify_context_engine_session_end(self, messages)
  772. def commit_memory_session(self, messages: list | None = None) -> None:
  773. """Flush end-of-session extraction on session_id rotation (/new, compression) without tearing providers
  774. down."""
  775. if self._memory_manager:
  776. _quietly(lambda: self._memory_manager.on_session_end(messages or []))
  777. _notify_context_engine_session_end(self, messages)
  778. def _sync_external_memory_for_turn(self, *, original_user_message: Any, final_response: Any, interrupted: bool,
  779. messages: list | None = None) -> None:
  780. """Mirror a completed turn into external memory providers (``sync_all`` + ``queue_prefetch_all``).
  781. Uses ``original_user_message`` (``user_message`` may carry injected skill content). Interrupted turns
  782. are skipped: partial output is not durable truth. Best-effort — an offline backend never blocks.
  783. A partial assistant output, an aborted tool chain, or a mid-stream reset is not durable
  784. conversational truth — mirroring it into an external memory backend pollutes future recall with
  785. state the user never saw completed. The prefetch is gated on the same flag: the user's next message
  786. is almost certainly a retry of the same intent, and a prefetch keyed on the interrupted turn would
  787. fire against stale context. See #15218.
  788. """
  789. if interrupted or not (self._memory_manager and final_response and original_user_message):
  790. return
  791. # Flatten multimodal parts to text (newline-joined for memory).
  792. user_text = _summarize_user_message_for_log(original_user_message, sep="\n")
  793. response_text = _summarize_user_message_for_log(final_response, sep="\n")
  794. if not (user_text and response_text):
  795. return
  796. try:
  797. sync_kwargs = {"session_id": self.session_id or "", **({"messages": messages} if messages is not None else {})}
  798. # Stashed by build_turn_context() for this turn, None on a human turn.
  799. turn_author = getattr(self, "_turn_author", None)
  800. if turn_author is not None:
  801. sync_kwargs["turn_author"] = turn_author
  802. self._memory_manager.sync_all(user_text, response_text, **sync_kwargs)
  803. # Sibling of the build_turn_context() prefetch gate: don't key recall on zero-signal prompts.
  804. if not is_trivial_prompt(user_text):
  805. self._memory_manager.queue_prefetch_all(user_text, session_id=self.session_id or "")
  806. except Exception:
  807. pass
  808. def release_clients(self) -> None:
  809. """Release LLM clients, child agents and memory providers WITHOUT tearing down session tool state (gateway
  810. cache eviction: the session may resume on the same task_id, so processes, sandbox, browser and computer-use
  811. are kept). Idempotent; distinct from ``close()``."""
  812. self._close_active_children(soft=True)
  813. # Retire (don't hard-close) the shared client: eviction runs on the gateway memory-manager thread,
  814. # and a cross-thread close can release TLS FDs under a still-unwinding worker.
  815. _quietly(self._drop_shared_client, lambda c: self._retire_shared_openai_client(c, reason="cache_evict"))
  816. self._close_request_clients("cache_evict")
  817. # The Codex app-server child is an LLM client, not session tool state: the evicted instance is popped
  818. # from the cache and a rebuilt agent spawns its own child, so an unclosed one leaks for the gateway's life.
  819. _quietly(self._close_codex_session)
  820. if getattr(self, "_memory_manager", None) is not None:
  821. _quietly(self._memory_manager.release_soft)
  822. from agent.prepared_compaction import release_for_agent
  823. _quietly(release_for_agent, self)
  824. def close(self) -> None:
  825. """Release every resource this agent holds (idempotent); each phase is guarded so one failure never
  826. blocks the rest."""
  827. session_messages = getattr(self, "_session_messages", None)
  828. _quietly(self.shutdown_memory_provider, session_messages if isinstance(session_messages, list) else None)
  829. self._close_task_resources(getattr(self, "session_id", None) or "")
  830. self._close_active_children(soft=False)
  831. from agent.prepared_compaction import release_for_agent
  832. _quietly(release_for_agent, self)
  833. _quietly(self._drop_shared_client, lambda c: self._close_openai_client(c, reason="agent_close", shared=True))
  834. self._close_request_clients("agent_close")
  835. _quietly(self._close_codex_session)
  836. # Free conversation history proactively: callers may still hold the closed agent. The DB-flush
  837. # settled-prefix snapshot and the streamed-text accumulator are shadow copies of the same transcript;
  838. # on a closed delegate child they were the only remaining owners, pinning its history in the parent heap.
  839. self._session_messages = []
  840. self._db_flush_scan_prefix = None
  841. self._streamed_assistant_text_parts = []
  842. if isinstance(session_messages, list):
  843. # The token-estimate memo pins message strings; a closed conversation's can never hit again. The
  844. # system prompt reaches the memo only through api_messages, never through the history, and a
  845. # prompt-caching request splits it into the static prefix + a per-request suffix slice: the
  846. # prefix's pin evicts that split entry.
  847. from agent.model_metadata_token_memo import forget_message_token_memo
  848. _quietly(forget_message_token_memo, (session_messages, getattr(self, "_cached_system_prompt", None),
  849. getattr(self, "_cached_system_prompt_static", None)))
  850. _quietly(self._trim_process_memory)
  851. _quietly(self._finalize_owned_session_row)
  852. # -- close()/release_clients() phases -------------------------------------------------------------
  853. def _close_active_children(self, *, soft: bool) -> None:
  854. """Detach and close per-turn child agents; ``soft`` releases their clients first, falling back to close()."""
  855. try:
  856. with self._active_children_lock:
  857. children = list(self._active_children)
  858. self._active_children.clear()
  859. except Exception:
  860. return
  861. for child in children:
  862. if soft:
  863. try:
  864. child.release_clients()
  865. continue
  866. except Exception:
  867. pass
  868. _quietly(lambda: child.close())
  869. def _drop_shared_client(self, close_fn: Callable[[Any], None]) -> None:
  870. """Hand the shared OpenAI/httpx client to ``close_fn`` and clear the attribute."""
  871. # Retire the OpenAI/httpx client to release sockets immediately. #70773: eviction runs on the
  872. # gateway's memory-manager thread — a cross-thread hard close of the shared client can release TLS
  873. # FDs under a still-unwinding worker (FD-recycle → SQLite corruption). Retirement shuts the pooled
  874. # sockets down (the memory/socket win we want here) and lets GC release the FDs once no thread holds
  875. # them.
  876. client = getattr(self, "client", None)
  877. if client is not None:
  878. close_fn(client)
  879. self.client = None
  880. def _close_request_clients(self, reason: str) -> None:
  881. """Drop the cached per-request wire clients (reused across sequential LLM calls)."""
  882. _quietly(self._close_cached_request_openai_client, reason=reason)
  883. _quietly(self._close_cached_request_anthropic_client, reason=reason)
  884. def _close_codex_session(self) -> None:
  885. """Close the Codex app-server session (else the child keeps running); the attribute is cleared BEFORE
  886. close() so a concurrent reader can't grab a half-closed session."""
  887. codex_session = getattr(self, "_codex_session", None)
  888. if codex_session is not None:
  889. self._codex_session = None
  890. codex_session.close()
  891. @staticmethod
  892. def _trim_process_memory() -> None:
  893. """Return freed pages to the OS; no full GC here (it would freeze every other session), the idle one runs."""
  894. from hermes_cli.mem_trim import note_agent_closed, trim_memory
  895. note_agent_closed()
  896. trim_memory(force=True, reason="agent close", collect=False)
  897. def _finalize_owned_session_row(self) -> None:
  898. """End the session row unless ownership was handed forward (compression helpers, review forks sharing
  899. the parent's id; end_session() is first-reason-wins), then release the SQLite handle ONLY when this
  900. agent owns it — a dedicated handle left open pins its fds and token-writer thread for the process
  901. lifetime. The owner flag is cleared first so close() stays idempotent."""
  902. session_db = getattr(self, "_session_db", None)
  903. session_id = getattr(self, "session_id", None)
  904. if getattr(self, "_end_session_on_close", True) and session_db and session_id:
  905. _quietly(lambda: session_db.end_session(session_id, "agent_close"))
  906. if getattr(self, "_owns_session_db", False) and session_db is not None:
  907. self._owns_session_db = False
  908. # Shared instances no-op on close(); release the refcount so the registry closes on the last caller.
  909. # See #90837.
  910. from hermes_state_registry import release_or_close
  911. release_or_close(session_db)
  912. def _hydrate_todo_store(self, history: list[dict[str, Any]]) -> None:
  913. """Replay the most recent todo tool response (the gateway builds a fresh AIAgent per message). Only
  914. results paired with an earlier assistant Todo-tool call count — a forged bare ``role: tool`` message
  915. must not seed the store (GHSA-5g4g-6jrg-mw3g)."""
  916. found = self._latest_todo_response(history)
  917. if found is not None:
  918. last_todo_response, last_todo_revision = found
  919. # Restore only when history carries a newer revision than the store holds; empty lists are an
  920. # authoritative clear.
  921. try:
  922. history_revision = max(0, int(last_todo_revision or 0))
  923. except (TypeError, ValueError):
  924. history_revision = 1
  925. if history_revision > int(self._todo_store.snapshot().get("revision", 0) or 0):
  926. self._todo_store.restore(last_todo_response, revision=history_revision)
  927. if not self.quiet_mode:
  928. self._vprint(f"{self.log_prefix}📋 Restored {len(last_todo_response)} todo item(s) from history")
  929. _set_interrupt(False)
  930. def _latest_todo_response(self, history: list[dict[str, Any]]) -> Optional[tuple]:
  931. """Walk history backwards for the newest paired, size-bounded todo result → ``(todos, revision)``."""
  932. from tools.todo_tool import MAX_TODO_RESULT_CHARS
  933. for idx in range(len(history) - 1, -1, -1):
  934. msg = history[idx]
  935. content = msg.get("content", "")
  936. if msg.get("role") != "tool" or not isinstance(content, str) or not self._tool_response_matches_todo_call(history, idx):
  937. continue
  938. if len(content) > MAX_TODO_RESULT_CHARS:
  939. logger.warning("Skipping oversized todo tool response during hydration: "
  940. "session=%s chars=%d", self.session_id or "none", len(content))
  941. continue
  942. if '"todos"' not in content: # cheap pre-filter before json.loads
  943. continue
  944. try:
  945. data = json.loads(content)
  946. except (json.JSONDecodeError, TypeError):
  947. continue
  948. if "todos" in data and isinstance(data["todos"], list):
  949. return data["todos"], data.get("revision", 1)
  950. return None
  951. @classmethod
  952. def _tool_response_matches_todo_call(cls, history: list[dict[str, Any]], tool_index: int) -> bool:
  953. """True when the nearest prior assistant message issued a Todo-tool call (legacy aliases and the
  954. ``tool_call`` bridge canonicalized) with this ``tool_call_id``; a ``user``/``system`` boundary or
  955. missing id means unpaired → must not hydrate."""
  956. tool_call_id = history[tool_index].get("tool_call_id") if 0 <= tool_index < len(history) else None
  957. if not tool_call_id:
  958. return False
  959. for prior in reversed(history[:tool_index]):
  960. role = prior.get("role")
  961. if role == "assistant":
  962. return cls._assistant_has_todo_tool_call(prior, tool_call_id)
  963. if role in {"user", "system"}:
  964. return False
  965. return False
  966. @classmethod
  967. def _assistant_has_todo_tool_call(cls, assistant_msg: dict[str, Any], tool_call_id: str) -> bool:
  968. """True when the paired call resolves to the registered Todo tool."""
  969. from tools.todo_tool import is_todo_tool_call
  970. tool_calls = assistant_msg.get("tool_calls")
  971. return isinstance(tool_calls, list) and any(
  972. cls._get_tool_call_id_static(tc) == tool_call_id and is_todo_tool_call(tc) for tc in tool_calls
  973. )
  974. @property
  975. def is_interrupted(self) -> bool:
  976. """Check if an interrupt has been requested."""
  977. return self._interrupt_requested
  978. _build_system_prompt = _forward("agent.system_prompt", "build_system_prompt")
  979. # Call ID of a tool_call entry (dict or object); policy owner: ``message_sanitization.coalesce_tool_call_id``.
  980. _get_tool_call_id_static = staticmethod(_sanitize_coalesce_tool_call_id)
  981. @staticmethod
  982. def _get_tool_call_name_static(tc) -> str:
  983. """Function name of a tool_call entry (dict or object); Gemini requires it on every ``role: tool`` message."""
  984. if isinstance(tc, dict):
  985. fn = tc.get("function")
  986. return (fn.get("name", "") or "") if isinstance(fn, dict) else ""
  987. return getattr(getattr(tc, "function", None), "name", "") or ""
  988. _VALID_API_ROLES = frozenset({"system", "user", "assistant", "tool", "function", "developer"})
  989. _sanitize_api_messages = _forward_static("agent.agent_runtime_helpers", "sanitize_api_messages")
  990. @staticmethod
  991. def _is_thinking_only_assistant(msg: dict[str, Any], *, drop_codex_reasoning_items: bool = True) -> bool:
  992. """True if ``msg`` is an assistant turn whose only payload is reasoning (no text, no tool_calls).
  993. Providers converting reasoning to thinking blocks reject it (400 "final block cannot be thinking"), so
  994. the turn is dropped from the API copy; the transcript keeps the reasoning block.
  995. """
  996. if not isinstance(msg, dict) or msg.get("role") != "assistant" or msg.get("tool_calls"):
  997. return False
  998. # Prefill stubs are thinking-only by construction; checked before content inspection since
  999. # repair_empty_non_final_messages may have healed content.
  1000. if msg.get("_thinking_prefill"):
  1001. return True
  1002. if AIAgent._content_has_real_payload(msg.get("content")):
  1003. return False
  1004. # A native compaction checkpoint makes a carrier never thinking-only, regardless of api_mode or
  1005. # reasoning field. Checked above every reasoning branch so no carrier shape is dropped.
  1006. # The checkpoint is the server-side stand-in for already-pruned history and exists in exactly one
  1007. # place; the codex_responses adapter also surfaces commentary text via msg["reasoning"], so the
  1008. # string branch below would otherwise drop a carrier before the sidecar is ever inspected. See
  1009. # #82108.
  1010. from agent.native_compaction import has_compaction_checkpoint
  1011. if has_compaction_checkpoint(msg.get("codex_reasoning_items")):
  1012. return False
  1013. reasoning = msg.get("reasoning_content") or msg.get("reasoning")
  1014. rd = msg.get("reasoning_details")
  1015. if (isinstance(reasoning, str) and reasoning.strip()) or (isinstance(rd, list) and rd):
  1016. return True
  1017. # Codex Responses keeps encrypted reasoning under a separate key; only real items count as
  1018. # thinking-only, empty/junk lists fall through to generic empty-turn handling.
  1019. codex_items = msg.get("codex_reasoning_items")
  1020. if drop_codex_reasoning_items and isinstance(codex_items, list):
  1021. return any(isinstance(item, dict) and item.get("type") == "reasoning" for item in codex_items)
  1022. return False
  1023. @staticmethod
  1024. def _content_has_real_payload(content: Any) -> bool:
  1025. """True when assistant ``content`` carries anything beyond (redacted) thinking blocks / whitespace."""
  1026. if isinstance(content, str):
  1027. return bool(content.strip())
  1028. if isinstance(content, list):
  1029. for block in content:
  1030. if not isinstance(block, dict):
  1031. if block: # non-empty non-dict string etc.
  1032. return True
  1033. continue
  1034. btype = block.get("type")
  1035. if btype == "text":
  1036. text = block.get("text", "")
  1037. if isinstance(text, str) and text.strip():
  1038. return True
  1039. elif btype not in {"thinking", "redacted_thinking"}:
  1040. return True # tool_use, image, document, etc. — real payload
  1041. return False
  1042. return content is not None and content != ""
  1043. _drop_thinking_only_and_merge_users = _forward_static("agent.agent_runtime_helpers", "drop_thinking_only_and_merge_users")
  1044. @staticmethod
  1045. def _cap_delegate_task_calls(tool_calls: list) -> list:
  1046. """Cap delegate_task calls in one turn at max_concurrent_children (non-delegate calls all kept);
  1047. returns the original list when nothing was truncated."""
  1048. from tools.delegate_tool import _get_max_concurrent_children
  1049. max_children = _get_max_concurrent_children()
  1050. delegate_count = sum(1 for tc in tool_calls if tc.function.name == "delegate_task")
  1051. if delegate_count <= max_children:
  1052. return tool_calls
  1053. kept_delegates, truncated = 0, []
  1054. for tc in tool_calls:
  1055. if tc.function.name == "delegate_task":
  1056. if kept_delegates >= max_children:
  1057. continue
  1058. kept_delegates += 1
  1059. truncated.append(tc)
  1060. logger.warning("Truncated %d excess delegate_task call(s) to enforce "
  1061. "max_concurrent_children=%d limit", delegate_count - max_children, max_children)
  1062. return truncated
  1063. @staticmethod
  1064. def _deduplicate_tool_calls(tool_calls: list) -> list:
  1065. """Drop duplicate (tool_name, arguments) pairs in one turn (first wins). Valid JSON arguments are
  1066. canonicalized so key order/whitespace can't evade dedup; returns the original list when nothing was removed."""
  1067. seen, unique = set(), []
  1068. for tc in tool_calls:
  1069. arguments = tc.function.arguments
  1070. try:
  1071. arguments = json.dumps(json.loads(arguments), separators=(",", ":"), sort_keys=True)
  1072. except (TypeError, ValueError):
  1073. pass
  1074. key = (tc.function.name, arguments)
  1075. if key in seen:
  1076. logger.warning("Removed duplicate tool call: %s", tc.function.name)
  1077. continue
  1078. seen.add(key)
  1079. unique.append(tc)
  1080. return unique if len(unique) < len(tool_calls) else tool_calls
  1081. # Distinct ids per assistant turn, in place (policy owner: ``message_sanitization``). Collisions get a
  1082. # deterministic ``<id>_d<n>`` suffix — never uuid4, for prompt-cache prefix stability.
  1083. _uniquify_tool_call_ids = staticmethod(_sanitize_uniquify_tool_call_ids)
  1084. _repair_tool_call = _forward("agent.agent_runtime_helpers", "repair_tool_call")
  1085. _invalidate_system_prompt = _forward("agent.system_prompt", "invalidate_system_prompt")
  1086. # Codex Responses id policy (agent.codex_responses_adapter): deterministic call ids when the API omits one
  1087. # (random UUIDs would break the provider prompt cache), split stored ids, derive valid ``fc_`` ids.
  1088. _deterministic_call_id = staticmethod(_codex_deterministic_call_id)
  1089. _split_responses_tool_id = staticmethod(_codex_split_responses_tool_id)
  1090. _derive_responses_function_call_id = staticmethod(_codex_derive_responses_function_call_id)
  1091. _interruptible_api_call = _forward("agent.chat_completion_helpers", "interruptible_api_call")
  1092. _interruptible_streaming_api_call = _forward("agent.chat_completion_helpers", "interruptible_streaming_api_call")
  1093. _try_activate_fallback = _forward("agent.chat_completion_helpers", "try_activate_fallback")
  1094. def _has_pending_fallback(self) -> bool:
  1095. """Whether a fallback provider remains (mirrors ``try_activate_fallback``'s guard) — gates the
  1096. "trying fallback..." status so we never announce one that won't be attempted.
  1097. See #17446.
  1098. """
  1099. return getattr(self, "_fallback_index", 0) < len(getattr(self, "_fallback_chain", None) or [])
  1100. _restore_primary_runtime = _forward("agent.agent_runtime_helpers", "restore_primary_runtime")
  1101. _try_recover_primary_transport = _forward("agent.agent_runtime_helpers", "try_recover_primary_transport")
  1102. _build_api_kwargs = _forward("agent.chat_completion_helpers", "build_api_kwargs")
  1103. def _set_tool_guardrail_halt(self, decision: ToolGuardrailDecision) -> None:
  1104. """Record the first guardrail decision that should stop this turn."""
  1105. if decision.should_halt and self._tool_guardrail_halt_decision is None:
  1106. self._tool_guardrail_halt_decision = decision
  1107. if decision.should_halt:
  1108. record_guardrail_decision(self, decision.action, decision.code)
  1109. def _toolguard_controlled_halt_response(self, decision: ToolGuardrailDecision) -> str:
  1110. # Shown to the user as the reply, so no decision codes; the code stays in result["guardrail"].
  1111. return (
  1112. f"I stopped retrying because I kept running {decision.tool_name or 'the same tool'} "
  1113. f"{decision.count} times without making progress. The last result above shows what "
  1114. "blocked it. Tell me how you'd like to proceed, or send `continue` and I'll try a "
  1115. "different approach."
  1116. )
  1117. def _append_guardrail_observation(self, tool_name: str, function_args: dict, function_result: str, *,
  1118. failed: bool, tool_call_id: str = "") -> str:
  1119. decision = self._tool_guardrails.after_call(tool_name, function_args, function_result, failed=failed)
  1120. # Identical-call stall guards observe the RAW result (before the per-call loop suffix) and are applied
  1121. # at result construction so tool results stay append-only / cache-safe.
  1122. stall_notice = result_stub = stall_kind = None
  1123. if self._stall_guards_enabled():
  1124. try:
  1125. observation = self._tool_guardrails.observe_call(
  1126. tool_name, function_args, function_result if isinstance(function_result, str) else None,
  1127. tool_call_id=tool_call_id, failed=failed,
  1128. )
  1129. stall_notice, result_stub, stall_kind = observation.notice, observation.stub, observation.kind
  1130. except Exception as exc:
  1131. logger.debug("stall-guard identical-call observation failed: %s", exc)
  1132. # Result-reference stubbing: a 2nd+ identical call with a byte-identical FRESH result enters
  1133. # context as a short stub. Not a cache — the tool ran; only plain-string results are stubbed.
  1134. if result_stub and isinstance(function_result, str):
  1135. function_result = result_stub
  1136. if decision.action in {"warn", "halt"}:
  1137. function_result = append_toolguard_guidance(function_result, decision)
  1138. record_guardrail_warnings(self, decision, stall_kind if stall_notice else None)
  1139. if decision.should_halt:
  1140. self._set_tool_guardrail_halt(decision)
  1141. else:
  1142. # observe_call may have raised the identical-call streak or batch-cycle halt (hard_stop_enabled, tool-agnostic).
  1143. streak_halt = self._tool_guardrails.halt_decision
  1144. if streak_halt is not None and streak_halt.code in ("identical_call_streak_halt", "identical_cycle_halt"):
  1145. function_result = append_toolguard_guidance(function_result, streak_halt)
  1146. self._set_tool_guardrail_halt(streak_halt)
  1147. if stall_notice:
  1148. function_result = (function_result or "") + "\n\n" + stall_notice
  1149. return function_result
  1150. def _stall_guards_enabled(self) -> bool:
  1151. """Config gate for the runtime anti-stall guards (agent.stall_guards)."""
  1152. return bool(getattr(self, "_stall_guards", True))
  1153. def _guardrail_block_result(self, decision: ToolGuardrailDecision) -> str:
  1154. self._set_tool_guardrail_halt(decision)
  1155. return toolguard_synthetic_result(decision)
  1156. def _execute_tool_calls(self, assistant_message, messages: list, effective_task_id: str, api_call_count: int = 0) -> None:
  1157. """Execute the assistant's tool calls and append results to ``messages``.
  1158. The segment planner splits the batch into runs of parallel-safe calls (read-only, non-overlapping file
  1159. targets, opted-in MCP) separated by sequential barriers, run in emission order.
  1160. """
  1161. tool_calls = assistant_message.tool_calls
  1162. args = (assistant_message, messages, effective_task_id, api_call_count)
  1163. self._executing_tools = True # allow _vprint during tool execution even with stream consumers
  1164. try:
  1165. with scoped_connection_surface(agent_connection_surface(self)):
  1166. if len(tool_calls) <= 1:
  1167. self._execute_tool_calls_sequential(*args)
  1168. else:
  1169. from agent.tool_dispatch_helpers import _plan_tool_batch_segments
  1170. active_env = get_active_env(effective_task_id)
  1171. exec_cwd = Path(active_env.cwd) if active_env is not None and active_env.cwd else None
  1172. segments = _plan_tool_batch_segments(tool_calls, execution_cwd=exec_cwd)
  1173. if len(segments) == 1:
  1174. run = self._execute_tool_calls_concurrent if segments[0][0] == "parallel" else self._execute_tool_calls_sequential
  1175. run(*args)
  1176. else:
  1177. from agent.tool_executor import execute_tool_calls_segmented
  1178. execute_tool_calls_segmented(self, *args, segments=segments)
  1179. finally:
  1180. self._executing_tools = False
  1181. # getattr: test stubs built without _set_defaults drive this method too
  1182. if getattr(self, "_trim_after_tool_batch", False):
  1183. # Only on normal completion: every executor frame that held a >=1 MB raw result has
  1184. # unwound and just the spilled preview lives in ``messages``. An in-flight exception
  1185. # would pin those frames via its traceback, so that path leaves the flag for the
  1186. # next completed batch (agent/tool_executor.py, #70684).
  1187. self._trim_after_tool_batch = False
  1188. from hermes_cli.mem_trim import trim_memory
  1189. trim_memory(reason="large tool result")
  1190. def _dispatch_delegate_task(self, function_args: dict) -> str:
  1191. """Single call site for delegate_task dispatch; new DELEGATE_TASK_SCHEMA fields are added only here."""
  1192. from tools.delegate_tool import _strip_model_hidden_task_fields, delegate_task as _delegate_task
  1193. # Top-level MODEL delegations run in the background (handle returned, results re-enter as messages),
  1194. # unless the session's delegate_task is the joined variant (one-shot, delegation.gateway_mode inline).
  1195. # An ORCHESTRATOR SUBAGENT (depth > 0) stays synchronous — it needs results in-turn and owns no gateway
  1196. # session. The schema-level `background` param is intentionally ignored.
  1197. return _delegate_task(
  1198. goal=function_args.get("goal"), context=function_args.get("context"),
  1199. tasks=_strip_model_hidden_task_fields(function_args.get("tasks")),
  1200. max_iterations=function_args.get("max_iterations"), role=function_args.get("role"),
  1201. background=not (getattr(self, "_delegate_depth", 0) > 0), images=function_args.get("images"),
  1202. action=function_args.get("action"),
  1203. subagent_id=function_args.get("subagent_id"), message=function_args.get("message"), parent_agent=self,
  1204. )
  1205. _invoke_tool = _forward("agent.agent_runtime_helpers", "invoke_tool")
  1206. @staticmethod
  1207. def _wrap_verbose(label: str, text: str, indent: str = " ") -> str:
  1208. """Word-wrap verbose tool output to the terminal width (each existing line separately), continuation
  1209. lines indented."""
  1210. import shutil, textwrap
  1211. wrap_width = max(40, shutil.get_terminal_size((120, 24)).columns - len(indent))
  1212. out_lines: list[str] = []
  1213. for raw_line in text.split("\n"):
  1214. if len(raw_line) <= wrap_width:
  1215. out_lines.append(raw_line)
  1216. else:
  1217. out_lines.extend(textwrap.wrap(raw_line, width=wrap_width, break_long_words=True, break_on_hyphens=False) or [raw_line])
  1218. return f"{indent}{label}" + ("\n" + indent).join(out_lines)
  1219. _execute_tool_calls_concurrent = _forward("agent.tool_executor", "execute_tool_calls_concurrent")
  1220. _execute_tool_calls_sequential = _forward("agent.tool_executor", "execute_tool_calls_sequential")
  1221. _handle_max_iterations = _forward("agent.chat_completion_helpers", "handle_max_iterations")
  1222. def _conversation_root_id(self) -> Optional[str]:
  1223. """Session-lineage ROOT id for Portal usage attribution, so one conversation keeps a single
  1224. ``conversation=`` tag across compression rotation; subagents resolve via ``_parent_session_id``."""
  1225. cached = getattr(self, "_cached_conversation_root", None)
  1226. if cached:
  1227. return str(cached)
  1228. sid = getattr(self, "session_id", None)
  1229. if not sid:
  1230. return None
  1231. # Subagents may not have a DB row yet on their first turn; walking from the parent id still lands
  1232. # on the right root.
  1233. start = getattr(self, "_parent_session_id", None) or sid
  1234. db = getattr(self, "_session_db", None)
  1235. if db is None:
  1236. return start
  1237. try:
  1238. return db.get_conversation_root(start) or start
  1239. except Exception:
  1240. logger.debug("Conversation root lineage walk failed", exc_info=True)
  1241. return start
  1242. _BASIC_TOOLSETS = {"web", "terminal", "vision", "creative", "reasoning"}
  1243. _COMPOSITE_TOOLSETS = {"research", "development", "analysis", "content_creation", "full_stack"}
  1244. _LIST_TOOLS_USAGE = """
  1245. 💡 Usage Examples:
  1246. # Use predefined toolsets
  1247. python run_agent.py --enabled_toolsets=research --query='search for Python news'
  1248. python run_agent.py --enabled_toolsets=development --query='debug this code'
  1249. python run_agent.py --enabled_toolsets=safe --query='analyze without terminal'
  1250. # Combine multiple toolsets
  1251. python run_agent.py --enabled_toolsets=web,vision --query='analyze website'
  1252. # Disable toolsets
  1253. python run_agent.py --disabled_toolsets=terminal --query='no command execution'
  1254. # Run with trajectory saving enabled
  1255. python run_agent.py --save_trajectories --query='your question here'"""
  1256. def _print_tool_listing() -> None:
  1257. """``--list_tools``: print toolsets (basic / composite / scenario / legacy), every tool, and usage examples."""
  1258. from model_tools import get_all_tool_names, get_available_toolsets
  1259. from toolsets import get_all_toolsets, get_toolset_info
  1260. print("📋 Available Tools & Toolsets:")
  1261. print("-" * 50)
  1262. print("\n🎯 Predefined Toolsets (New System):")
  1263. print("-" * 40)
  1264. basic_toolsets, composite_toolsets, scenario_toolsets = [], [], []
  1265. for name in get_all_toolsets():
  1266. info = get_toolset_info(name)
  1267. if info:
  1268. bucket = basic_toolsets if name in _BASIC_TOOLSETS else composite_toolsets if name in _COMPOSITE_TOOLSETS else scenario_toolsets
  1269. bucket.append((name, info))
  1270. print("\n📌 Basic Toolsets:")
  1271. for name, info in basic_toolsets:
  1272. print(f" • {name:15} - {info['description']}")
  1273. print(f" Tools: {', '.join(info['resolved_tools']) if info['resolved_tools'] else 'none'}")
  1274. print("\n📂 Composite Toolsets (built from other toolsets):")
  1275. for name, info in composite_toolsets:
  1276. print(f" • {name:15} - {info['description']}")
  1277. print(f" Includes: {', '.join(info['includes']) if info['includes'] else 'none'}")
  1278. print(f" Total tools: {info['tool_count']}")
  1279. print("\n🎭 Scenario-Specific Toolsets:")
  1280. for name, info in scenario_toolsets:
  1281. print(f" • {name:20} - {info['description']}")
  1282. print(f" Total tools: {info['tool_count']}")
  1283. print("\n📦 Legacy Toolsets (for backward compatibility):")
  1284. for name, info in get_available_toolsets().items():
  1285. print(f" {'✅' if info['available'] else '❌'} {name}: {info['description']}")
  1286. if not info["available"]:
  1287. print(f" Requirements: {', '.join(info['requirements'])}")
  1288. all_tools = get_all_tool_names()
  1289. print(f"\n🔧 Individual Tools ({len(all_tools)} available):")
  1290. for tool_name in sorted(all_tools):
  1291. print(f" 📌 {tool_name} (from {get_toolset_for_tool(tool_name)})")
  1292. print(_LIST_TOOLS_USAGE)
  1293. def _parse_toolset_arg(raw: Optional[str], label: str) -> Optional[list[str]]:
  1294. """Comma-separated toolset CLI arg → list (echoed), or None when absent."""
  1295. if not raw:
  1296. return None
  1297. names = [t.strip() for t in raw.split(",")]
  1298. print(f"{label}: {names}")
  1299. return names
  1300. def _save_sample_trajectory(agent: AIAgent, result: dict, user_query: str, model: str) -> None:
  1301. """``--save_sample``: write one trajectory (same format as batch_runner) to a UUID-named JSON file."""
  1302. sample_filename = f"sample_{str(uuid.uuid4())[:8]}.json"
  1303. entry = {
  1304. "conversations": agent._convert_to_trajectory_format(result['messages'], user_query, result['completed']),
  1305. "timestamp": datetime.now().isoformat(), "model": model, "completed": result['completed'], "query": user_query,
  1306. }
  1307. try:
  1308. with open(sample_filename, "w", encoding="utf-8") as f:
  1309. f.write(json.dumps(entry, ensure_ascii=False, indent=2))
  1310. print(f"\n💾 Sample trajectory saved to: {sample_filename}")
  1311. except Exception as e:
  1312. print(f"\n⚠️ Failed to save sample: {e}")
  1313. def main(
  1314. query: str | None = None, model: str = "", api_key: str | None = None, base_url: str = "", max_turns: int = 10,
  1315. enabled_toolsets: str | None = None, disabled_toolsets: str | None = None, list_tools: bool = False,
  1316. save_trajectories: bool = False, save_sample: bool = False, verbose: bool = False, log_prefix_chars: int = 20,
  1317. ):
  1318. """
  1319. Main function for running the agent directly.
  1320. Args:
  1321. query (str): Natural language query for the agent. Defaults to Python 3.13 example.
  1322. model (str): Model name to use (OpenRouter format: provider/model). Defaults to anthropic/claude-
  1323. sonnet-4.6.
  1324. api_key (str): API key for authentication. Uses OPENROUTER_API_KEY env var if not provided.
  1325. base_url (str): Base URL for the model API. Defaults to https://openrouter.ai/api/v1
  1326. max_turns (int): Maximum number of API call iterations. Defaults to 10.
  1327. enabled_toolsets (str): Comma-separated list of toolsets to enable. Supports predefined
  1328. toolsets (e.g., "research", "development", "safe").
  1329. Multiple toolsets can be combined: "web,vision"
  1330. disabled_toolsets (str): Comma-separated list of toolsets to disable (e.g., "terminal")
  1331. list_tools (bool): Just list available tools and exit
  1332. save_trajectories (bool): Save conversation trajectories to JSONL files (appends to
  1333. trajectory_samples.jsonl). Defaults to False.
  1334. save_sample (bool): Save a single trajectory sample to a UUID-named JSONL file for inspection.
  1335. Defaults to False.
  1336. verbose (bool): Enable verbose logging for debugging. Defaults to False.
  1337. log_prefix_chars (int): Number of characters to show in log previews for tool calls/responses.
  1338. Defaults to 20.
  1339. Toolset Examples:
  1340. - "research": Web search, extract, crawl + vision tools
  1341. """
  1342. print("🤖 AI Agent with Tool Calling")
  1343. print("=" * 50)
  1344. if list_tools:
  1345. return _print_tool_listing()
  1346. # One TLS authority: trust the OS store before any outbound call (bare
  1347. # requests/urllib included) resolves a CA bundle — see agent/ssl_verify.py.
  1348. # The `hermes` CLI does this in hermes_cli.main; this console script
  1349. # bypasses it. Never raises.
  1350. from agent.ssl_verify import install_truststore
  1351. install_truststore()
  1352. enabled_toolsets_list = _parse_toolset_arg(enabled_toolsets, "🎯 Enabled toolsets")
  1353. disabled_toolsets_list = _parse_toolset_arg(disabled_toolsets, "🚫 Disabled toolsets")
  1354. if save_trajectories:
  1355. print("💾 Trajectory saving: ENABLED")
  1356. print(" - Successful conversations → trajectory_samples.jsonl")
  1357. print(" - Failed conversations → failed_trajectories.jsonl")
  1358. try:
  1359. agent = AIAgent(
  1360. base_url=base_url, model=model, api_key=api_key, max_iterations=max_turns,
  1361. enabled_toolsets=enabled_toolsets_list, disabled_toolsets=disabled_toolsets_list,
  1362. save_trajectories=save_trajectories, verbose_logging=verbose, log_prefix_chars=log_prefix_chars,
  1363. )
  1364. except RuntimeError as e:
  1365. print(f"❌ Failed to initialize agent: {e}")
  1366. return
  1367. user_query = query if query is not None else ("Tell me about the latest developments in Python 3.13 and what new features "
  1368. "developers should know about. Please search for current information and try it out.")
  1369. print(f"\n📝 User Query: {user_query}")
  1370. print("\n" + "=" * 50)
  1371. result = agent.run_conversation(user_query)
  1372. print("\n" + "=" * 50 + "\n📋 CONVERSATION SUMMARY\n" + "=" * 50)
  1373. print(f"✅ Completed: {result['completed']}\n📞 API Calls: {result['api_calls']}\n💬 Messages: {len(result['messages'])}")
  1374. if result['final_response']:
  1375. print("\n🎯 FINAL RESPONSE:\n" + "-" * 30 + "\n" + result['final_response'])
  1376. if save_sample:
  1377. _save_sample_trajectory(agent, result, user_query, model)
  1378. print("\n👋 Agent execution completed!")
  1379. if __name__ == "__main__":
  1380. from agent.legacy_cli import main as _legacy_cli_main
  1381. raise SystemExit(_legacy_cli_main(run=main))