agent_init.py 118 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894189518961897189818991900190119021903190419051906190719081909191019111912191319141915191619171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954195519561957195819591960196119621963196419651966196719681969197019711972197319741975197619771978197919801981198219831984198519861987198819891990199119921993199419951996199719981999200020012002200320042005200620072008200920102011201220132014201520162017201820192020202120222023202420252026202720282029203020312032203320342035203620372038203920402041204220432044204520462047204820492050205120522053205420552056205720582059206020612062206320642065206620672068206920702071207220732074207520762077207820792080208120822083208420852086208720882089209020912092209320942095209620972098209921002101210221032104210521062107210821092110211121122113211421152116211721182119212021212122212321242125212621272128212921302131213221332134213521362137213821392140214121422143214421452146214721482149215021512152215321542155215621572158215921602161216221632164216521662167216821692170217121722173217421752176217721782179218021812182218321842185218621872188218921902191219221932194219521962197219821992200220122022203220422052206220722082209221022112212221322142215221622172218221922202221222222232224222522262227222822292230223122322233223422352236223722382239224022412242224322442245224622472248224922502251225222532254225522562257225822592260226122622263226422652266226722682269227022712272227322742275
  1. """Implementation of :meth:`AIAgent.__init__` as ``init_agent(agent, ...)``.
  2. ``init_agent`` is a thin, ordered orchestrator over ``_init_*`` / ``_build_*`` phase
  3. helpers (routing → callbacks → client → tools → session → config sections → compression →
  4. context engine). Phase ORDER is load-bearing: later phases read attributes earlier ones set.
  5. Symbols that tests patch on ``run_agent.*`` (``OpenAI``, ``get_tool_definitions``,
  6. ``logger``, …) are resolved through :func:`_ra` so the patch contract is preserved.
  7. """
  8. from __future__ import annotations
  9. import logging
  10. import os
  11. import re
  12. import sys
  13. import threading
  14. import time
  15. from collections import deque
  16. from contextlib import suppress
  17. from datetime import datetime
  18. from types import SimpleNamespace
  19. from typing import Any, Callable, Dict, List, Optional
  20. from urllib.parse import parse_qs, urlparse, urlunparse
  21. from agent.context_compressor import ContextCompressor
  22. from agent.agent_init_fallback import _fallback_entries, _init_fallback_chain, recompute_init_fallback_api_mode
  23. from agent.agent_init_params import _CALLBACK_PARAMS, _GATEWAY_IDENTITY_PARAMS, _PASSTHROUGH_PARAMS
  24. from agent.agent_runtime_helpers import _ra
  25. from agent.iteration_budget import IterationBudget, normalize_budget_warning_ratio
  26. from agent.memory_context import StreamingContextScrubber
  27. from agent.memory_provider import is_core_memory_provider
  28. from agent.session_activity import ActivityProvenance
  29. from agent.model_metadata import (
  30. MINIMUM_CONTEXT_LENGTH, fetch_model_metadata, is_local_endpoint
  31. )
  32. from agent.agent_init_ollama import _clamp_compressor_to_ollama_num_ctx, _configure_ollama_num_ctx
  33. from agent.agent_init_compression_notice import _emit_compression_summary
  34. from agent.primary_runtime_snapshot import _snapshot_primary_runtime
  35. from agent.process_bootstrap import _install_safe_stdio
  36. from agent.subdirectory_hints import SubdirectoryHintTracker
  37. from agent.agent_init_memory_provider import resolve_memory_provider
  38. from agent.think_scrubber import StreamingThinkScrubber
  39. from agent.tool_guardrails import (
  40. ToolCallGuardrailConfig, ToolCallGuardrailController
  41. )
  42. from hermes_cli.config import DEFAULT_CONFIG, cfg_get
  43. from hermes_cli.route_identity import normalize_route_base_url
  44. from hermes_cli.timeouts import get_provider_request_timeout
  45. from hermes_constants import get_hermes_home
  46. from hermes_state_ids import new_session_id
  47. from utils import base_url_host_matches, is_truthy_value
  48. # Same logger name as run_agent so caplog/patches on "run_agent" see our records.
  49. logger = logging.getLogger("run_agent")
  50. def _provider_default_routes(provider: str) -> set[str]:
  51. """Return known exact default routes for a canonical provider id."""
  52. routes: set[str] = set()
  53. def add(value):
  54. route = normalize_route_base_url(value)
  55. if route:
  56. routes.add(route)
  57. with suppress(Exception):
  58. from hermes_cli.providers import HERMES_OVERLAYS, get_provider
  59. overlay = HERMES_OVERLAYS.get(provider)
  60. provider_def = get_provider(provider, allow_network=False)
  61. add(getattr(overlay, "base_url_override", ""))
  62. add(getattr(provider_def, "base_url", ""))
  63. with suppress(Exception):
  64. from providers import get_provider_profile
  65. add(getattr(get_provider_profile(provider), "base_url", ""))
  66. with suppress(Exception):
  67. from hermes_cli.auth import PROVIDER_REGISTRY
  68. from hermes_cli.models import normalize_provider as normalize_model_provider
  69. from hermes_cli.providers import normalize_provider as normalize_registry_provider
  70. for provider_id, config in PROVIDER_REGISTRY.items():
  71. if normalize_registry_provider(normalize_model_provider(provider_id)) == provider:
  72. add(getattr(config, "inference_base_url", ""))
  73. if provider == "gemini":
  74. routes.update(f"{route.rstrip('/')}/openai" for route in list(routes))
  75. return routes
  76. def _context_route_mismatch(
  77. configured_base_url: Any, active_base_url: Any, configured_provider: Any, active_provider: Any,
  78. *, already_normalized: bool = False,
  79. ) -> bool:
  80. """Return whether a context pin's configured route differs from runtime."""
  81. _norm = (lambda v: str(v or "")) if already_normalized else normalize_route_base_url
  82. configured_route, active_route = _norm(configured_base_url), _norm(active_base_url)
  83. if configured_route:
  84. return configured_route != active_route
  85. configured_provider = str(configured_provider or "").strip()
  86. active_provider = str(active_provider or "").strip()
  87. if not configured_provider:
  88. return False
  89. try:
  90. from hermes_cli.models import normalize_provider as normalize_model_provider
  91. configured_provider = normalize_model_provider(configured_provider)
  92. active_provider = normalize_model_provider(active_provider)
  93. except Exception:
  94. configured_provider = configured_provider.lower()
  95. active_provider = active_provider.lower()
  96. with suppress(Exception):
  97. from hermes_cli.providers import normalize_provider as normalize_registry_provider
  98. configured_provider = normalize_registry_provider(configured_provider)
  99. active_provider = normalize_registry_provider(active_provider)
  100. if active_route:
  101. configured_routes = _provider_default_routes(configured_provider)
  102. if configured_routes:
  103. return active_route not in configured_routes
  104. # Named/custom providers have no catalog default routes: an empty configured URL
  105. # with a matching provider identity is the same route (gateway display paths
  106. # compare the raw empty model.base_url and must not drop model.context_length).
  107. return not (active_provider and configured_provider == active_provider)
  108. return bool(
  109. configured_provider and active_provider and configured_provider != active_provider
  110. )
  111. def _normalize_custom_provider_name(value: Any) -> str:
  112. """Mirror runtime normalization for a requested custom-provider identity."""
  113. return str(value or "").strip().lower().replace(" ", "-")
  114. def _custom_provider_runtime_ids(value: Any) -> set[str]:
  115. """Return raw/menu identities that runtime accepts for a configured name."""
  116. normalized = _normalize_custom_provider_name(value)
  117. if not normalized:
  118. return set()
  119. return {normalized, f"custom:{normalized}"}
  120. def _resolve_compression_threshold(
  121. global_threshold: float, model_cthresh: Optional[float], *, model: Optional[str] = None,
  122. is_codex_autoraise: bool,
  123. ) -> tuple[float, Optional[dict[str, Any]]]:
  124. """Global compaction threshold merged with a per-model override.
  125. Returns ``(threshold, autoraise_notice)``; the notice is set only when a Codex autoraise
  126. actually RAISES the threshold — it never lowers a higher user value (the user deliberately
  127. keeps more raw context). Other overrides (Arcee Trinity) stay unconditional.
  128. """
  129. if model_cthresh is None:
  130. return global_threshold, None
  131. if is_codex_autoraise:
  132. if model_cthresh <= global_threshold + 1e-9:
  133. return global_threshold, None
  134. return model_cthresh, {"model": model, "from": global_threshold, "to": model_cthresh}
  135. return model_cthresh, None
  136. def _normalized_custom_base_url(value: Any) -> str:
  137. if not isinstance(value, str):
  138. return ""
  139. return value.strip().rstrip("/")
  140. def _custom_provider_model_matches(agent_model: str, entry: dict[str, Any]) -> bool:
  141. agent_model_norm = str(agent_model or "").strip().lower()
  142. # Multi-model entries (`providers.<name>.models` mapping / legacy `models:` list):
  143. # matching ANY catalog entry counts, else a provider whose `model` differs from the
  144. # session model drops its extra_body (e.g. OpenAI service_tier) → wrong billing tier.
  145. models = entry.get("models")
  146. catalog = [str(m).strip().lower() for m in models] if isinstance(models, (dict, list, tuple)) else []
  147. if catalog and agent_model_norm in catalog:
  148. return True
  149. provider_model = str(entry.get("model", "") or "").strip().lower()
  150. return (not provider_model and not catalog) or provider_model == agent_model_norm
  151. def _custom_provider_extra_body_for_agent(
  152. *, provider: str, model: str, base_url: str, custom_providers: list[dict[str, Any]]
  153. ) -> Optional[dict[str, Any]]:
  154. provider_norm = (provider or "").strip().lower()
  155. if provider_norm != "custom" and not provider_norm.startswith("custom:"):
  156. return None
  157. provider_key_filter = provider_norm.partition(":")[2].strip()
  158. target_url = _normalized_custom_base_url(base_url)
  159. if not target_url:
  160. return None
  161. fallback: Optional[dict[str, Any]] = None
  162. for entry in custom_providers or []:
  163. if not isinstance(entry, dict):
  164. continue
  165. entry_keys = {
  166. str(entry.get("provider_key", "") or "").strip().lower(),
  167. str(entry.get("name", "") or "").strip().lower(),
  168. }
  169. if provider_key_filter and provider_key_filter not in entry_keys:
  170. continue
  171. if _normalized_custom_base_url(entry.get("base_url")) != target_url:
  172. continue
  173. extra_body = entry.get("extra_body")
  174. if not isinstance(extra_body, dict) or not extra_body:
  175. continue
  176. if str(entry.get("model", "") or "").strip():
  177. if _custom_provider_model_matches(model, entry):
  178. return dict(extra_body)
  179. elif fallback is None:
  180. fallback = dict(extra_body)
  181. return fallback
  182. def _merge_custom_provider_extra_body(agent, custom_providers: list[dict[str, Any]]) -> None:
  183. extra_body = _custom_provider_extra_body_for_agent(
  184. provider=agent.provider, model=agent.model, base_url=agent.base_url,
  185. custom_providers=custom_providers,
  186. )
  187. if not extra_body:
  188. return
  189. overrides = dict(getattr(agent, "request_overrides", {}) or {})
  190. merged_extra_body = dict(extra_body)
  191. existing_extra_body = overrides.get("extra_body")
  192. if isinstance(existing_extra_body, dict):
  193. merged_extra_body.update(existing_extra_body)
  194. overrides["extra_body"] = merged_extra_body
  195. agent.request_overrides = overrides
  196. def _normalize_run_budget_seconds(value) -> Optional[float]:
  197. """Positive float or None (feature off). ``bool`` rejected: YAML ``true`` → 1s budget."""
  198. if value is None or isinstance(value, bool):
  199. return None
  200. try:
  201. seconds = float(value)
  202. except (TypeError, ValueError):
  203. return None
  204. return seconds if seconds > 0 else None # NaN compares False → None
  205. def _refuse_checkpoint_required_on_codex_app_server(
  206. checkpoint_required: bool, api_mode: Optional[str]
  207. ) -> None:
  208. """Fail closed at init: the codex app-server compacts its own thread without a truthful
  209. pre-compaction boundary (default "native" mode), so a required checkpoint can't be
  210. guaranteed — the compress_context() guard alone cannot cover native turns."""
  211. if checkpoint_required and api_mode == "codex_app_server":
  212. raise RuntimeError(
  213. "BLOCKED_MISSING_PREREQUISITE: compression.checkpoint_required "
  214. "is incompatible with the codex_app_server API mode: the codex "
  215. "agent compacts its own thread without a truthful pre-compaction "
  216. "transcript boundary, so a required pre-compress checkpoint "
  217. "cannot be guaranteed. Disable compression.checkpoint_required "
  218. "or use a non-app-server API mode."
  219. )
  220. def _parse_config_int(raw: Any, default: int) -> int:
  221. """Strict int coercion: rejects bool (YAML ``true`` → 1) and fractional floats."""
  222. if isinstance(raw, bool):
  223. return default
  224. if isinstance(raw, int):
  225. return raw
  226. if isinstance(raw, float):
  227. return int(raw) if raw.is_integer() else default
  228. try:
  229. return int(str(raw).strip())
  230. except (TypeError, ValueError):
  231. return default
  232. def _cfg_flag(cfg: dict[str, Any], key: str, default: bool) -> bool:
  233. """Legacy string-set truthiness used by the ``compression`` section."""
  234. return str(cfg.get(key, default)).lower() in {"true", "1", "yes"}
  235. def _cfg_dict(cfg: dict[str, Any], key: str) -> dict[str, Any]:
  236. """``cfg[key]`` if it is a mapping, else ``{}`` (malformed sections are ignored)."""
  237. section = cfg.get(key, {})
  238. return section if isinstance(section, dict) else {}
  239. class CompressionSettings(SimpleNamespace):
  240. """Parsed ``compression`` config section (see ``_parse_compression_config``)."""
  241. _EXPLICIT_API_MODES = {
  242. "chat_completions", "codex_responses", "anthropic_messages", "bedrock_converse",
  243. "codex_app_server",
  244. }
  245. def _resolve_api_mode(agent, api_mode, provider_name, base_url):
  246. """Set ``agent.api_mode`` (and provider rewrites) — ordered ladder, first match wins."""
  247. from hermes_cli.providers import is_actual_route
  248. from agent.transports import registered_api_modes
  249. host, url = agent._base_url_hostname, agent._base_url_lower
  250. if is_actual_route(agent.provider, base_url):
  251. agent.api_mode = "chat_completions"
  252. elif api_mode in _EXPLICIT_API_MODES or (api_mode and api_mode in registered_api_modes()):
  253. # A provider plugin's own dialect (``register_transport(api_mode, cls)``) is as explicit
  254. # as the in-tree modes; rewriting it to chat_completions silently dropped its transport.
  255. agent.api_mode = api_mode
  256. elif agent.provider in {"openai-codex", "xai", "xai-oauth"}:
  257. agent.api_mode = "codex_responses"
  258. elif provider_name is None and host == "chatgpt.com" and "/backend-api/codex" in url:
  259. agent.api_mode = "codex_responses"
  260. agent.provider = "openai-codex"
  261. elif provider_name is None and host == "api.x.ai":
  262. agent.api_mode = "codex_responses"
  263. agent.provider = "xai"
  264. elif agent.provider == "anthropic" or (provider_name is None and host == "api.anthropic.com"):
  265. agent.api_mode = "anthropic_messages"
  266. agent.provider = "anthropic"
  267. elif url.rstrip("/").endswith("/anthropic"):
  268. # Third-party Anthropic-compatible endpoints (MiniMax, DashScope) end in /anthropic.
  269. agent.api_mode = "anthropic_messages"
  270. elif agent.provider == "bedrock" or (
  271. host.startswith("bedrock-runtime.") and base_url_host_matches(url, "amazonaws.com")
  272. ):
  273. agent.api_mode = "bedrock_converse"
  274. elif agent.provider in {"nous", "nous-portal", "nousresearch"}:
  275. # Portal is dual-wire (anthropic/* → Messages, else chat_completions); covers direct
  276. # AIAgent construction without a resolved runtime.
  277. from hermes_cli.providers import nous_api_mode
  278. agent.api_mode = nous_api_mode(agent.model)
  279. else:
  280. # Host-mandated wire check — LAST, so the provider-slug rewrites above always win.
  281. # Covers api.meta.ai → codex_responses (prompt caching: 0% on chat vs 93-99%).
  282. # URL-driven, not provider-name-driven: `providers.meta` may point anywhere.
  283. try:
  284. # Note: provider="meta" without an api.meta.ai base_url (or with a non-api.meta.ai base_url)
  285. # intentionally falls through to chat_completions here. The wire protocol for Meta is URL-driven
  286. # BY DESIGN, not provider-name-driven, because user config `providers.meta` may point at any
  287. # OpenAI-compatible endpoint, and forcing `codex_responses` on the provider name alone would
  288. # break custom endpoints named "meta" that do not host the Responses API. See #63425.
  289. from hermes_cli.providers import host_mandated_api_mode as _host_mandated_api_mode
  290. _mandated = _host_mandated_api_mode(base_url or "")
  291. except Exception:
  292. _mandated = None
  293. agent.api_mode = _mandated if _mandated is not None else "chat_completions"
  294. def _finalize_routing(agent, api_mode, credential_pool):
  295. from hermes_cli.providers import is_actual_route
  296. # Credential-pool validation runs AFTER provider auto-detection so a pool scoped to
  297. # "anthropic" isn't rejected for provider=None + anthropic.com URL.
  298. # Regression from #63048 which placed this check before the URL-based auto-detection block above (fixed
  299. # #63425).
  300. if credential_pool is not None:
  301. try:
  302. from agent.credential_pool import credential_pool_matches_provider
  303. if not credential_pool_matches_provider(
  304. credential_pool, agent.provider, base_url=agent.base_url,
  305. ):
  306. agent._credential_pool = None
  307. except Exception:
  308. agent._credential_pool = None
  309. # Warm the transport cache so import errors surface at init (non-fatal: some modes lack one).
  310. with suppress(Exception):
  311. agent._get_transport()
  312. # The Nous agent key lives ~1 h. Without the proactive refresher every agent in the process
  313. # discovers expiry reactively, on its own next request, all in the same minute: with 200
  314. # in-process subagents that was a 401 storm each hour (620 in one run) and the credential
  315. # pool benched the provider for all of them. The gateway and web server start this thread
  316. # at boot; the CLI process (and everything spawned inside it) never did. Idempotent,
  317. # process-wide, daemon.
  318. if agent.provider == "nous":
  319. with suppress(Exception):
  320. from hermes_cli.nous_auth_keepalive import start_nous_auth_keepalive
  321. start_nous_auth_keepalive()
  322. with suppress(Exception):
  323. from hermes_cli.model_normalize import (
  324. _AGGREGATOR_PROVIDERS, normalize_model_for_provider
  325. )
  326. if agent.provider not in _AGGREGATOR_PROVIDERS:
  327. agent.model = normalize_model_for_provider(agent.model, agent.provider)
  328. # Nous model policy follows the ROUTE (the welcome host serves one model); a credential-pool
  329. # swap can change the route later, so ``_swap_credential`` applies the same helper again.
  330. from hermes_cli.anon_auth import pin_model_for_route
  331. agent.model = pin_model_for_route(agent.provider, agent.base_url, agent.model)
  332. # Auto-upgrade to Responses for GPT-5.x-style models and direct OpenAI URLs, unless
  333. # api_mode was explicit, the runtime is ACP (`acp://` clients route themselves, no
  334. # Responses surface) or Azure OpenAI (gpt-5.x on /chat/completions only). Provider
  335. # exceptions live in _provider_model_requires_responses_api.
  336. from hermes_cli.runtime_provider_backends import _is_external_process_provider
  337. _base_lower = str(agent.base_url or "").lower()
  338. if (
  339. # GPT-5.x models usually require the Responses API path; a profile's api_mode_for_model may keep one on
  340. # chat completions. ACP runtimes are excluded: an ACP client routes itself (no Responses surface). Keyed on the
  341. # `acp://` scheme AND the profile's external_process auth_type (an `<X>_ACP_BASE_URL` override
  342. # can carry an https marker), not one vendor, so every ACP client is covered. When api_mode was explicitly
  343. # provided, respect it — the user knows what their endpoint supports (#10473). Exception: Azure
  344. # OpenAI serves gpt-5.x on /chat/completions and does NOT support the Responses API — skip the
  345. # upgrade for Azure (openai.azure.com), even though it looks OpenAI-compatible.
  346. api_mode is None
  347. and agent.api_mode == "chat_completions"
  348. and not is_actual_route(agent.provider, agent.base_url)
  349. and not _base_lower.startswith(("acp://", "acp+tcp://"))
  350. and not _is_external_process_provider(agent.provider)
  351. and not agent._is_azure_openai_url()
  352. and (
  353. agent._is_direct_openai_url()
  354. or agent._provider_model_requires_responses_api(agent.model, provider=agent.provider)
  355. )
  356. ):
  357. agent.api_mode = "codex_responses"
  358. # Invalidate the eager-warmed transport cache — api_mode changed after the warm.
  359. if hasattr(agent, "_transport_cache"):
  360. agent._transport_cache.clear()
  361. # Pre-warm the OpenRouter metadata cache (1h TTL) off-thread so the first pricing estimate
  362. # doesn't block. Process-level Event guard: an unguarded spawn leaks a thread per message.
  363. if (agent.provider == "openrouter" or agent._is_openrouter_url()) and \
  364. not _ra()._openrouter_prewarm_done.is_set():
  365. _ra()._openrouter_prewarm_done.set()
  366. threading.Thread(
  367. target=fetch_model_metadata, daemon=True, name="openrouter-prewarm",
  368. ).start()
  369. def _set_defaults(agent, table: dict[str, Any]) -> None:
  370. """Assign each ``name -> value`` on ``agent``; callables are factories (fresh per agent)."""
  371. for name, value in table.items():
  372. setattr(agent, name, value() if callable(value) else value)
  373. # Control-flow state (interrupts / steer / redirect / delegation / background review).
  374. _CONTROL_STATE: dict[str, Any] = {
  375. "_executing_tools": False, # lets _vprint print while tools run with stream consumers on
  376. "_trim_after_tool_batch": False, # a >=1 MB tool result was committed; trim once the batch unwinds
  377. "_tool_guardrails": ToolCallGuardrailController,
  378. "_tool_guardrail_halt_decision": None,
  379. # Interrupts. Hard cancellation is separate from redirect/message state; the Event makes
  380. # the cause atomic for auxiliary stream pollers.
  381. "_interrupt_requested": False,
  382. "_interrupt_message": None, # optional message that triggered the interrupt
  383. "_hard_interrupt_requested": threading.Event,
  384. "_execution_thread_id": None, # set at run_conversation() start
  385. "_interrupt_thread_signal_pending": False,
  386. "_client_lock": threading.RLock,
  387. "_model_request_active": threading.Event,
  388. "_supports_active_turn_redirect": True,
  389. # /steer: the drain hook appends the note to the last tool result after the current
  390. # batch — no interrupt, no new user turn (role alternation preserved).
  391. "_pending_steer": None,
  392. "_pending_steer_lock": threading.Lock,
  393. # Active-turn redirect: keep the valid turn prefix, cancel only the in-flight request,
  394. # rebuild the tail with the correction. Drained at a role-safe boundary.
  395. "_pending_redirect": None,
  396. "_pending_redirect_lock": threading.Lock,
  397. # Concurrent-tool worker tids: `_set_interrupt` on `_execution_thread_id` alone doesn't
  398. # reach ThreadPoolExecutor workers, so interrupt()/clear_interrupt() fan out to these.
  399. "_tool_worker_threads": set,
  400. "_tool_worker_threads_lock": threading.Lock,
  401. # Subagent delegation: depth (0 = top-level) and running children (interrupt propagation).
  402. "_delegate_depth": 0,
  403. "_active_children": list,
  404. "_active_children_lock": threading.Lock,
  405. # Background review (agent/background_review.py): the run is installed before the worker
  406. # starts and fences its first provider phase; the agent pointer enables interrupt fan-out.
  407. "_background_review_agent": None,
  408. "_background_review_run": None,
  409. "_background_review_lock": threading.Lock,
  410. }
  411. # Per-turn bookkeeping: budgets, activity tracking, rate-limit/credits telemetry.
  412. _TURN_STATE: dict[str, Any] = {
  413. # Intermediate pressure warnings made models give up early; ordinary conversations
  414. # remain opt-in. Dispatcher workers receive a bounded completion checkpoint.
  415. "_iteration_budget_warning_injected": False,
  416. "_budget_exhausted_injected": False,
  417. "_budget_grace_call": False,
  418. "_run_budget_started_at": None, # set by turn_context.prepare_turn when a budget is active
  419. "_run_budget_wrapup_injected": False, # one-shot latch for the 80% wrap-up notice
  420. # Activity tracking (API call / tool / stream chunk) for the gateway timeout handler and
  421. # "still working" notifications. Named provenances are stamped only by compression writers.
  422. "_last_activity_ts": lambda: time.time(),
  423. "_last_activity_desc": "initializing",
  424. "_last_activity_provenance": ActivityProvenance.UNKNOWN,
  425. "_session_activity_last_persist_mono": 0.0, # rate-limits durable SessionDB stamps
  426. "_current_tool": None,
  427. "_api_call_count": 0,
  428. # Opt-out for the between-turns MCP refresh; set on forks that need byte-identical tools[].
  429. "_skip_mcp_refresh": False,
  430. # Registry generation of the tool snapshot (set in _load_tools): a late refresh rejects
  431. # a stale rebuild instead of clobbering a newer one.
  432. "_tool_snapshot_generation": 0,
  433. "_rate_limit_state": None, # from x-ratelimit-* headers; read by /usage
  434. # Credits tracking (dev-only, HERMES_DEV_CREDITS) from x-nous-credits-* headers; session
  435. # start is latched on the first header so cumulative spend can be reported.
  436. "_credits_state": None,
  437. "_credits_session_start_micros": None,
  438. "_or_cache_hits": 0, # X-OpenRouter-Cache-Status: HIT count
  439. }
  440. # Session persistence state.
  441. _SESSION_STATE: dict[str, Any] = {
  442. "_session_messages": list,
  443. # Responses encrypted-reasoning replay. The first ``invalid_encrypted_content`` rejection only
  444. # strips the stale blobs (a rotated sealing key); a second one means the route cannot round-trip
  445. # its own fresh blobs, so replay is disabled for the session (stateless continuity).
  446. "_codex_reasoning_replay_enabled": True,
  447. "_codex_reasoning_replay_rejected": False,
  448. "_memory_write_origin": "assistant_tool",
  449. "_memory_write_context": "foreground",
  450. # Cached system prompt (built once, rebuilt on compression) + its cross-session-stable
  451. # prefix, kept separately only to place an early cache marker.
  452. "_cached_system_prompt": None,
  453. "_cached_system_prompt_static": None,
  454. # skills.auto_load rendered ONCE per agent: every rebuild (model switch, compression,
  455. # static-prefix restoration) reuses these exact bytes instead of re-reading config/skills.
  456. "_auto_load_skills_resolved": False,
  457. "_auto_load_skills_result": ("", [], []),
  458. # ``(cwd, workspace_block)`` pinned on the first build: the git/workspace snapshot is
  459. # probed once per session and replayed on every rebuild, so a moving repo can't push the
  460. # prefix-cache divergence point ahead of the volatile band at a compaction boundary.
  461. "_frozen_workspace_snapshot": None,
  462. # Whether close() also closes _session_db. False: a caller-supplied handle is usually the
  463. # SHARED launch handle; callers handing over a DEDICATED handle set True.
  464. "_owns_session_db": False,
  465. # Close flush and turn-start flush can overlap; the durable marker lives on each message
  466. # dict, so its test-and-append is serialized per agent.
  467. "_session_persist_lock": threading.RLock,
  468. # CLI's just-accepted user dict, reused by turn setup so its durable marker survives a
  469. # close-persistence race.
  470. "_pending_cli_user_message": None,
  471. "_last_flushed_db_idx": 0, # DB-write cursor (prevents duplicate writes)
  472. "_session_db_created": False, # DB row deferred to run_conversation()
  473. # False on helper agents (compression / hygiene / review forks) that hand the session to
  474. # a continuation row that must stay open.
  475. "_end_session_on_close": True,
  476. # True on the background review fork: never persist or publish session lifecycle hooks,
  477. # so its harness turn can't hijack or appear under the live session.
  478. "_persist_disabled": False,
  479. }
  480. # Streaming delivery state.
  481. _STREAM_STATE: dict[str, Any] = {
  482. "_stream_callback": None, # streaming TTS; set early so _vprint can reference it
  483. "_stream_needs_break": False, # one "\n\n" before the next real text delta after tools
  484. # Stateful scrubbers: <memory-context> / thinking spans split across deltas defeat
  485. # per-delta regexes (both tags must be in one string).
  486. "_stream_context_scrubber": StreamingContextScrubber,
  487. "_stream_think_scrubber": StreamingThinkScrubber,
  488. "_current_streamed_assistant_text": "", # so a later completed interim isn't re-sent
  489. "_delivered_interim_texts": set, # interims this user turn (spans Codex continuations)
  490. # Single-writer guard for the delta sink: each attempt claims a monotonic writer token and
  491. # the sink drops chunks from threads holding a stale one, so a superseded stream can't
  492. # interleave with the retry's. Threads that never claimed are never fenced.
  493. "_stream_writer_lock": threading.Lock,
  494. "_stream_writer_token": 0,
  495. "_stream_writer_tls": threading.local,
  496. "_stream_writer_dropped": 0,
  497. # Set once a strict endpoint 400/422s on ``stream_options``; later streams omit it (#9705).
  498. "_stream_options_unsupported": False,
  499. # API-facing user message override when it differs from the persisted transcript (voice).
  500. "_persist_user_message_idx": None,
  501. "_persist_user_message_override": None,
  502. "_persist_user_message_timestamp": None,
  503. # Image-to-text fallbacks cached per payload/URL so one tool loop doesn't re-run vision.
  504. "_anthropic_image_fallback_cache": dict,
  505. }
  506. def _init_prompt_cache_config(agent):
  507. # Anthropic prompt caching (~75% input savings): auto-enabled for Claude on native
  508. # Anthropic, OpenRouter and anthropic_messages gateways. See _anthropic_prompt_cache_policy.
  509. agent._use_prompt_caching, agent._use_native_cache_layout = (
  510. agent._anthropic_prompt_cache_policy()
  511. )
  512. agent._cache_disabled = False
  513. # cache_ttl: "5m" (default), "1h" (2x write cost; pays off with >5-minute pauses) or "auto"
  514. # (1h when a person paces the session, 5m when a machine does); unknown values keep "5m". A falsy/off value disables caching entirely (OAuth plans
  515. # billing cache writes, proxies adding their own cache_control); the disable survives
  516. # /model switches and fallback re-derivation.
  517. # Anthropic supports "5m" (default) and "1h" cache TTL tiers. Read from config.yaml under
  518. # prompt_caching.cache_ttl; unknown values keep "5m". 1h tier costs 2x on write vs 1.25x for 5m, but
  519. # amortizes across long sessions with >5-minute pauses between turns (#14971). This is useful for OAuth
  520. # subscription users where cache writes bill against "extra usage" or for third-party proxies that
  521. # inject their own cache_control markers (#13477).
  522. agent._cache_ttl = "5m"
  523. try:
  524. from hermes_cli.config import load_config_readonly as _load_pc_cfg
  525. from agent.agent_runtime_helpers import cache_ttl_means_disabled
  526. from agent.prompt_caching import AUTO_CACHE_TTL, auto_cache_ttl_for_source
  527. _pc_cfg = _load_pc_cfg().get("prompt_caching", {}) or {}
  528. _ttl = _pc_cfg.get("cache_ttl", "5m")
  529. if _ttl in {"5m", "1h"}:
  530. agent._cache_ttl = _ttl
  531. elif _ttl == AUTO_CACHE_TTL:
  532. # Decided once per session from its source (a delegated child is clamped to 5m again
  533. # in delegate_tool regardless).
  534. from agent.session_source import session_source_for
  535. agent._cache_ttl = auto_cache_ttl_for_source(session_source_for(getattr(agent, "platform", None)))
  536. elif cache_ttl_means_disabled(_ttl):
  537. agent._use_prompt_caching = False
  538. agent._use_native_cache_layout = False
  539. agent._cache_ttl = None
  540. agent._cache_disabled = True
  541. except Exception as exc: # health: allow BLE001 -- init must survive any config failure; the class is logged
  542. # Config values and traceback frames may contain credentials.
  543. logger.warning(
  544. "Agent configuration for prompt_caching.cache_ttl could not be loaded (%s); "
  545. "using default prompt caching settings. Check the active Hermes Python "
  546. "environment and dependencies; run 'hermes config check' after "
  547. "configuration imports work again.",
  548. type(exc).__name__,
  549. )
  550. def _init_turn_state(agent, run_budget_seconds):
  551. _set_defaults(agent, _TURN_STATE)
  552. # Wall-clock run budget per turn: constructor arg wins, else agent.run_budget_seconds
  553. # (in _apply_agent_section). None = fully off (no clock reads, injection, or capping).
  554. agent.run_budget_seconds = _normalize_run_budget_seconds(run_budget_seconds)
  555. from agent.credits_tracker import new_credits_latch
  556. agent._credits_latch = new_credits_latch() # threshold-notice latch (sticky keys + gates)
  557. def _setup_logging(agent):
  558. # agent.log (INFO+) + errors.log (WARNING+); idempotent so per-message gateway agents
  559. # don't duplicate handlers.
  560. from hermes_logging import setup_logging, setup_verbose_logging
  561. # The ACTIVE home, not run_agent's import-time freeze: a Desktop serve backend builds agents
  562. # for several profiles inside set_hermes_home_override(), and the frozen launch home made
  563. # setup_logging() see a home it already served, so it never adopted the profile and every
  564. # profile's records landed in the launch profile's agent.log (#125974).
  565. setup_logging(hermes_home=get_hermes_home())
  566. if agent.verbose_logging:
  567. setup_verbose_logging()
  568. _ra().logger.info("Verbose logging enabled (third-party library logs suppressed)")
  569. # Quiet mode must NOT raise per-logger levels: isEnabledFor() runs before propagation and
  570. # would starve the root file handlers. Noise reduction belongs in hermes_logging.
  571. def _print_key_banner(key, label: str, warn_missing: bool = False) -> None:
  572. """Masked credential line. A callable ``key`` (Entra ID, Vertex OAuth, key_cmd, ...) is labelled
  573. by its tagged source and never invoked. Keys ≤ 12 chars (incl. "dummy-key") are not shown."""
  574. from agent.credential_source import credential_label
  575. if source_label := credential_label(key):
  576. print(f"🔑 Using credentials: {source_label}")
  577. elif isinstance(key, str) and len(key) > 12:
  578. print(f"🔑 Using {label}: {key[:8]}...{key[-4:]}")
  579. elif warn_missing:
  580. print("⚠️ Warning: API key appears invalid or missing")
  581. def _init_anthropic_client(agent, api_key, base_url, _provider_timeout):
  582. """anthropic_messages: native Anthropic SDK (or AnthropicBedrock for Bedrock+Claude)."""
  583. from agent.anthropic_adapter import build_anthropic_client
  584. from agent.anthropic_credentials import resolve_anthropic_token
  585. agent.client = None
  586. agent._client_kwargs = {}
  587. agent._anthropic_base_url = base_url
  588. if agent.provider == "bedrock":
  589. # AnthropicBedrock SDK for full feature parity (prompt caching, thinking budgets).
  590. from agent.bedrock_adapter import bind_bedrock_runtime
  591. bind_bedrock_runtime(agent, base_url, "anthropic_messages")
  592. if not agent.quiet_mode:
  593. print(f"🤖 AI Agent initialized with model: {agent.model} (AWS Bedrock + AnthropicBedrock SDK, {agent._bedrock_region})")
  594. return
  595. # ANTHROPIC_TOKEN fallback only for native Anthropic — other anthropic_messages providers
  596. # must use their own key or Anthropic credentials leak to third-party endpoints.
  597. # Falling back would send Anthropic credentials to third-party endpoints (Fixes #1739, #minimax-401).
  598. _is_native_anthropic = agent.provider == "anthropic"
  599. effective_key = api_key or (resolve_anthropic_token(model=getattr(agent, "model", None)) if _is_native_anthropic else None) or ""
  600. # MiniMax OAuth tokens live ~15 min and the SDK freezes api_key at construction, so use a
  601. # callable provider: build_anthropic_client mints a fresh bearer per request (re-reading
  602. # auth.json, so other processes' refreshes are seen).
  603. if agent.provider == "minimax-oauth" and isinstance(effective_key, str) and effective_key:
  604. try:
  605. from hermes_cli.auth import build_minimax_oauth_token_provider
  606. effective_key = build_minimax_oauth_token_provider()
  607. except Exception as _mm_exc:
  608. logging.getLogger(__name__).warning(
  609. "MiniMax OAuth: failed to install per-request token provider "
  610. "(%s); falling back to static bearer that will expire ~15min in.",
  611. _mm_exc,
  612. )
  613. agent.api_key = effective_key
  614. agent._anthropic_api_key = effective_key
  615. # OAuth only for native Anthropic routes (the anthropic provider, or a custom provider whose host
  616. # is exactly api.anthropic.com, incl. a key_cmd callable token — #114967). Third-party
  617. # providers (MiniMax, Kimi, GLM, LiteLLM proxies) that accept the Anthropic protocol must never
  618. # trip OAuth code paths — doing so injects Claude-Code identity headers and system prompts that
  619. # cause 401/403 on their endpoints. See #1739.
  620. from agent.anthropic_credentials import anthropic_route_is_oauth
  621. agent._is_anthropic_oauth = anthropic_route_is_oauth(base_url, effective_key, provider=agent.provider)
  622. agent._anthropic_client = build_anthropic_client(effective_key, base_url, timeout=_provider_timeout)
  623. if not agent.quiet_mode:
  624. print(f"🤖 AI Agent initialized with model: {agent.model} (Anthropic native)")
  625. _print_key_banner(effective_key, "token")
  626. def _init_moa_client(agent, api_key):
  627. """provider == "moa": virtual Mixture-of-Agents facade, no real HTTP client."""
  628. from agent.moa_loop import bind_moa_runtime
  629. # build_moa_facade relays "moa.*" events through tool_progress_callback so every surface
  630. # shows each reference's answer before the aggregator acts. Display-only; shared with
  631. # fallback-restore so a restored facade keeps emitting.
  632. # build_moa_facade wires the reference relay that routes reference-model outputs to the agent's
  633. # tool_progress_callback so every surface that already consumes it (CLI spinner/scrollback, TUI,
  634. # desktop, gateway) can show each reference's answer as a labelled block before the aggregator acts. The
  635. # facade emits "moa.reference", "moa.progress", "moa.phase", and "moa.aggregating" events, forwarded
  636. # through the same callback the tool lifecycle uses. Best-effort and cache-safe — display-only events,
  637. # they never touch the message history. See #53802.
  638. bind_moa_runtime(agent, agent.model, api_key)
  639. if not agent.quiet_mode:
  640. print(f"🤖 AI Agent initialized with MoA preset: {agent.model}")
  641. def _init_bedrock_client(agent, base_url):
  642. """bedrock_converse: boto3 directly, no OpenAI client."""
  643. from agent.bedrock_adapter import bind_bedrock_runtime
  644. bind_bedrock_runtime(agent, base_url, "bedrock_converse")
  645. if not agent.quiet_mode:
  646. _gr_label = " + Guardrails" if agent._bedrock_guardrail_config else ""
  647. print(f"🤖 AI Agent initialized with model: {agent.model} (AWS Bedrock, {agent._bedrock_region}{_gr_label})")
  648. def _explicit_client_kwargs(agent, api_key, base_url, _provider_timeout) -> dict[str, Any]:
  649. """OpenAI-client kwargs from explicit CLI/gateway credentials (auth already resolved)."""
  650. _parsed_url = urlparse(base_url)
  651. client_kwargs = {"api_key": api_key, "base_url": base_url}
  652. if _parsed_url.query:
  653. client_kwargs["base_url"] = urlunparse(_parsed_url._replace(query=""))
  654. client_kwargs["default_query"] = {k: v[0] for k, v in parse_qs(_parsed_url.query).items()}
  655. if _provider_timeout is not None:
  656. client_kwargs["timeout"] = _provider_timeout
  657. # ACP/subprocess providers take launch kwargs instead of HTTP credentials. Keyed on the profile's
  658. # auth_type, not a vendor slug: every external_process plugin gets this launch path (#102421).
  659. from hermes_cli.runtime_provider_backends import _is_external_process_provider
  660. if _is_external_process_provider(agent.provider):
  661. client_kwargs["command"] = agent.acp_command
  662. client_kwargs["args"] = agent.acp_args
  663. from agent.provider_route_hooks import route_answer
  664. _headers_for = _host_default_headers_factory(base_url)
  665. if _headers_for is not None:
  666. client_kwargs["default_headers"] = _headers_for(api_key, base_url)
  667. elif _route_headers := route_answer("client_headers", provider=str(agent.provider or ""), base_url=base_url, scope=agent,
  668. api_key=api_key if isinstance(api_key, str) else ""):
  669. client_kwargs["default_headers"] = _route_headers
  670. elif "default_headers" not in client_kwargs:
  671. # Static profile.default_headers (Vercel AI Gateway attribution, Kimi UA on non-kimi.com endpoints).
  672. with suppress(Exception):
  673. from providers import get_provider_profile as _gpf
  674. _ph = _gpf(agent.provider)
  675. if _ph and _ph.default_headers:
  676. client_kwargs["default_headers"] = dict(_ph.default_headers)
  677. return client_kwargs
  678. def _routed_client_kwargs(agent, fallback_model, _provider_timeout) -> Optional[dict[str, Any]]:
  679. """OpenAI-client kwargs via the centralized provider router (no explicit creds).
  680. Falls through to the init-time fallback chain, then raises with the missing-key /
  681. no-provider diagnostic. ``None`` when the chain landed on a MoA preset: the facade is
  682. already bound and there is no OpenAI client to construct.
  683. """
  684. from agent.auxiliary_client import resolve_provider_client
  685. _routed_client, _ = resolve_provider_client(
  686. agent.provider or "auto", model=agent.model, raw_codex=True)
  687. if _routed_client is not None:
  688. from hermes_cli.providers import is_actual_route, normalize_provider
  689. effective_provider = getattr(_routed_client, "_hermes_aux_effective_provider", "")
  690. if is_actual_route(effective_provider):
  691. agent.provider = normalize_provider(effective_provider)
  692. return _client_kwargs_from_routed(_routed_client, _provider_timeout)
  693. # No credentials: try the fallback chain BEFORE failing (an exhausted single-entry pool
  694. # must not die with a misleading "No LLM provider configured"); only explicitly named
  695. # providers keep the missing-key diagnostic.
  696. # An exhausted single-entry pool (typically ``openrouter`` under free-tier daily quotas) must still
  697. # reach the chain instead of dying at init with a misleading "No LLM provider configured" error. See
  698. # #17929.
  699. _explicit = (agent.provider or "").strip().lower()
  700. _refused_entries = []
  701. for _fb in _fallback_entries(fallback_model):
  702. _fb_provider = str(_fb["provider"])
  703. try:
  704. from hermes_cli.fallback_config import resolve_entry_api_key
  705. _fb_explicit_key = resolve_entry_api_key(_fb)
  706. _fb_client, _fb_model = resolve_provider_client(
  707. _fb["provider"], model=_fb["model"], raw_codex=True,
  708. explicit_base_url=_fb.get("base_url"), explicit_api_key=_fb_explicit_key,
  709. )
  710. except Exception as _fb_exc:
  711. logger.debug("Init-time fallback entry %s failed: %s", _fb_provider, _fb_exc)
  712. # A bare exception (``KeyError()``) stringifies empty; name its type instead.
  713. _refused_entries.append((_fb_provider, str(_fb_exc) or type(_fb_exc).__name__))
  714. continue
  715. if _fb_client is None:
  716. # The router returns None when no credentials are usable for the entry — a skip
  717. # that leaves no trace otherwise, hiding key-less fallback entries from the log.
  718. logger.debug(
  719. "Init-time fallback entry %s resolved no usable credentials", _fb_provider
  720. )
  721. _refused_entries.append((_fb_provider, "no usable credentials"))
  722. continue
  723. agent._fallback_activated = True
  724. if _fb_provider.strip().lower() == "moa":
  725. # The chokepoint handed back the preset's aggregator client, which only proves the
  726. # preset resolves and its aggregator has credentials. A MoA entry means the preset
  727. # itself (same as ``provider: moa`` in config), so bind the facade, not the aggregator.
  728. from agent.moa_loop import bind_moa_runtime
  729. bind_moa_runtime(agent, _fb["model"])
  730. return None
  731. agent.provider = agent.requested_provider = _fb["provider"]
  732. agent.model = _fb_model or _fb["model"]
  733. recompute_init_fallback_api_mode(agent, _fb_client)
  734. return _client_kwargs_from_routed(_fb_client, _provider_timeout)
  735. # A burned credential pool (#119533) is otherwise indistinguishable from missing config,
  736. # so name it even when no fallback entries are configured.
  737. _pool_exhausted = False
  738. _pool = None
  739. if _explicit and _explicit != "auto":
  740. with suppress(Exception):
  741. from agent.credential_pool import load_pool
  742. _pool = load_pool(_explicit)
  743. _pool_exhausted = _pool.has_credentials() and not _pool.has_available(model=agent.model)
  744. if _refused_entries or _pool_exhausted:
  745. # Neutral wording: the explicit-provider branch below raises the provider-specific
  746. # missing-credentials message, not the generic "No LLM provider configured" one.
  747. logger.warning(
  748. "Init-time provider resolution failed: primary %r unresolvable (%s); fallback entries refused: %s",
  749. agent.provider,
  750. "credential pool exhausted" if _pool_exhausted else "no usable credentials",
  751. "; ".join(f"{_p} ({_r})" for _p, _r in _refused_entries) or "none configured",
  752. )
  753. # A fully-exhausted pool is a billing/quota failure, NOT a config problem: name it for EVERY
  754. # explicit provider. ``openrouter`` / ``custom`` have no provider-specific missing-credentials
  755. # branch, so a burned override pool there fell through to the generic "No LLM provider
  756. # configured" setup message even though the config default was fine (#94785). Prefer a billing
  757. # verdict (402 / classifier "billing") and fall back to the existing cooldown wording (which
  758. # names the 429 reset time, #56810); raise before the missing-credentials branch so a genuine
  759. # 402 is never described as a missing key or a transient rate limit.
  760. if _pool_exhausted:
  761. from agent.auxiliary_unavailable import (
  762. ProviderCredentialsExhaustedError,
  763. pool_billing_message,
  764. pool_cooldown_message,
  765. )
  766. _exhausted_message = (
  767. pool_billing_message(_explicit, model=agent.model, pool=_pool)
  768. or pool_cooldown_message(_explicit)
  769. )
  770. if _exhausted_message:
  771. raise ProviderCredentialsExhaustedError(_exhausted_message, provider=_explicit)
  772. if _explicit and _explicit not in {"auto", "openrouter", "custom"}:
  773. # Explicit non-OpenRouter provider with no creds and no usable fallback: fail fast.
  774. from agent.auxiliary_unavailable import ProviderNotConfiguredError, missing_provider_credentials_message
  775. raise ProviderNotConfiguredError(missing_provider_credentials_message(_explicit))
  776. from hermes_constants import profile_cli_selector
  777. from agent.auxiliary_unavailable import ProviderNotConfiguredError
  778. _sel = profile_cli_selector()
  779. raise ProviderNotConfiguredError(
  780. "No LLM provider configured. Run `hermes model` to "
  781. "select a provider, or run `hermes setup` for first-time "
  782. "configuration."
  783. )
  784. def _apply_openai_header_policy(agent, client_kwargs: dict[str, Any]) -> None:
  785. """Mutate ``client_kwargs`` (== ``agent._client_kwargs``) with header/TLS policy, in order:
  786. OpenRouter Claude beta header → model.default_headers → custom-provider TLS/extra_headers."""
  787. # Fine-grained tool streaming for Claude on OpenRouter: without the beta header
  788. # Anthropic buffers the whole tool call and OpenRouter's proxy times out.
  789. from agent.anthropic_adapter import _TOOL_STREAMING_BETA
  790. _effective_base = str(client_kwargs.get("base_url", "")).lower()
  791. if base_url_host_matches(_effective_base, "openrouter.ai") and "claude" in (agent.model or "").lower():
  792. headers = client_kwargs.get("default_headers") or {}
  793. existing_beta = headers.get("x-anthropic-beta", "")
  794. if _TOOL_STREAMING_BETA not in existing_beta:
  795. headers["x-anthropic-beta"] = ",".join(filter(None, (existing_beta, _TOOL_STREAMING_BETA)))
  796. client_kwargs["default_headers"] = headers
  797. # model.default_headers override provider/SDK defaults (WAFs rejecting SDK headers).
  798. agent._apply_user_default_headers()
  799. try:
  800. from hermes_cli.config import (
  801. apply_custom_provider_extra_headers_to_client_kwargs,
  802. apply_custom_provider_tls_to_client_kwargs, get_compatible_custom_providers,
  803. load_config,
  804. )
  805. _cp_entries = get_compatible_custom_providers(load_config())
  806. _cp_base_url = str(client_kwargs.get("base_url") or agent.base_url or "")
  807. apply_custom_provider_tls_to_client_kwargs(client_kwargs, _cp_base_url, _cp_entries)
  808. # Per-provider extra_headers applied last so the most specific config level wins.
  809. # SECURITY: values may carry credentials — never log them.
  810. apply_custom_provider_extra_headers_to_client_kwargs(client_kwargs, _cp_base_url, _cp_entries)
  811. except Exception:
  812. logger.debug("custom-provider TLS resolution skipped", exc_info=True)
  813. def _init_openai_client(agent, api_key, base_url, fallback_model, _provider_timeout):
  814. """OpenAI-wire client: resolve kwargs, apply header/TLS policy, construct."""
  815. if api_key and base_url:
  816. client_kwargs = _explicit_client_kwargs(agent, api_key, base_url, _provider_timeout)
  817. else:
  818. client_kwargs = _routed_client_kwargs(agent, fallback_model, _provider_timeout)
  819. if client_kwargs is None: # init-time fallback bound the MoA facade
  820. if not agent.quiet_mode:
  821. print(f"🤖 AI Agent initialized with MoA preset: {agent.model}")
  822. return
  823. from hermes_cli.providers import is_actual_route
  824. if is_actual_route(agent.provider, client_kwargs.get("base_url", "")):
  825. agent.api_mode = "chat_completions"
  826. if hasattr(agent, "_transport_cache"):
  827. agent._transport_cache.clear()
  828. try:
  829. from agent.bedrock_adapter import configure_bedrock_openai_client_kwargs
  830. configure_bedrock_openai_client_kwargs(client_kwargs, timeout=_provider_timeout)
  831. except Exception:
  832. if agent.provider == "bedrock" and "bedrock-mantle." in str(client_kwargs.get("base_url", "")):
  833. raise
  834. agent._client_kwargs = client_kwargs # stored for rebuilding after interrupt
  835. _apply_openai_header_policy(agent, client_kwargs)
  836. agent.api_key = client_kwargs.get("api_key", "")
  837. agent.base_url = client_kwargs.get("base_url", agent.base_url)
  838. try:
  839. agent.client = agent._create_openai_client(client_kwargs, reason="agent_init", shared=True)
  840. if not agent.quiet_mode:
  841. print(f"🤖 AI Agent initialized with model: {agent.model}")
  842. if base_url:
  843. print(f"🔗 Using custom base URL: {base_url}")
  844. from gateway.warning_notifications import warning_notifications_enabled
  845. _print_key_banner(client_kwargs.get("api_key", "none"), "API key",
  846. warn_missing=warning_notifications_enabled(agent.platform))
  847. except Exception as e:
  848. raise RuntimeError(f"Failed to initialize OpenAI client: {e}")
  849. def _build_client(agent, api_key, base_url, fallback_model):
  850. # LLM client per wire mode (raw_codex=True: the main agent needs direct
  851. # responses.stream()). One provider/model timeout up front so every path applies it.
  852. agent._anthropic_client = None
  853. agent._is_anthropic_oauth = False
  854. _provider_timeout = get_provider_request_timeout(agent.provider, agent.model)
  855. if agent.api_mode == "anthropic_messages":
  856. _init_anthropic_client(agent, api_key, base_url, _provider_timeout)
  857. elif agent.provider == "moa":
  858. _init_moa_client(agent, api_key)
  859. elif agent.api_mode == "bedrock_converse":
  860. _init_bedrock_client(agent, base_url)
  861. else:
  862. _init_openai_client(agent, api_key, base_url, fallback_model, _provider_timeout)
  863. def _lazy_headers(module: str, name: str, pass_key: bool = False, pass_base: bool = False):
  864. """Header factory ``(api_key, base_url) -> dict`` importing ``module.name`` at call time.
  865. ``pass_key`` forwards ``(key, base_url=base)``; ``pass_base`` forwards ``(base)``."""
  866. def factory(key, base):
  867. import importlib
  868. fn = getattr(importlib.import_module(module), name)
  869. if pass_key:
  870. return fn(key, base_url=base)
  871. return fn(base) if pass_base else fn()
  872. return factory
  873. # Host → default_headers factory for explicit base_url client construction. Ordered: first
  874. # host match wins; no match falls back to the provider profile's declared headers.
  875. _HOST_DEFAULT_HEADERS: list[tuple[str, Callable[[Any, str], dict[str, str]]]] = [
  876. ("openrouter.ai", _lazy_headers("agent.auxiliary_client", "build_or_headers")),
  877. ("integrate.api.nvidia.com",
  878. _lazy_headers("agent.auxiliary_client", "build_nvidia_nim_headers", pass_base=True)),
  879. ("api.routermint.com", _lazy_headers("agent.client_lifecycle", "_routermint_headers")),
  880. ("api.kimi.com", lambda _k, _b: {"User-Agent": "claude-code/0.1.0"}),
  881. ("portal.qwen.ai", _lazy_headers("agent.client_lifecycle", "_qwen_portal_headers")),
  882. ("chatgpt.com", _lazy_headers("agent.codex_headers", "codex_cloudflare_headers", pass_key=True)),
  883. ("x.ai", _lazy_headers("tools.xai_http", "hermes_xai_default_headers")),
  884. ]
  885. def _host_default_headers_factory(base_url: str):
  886. for host, factory in _HOST_DEFAULT_HEADERS:
  887. if base_url_host_matches(base_url, host):
  888. return factory
  889. return None
  890. def _client_kwargs_from_routed(client, timeout) -> dict[str, Any]:
  891. """OpenAI-client kwargs mirroring a router-resolved client, keeping its provider headers
  892. (SDK stores them in ``_custom_headers``; older/mocked clients expose ``default_headers``)."""
  893. kwargs = {"api_key": client.api_key, "base_url": str(client.base_url)}
  894. if timeout is not None:
  895. kwargs["timeout"] = timeout
  896. headers = (
  897. getattr(client, "_custom_headers", None)
  898. or getattr(client, "default_headers", None)
  899. or getattr(client, "_default_headers", None)
  900. )
  901. if headers:
  902. kwargs["default_headers"] = dict(headers)
  903. return kwargs
  904. def _load_tools(agent, enabled_toolsets, disabled_toolsets):
  905. from agent.runtime_context import load_tools
  906. if load_tools(agent):
  907. return
  908. # A feature that left core (Home Assistant) is installed once per process before discovery, so its tools
  909. # are in this snapshot; outcomes wait for a turn someone sees (deliver_kept_startup_notices), maybe not ours.
  910. from hermes_cli.left_core_migration import recover_at_startup
  911. recover_at_startup()
  912. # A multiplexed gateway may have switched HERMES_HOME since model_tools was imported;
  913. # make sure this profile's plugins are discovered before the tool snapshot.
  914. try:
  915. from hermes_cli.plugins import discover_plugins
  916. discover_plugins()
  917. except Exception:
  918. logger.warning("Plugin discovery failed during agent setup", exc_info=True)
  919. # Capture the registry generation FIRST so a concurrent refresh can detect staleness, and the delegation
  920. # backend this delegate_task is built from: the session routes on it (agent/delegation_backends.py).
  921. from agent.delegation_backends import saved_backend
  922. from tools.registry import registry as _snapshot_registry
  923. agent._tool_snapshot_generation, agent._delegation_backend = _snapshot_registry._generation, saved_backend()
  924. import model_tools
  925. from agent.oneshot_footprint import agent_is_oneshot
  926. from toolsets import agent_tool_surface, session_disabled_toolsets, tool_selection_key
  927. agent._configured_disabled_toolsets, disabled_toolsets = disabled_toolsets, session_disabled_toolsets(
  928. disabled_toolsets, getattr(agent, "platform", None), oneshot=agent_is_oneshot(agent)) # pin restore reads both
  929. agent.disabled_toolsets = disabled_toolsets # so the tool_search bridge and delegate children drop them too
  930. agent._tool_snapshot_selection = tool_selection_key(enabled_toolsets, disabled_toolsets) # tools[] freeze gate
  931. agent.tools = agent_tool_surface(agent, model_tools.get_tool_definitions(
  932. enabled_toolsets=enabled_toolsets, disabled_toolsets=disabled_toolsets, quiet_mode=agent.quiet_mode) or [])
  933. agent.valid_tool_names = {tool["function"]["name"] for tool in agent.tools} if agent.tools else set()
  934. # Kanban guidance is session-static for the dispatcher-owned worker only. Profiles may
  935. # expose kanban_show interactively, and children/cron runs inherit the env var, without
  936. # owning a task.
  937. from agent.delegation_context import owned_kanban_task
  938. from agent.prompt_builder import KANBAN_GUIDANCE
  939. agent._kanban_worker_guidance = (
  940. KANBAN_GUIDANCE if owned_kanban_task() and "kanban_show" in agent.valid_tool_names else ""
  941. )
  942. if agent.quiet_mode:
  943. return
  944. if agent.tools:
  945. print(f"🛠️ Loaded {len(agent.tools)} tools: {', '.join(sorted(agent.valid_tool_names))}")
  946. if enabled_toolsets:
  947. print(f" ✅ Enabled toolsets: {', '.join(enabled_toolsets)}")
  948. if disabled_toolsets:
  949. print(f" ❌ Disabled toolsets: {', '.join(disabled_toolsets)}")
  950. import model_tools
  951. requirements = model_tools.check_toolset_requirements()
  952. missing_reqs = [name for name, available in requirements.items() if not available]
  953. if missing_reqs:
  954. agent._safe_print(f"⚠️ Some tools may not work due to missing requirements: {missing_reqs}", diagnostic=True)
  955. else:
  956. print("🛠️ No tools loaded (all tools filtered out or unavailable)")
  957. if agent.save_trajectories:
  958. print("📝 Trajectory saving enabled")
  959. if agent.ephemeral_system_prompt:
  960. prompt_preview = agent.ephemeral_system_prompt[:60] + "..." if len(agent.ephemeral_system_prompt) > 60 else agent.ephemeral_system_prompt
  961. print(f"🔒 Ephemeral system prompt: '{prompt_preview}' (not saved to trajectories)")
  962. if agent._use_prompt_caching:
  963. if agent._use_native_cache_layout and agent.provider == "anthropic":
  964. source = "native Anthropic"
  965. elif agent._use_native_cache_layout:
  966. source = "Anthropic-compatible endpoint"
  967. else:
  968. source = "Claude via OpenRouter"
  969. print(f"💾 Prompt caching: ENABLED ({source}, {agent._cache_ttl} TTL)")
  970. def _publish_session_id(session_id: str) -> None:
  971. """Expose the session ID to tools via ContextVar (+ legacy os.environ fallback).
  972. If the ContextVar bridge fails to import, keep the root-agent env fallback but never let
  973. delegated construction publish a child ID process-wide.
  974. """
  975. try:
  976. from gateway.session_context import set_current_session_id
  977. set_current_session_id(session_id)
  978. except Exception:
  979. try:
  980. from agent.delegation_context import is_delegated_child_context
  981. delegated_child = is_delegated_child_context()
  982. except Exception:
  983. delegated_child = False
  984. if not delegated_child:
  985. os.environ["HERMES_SESSION_ID"] = session_id
  986. def _init_session_state(agent, session_id, session_db, parent_session_id, reasoning_config, max_tokens,
  987. checkpoints_enabled, checkpoint_max_snapshots, checkpoint_max_total_size_mb, checkpoint_max_file_size_mb):
  988. agent.session_start = datetime.now()
  989. agent.session_id = session_id or new_session_id(agent.session_start)
  990. _publish_session_id(agent.session_id)
  991. # ~/.hermes/sessions/ — kept unconditionally for request_dump_*.json debug breadcrumbs.
  992. agent.logs_dir = get_hermes_home() / "sessions"
  993. agent.logs_dir.mkdir(parents=True, exist_ok=True)
  994. _set_defaults(agent, _SESSION_STATE)
  995. # Filesystem checkpoint manager (transparent — not a tool)
  996. from tools.checkpoint_manager import CheckpointManager
  997. agent._checkpoint_mgr = CheckpointManager(
  998. enabled=checkpoints_enabled, max_snapshots=checkpoint_max_snapshots,
  999. max_total_size_mb=checkpoint_max_total_size_mb,
  1000. max_file_size_mb=checkpoint_max_file_size_mb,
  1001. )
  1002. agent._session_db = session_db # optional SQLite store (CLI/gateway-provided)
  1003. agent._parent_session_id = parent_session_id
  1004. agent._session_init_model_config = {
  1005. "max_iterations": agent.max_iterations,
  1006. "reasoning_config": reasoning_config,
  1007. "max_tokens": max_tokens,
  1008. }
  1009. # Process-scoped --yolo is persisted so `hermes --resume` restores the bypass
  1010. # (SessionDB.session_yolo_enabled); session-scoped /yolo toggles persist separately.
  1011. with suppress(Exception):
  1012. from tools.approval import _YOLO_MODE_FROZEN
  1013. if _YOLO_MODE_FROZEN:
  1014. agent._session_init_model_config["yolo_mode"] = True
  1015. # In-memory todo list for task planning (one per agent/session)
  1016. from tools.todo_tool import TodoStore
  1017. agent._todo_store = TodoStore()
  1018. def _apply_display_config(agent, _agent_cfg, platform):
  1019. # show_commentary: Codex phase=commentary → interim path (true) or reasoning channel.
  1020. agent.show_commentary = bool(_cfg_dict(_agent_cfg, "display").get("show_commentary", True))
  1021. # Window (seconds) for the bounded /fast auto|cold modes (agent.fast_mode).
  1022. agent.fast_auto_seconds = (_agent_cfg.get("agent") or {}).get("fast_auto_seconds", 60)
  1023. # lmstudio_load_mode: "explicit" (preload via management API) or "jit" (Auto-Evict path).
  1024. _model_section = _cfg_dict(_agent_cfg, "model")
  1025. _load_mode = str(_model_section.get("lmstudio_load_mode", "explicit") or "explicit").strip().lower()
  1026. agent.lmstudio_load_mode = _load_mode if _load_mode in {"explicit", "jit"} else "explicit"
  1027. if agent.lmstudio_load_mode != _load_mode:
  1028. logger.warning(
  1029. "Invalid model.lmstudio_load_mode=%r; expected 'explicit' or 'jit'. Using explicit.",
  1030. _model_section.get("lmstudio_load_mode"),
  1031. )
  1032. # model.streaming=false seeds _disable_streaming (the loop's runtime fallback) for
  1033. # backends with broken streaming tool calls. Session-scoped; orthogonal to display.streaming.
  1034. _streaming = str(_model_section.get("streaming", "true")).strip().lower()
  1035. agent._disable_streaming = _streaming in {"false", "0", "no", "off"}
  1036. if not agent._disable_streaming and _streaming not in {"true", "1", "yes", "on"}:
  1037. logger.warning(
  1038. "Invalid model.streaming=%r; expected a boolean. Using streaming (default).",
  1039. _model_section.get("streaming"),
  1040. )
  1041. agent._stream_5xx_probe_ts = None # monotonic time of the last streaming-5xx unmask probe
  1042. try:
  1043. agent._tool_guardrails = ToolCallGuardrailController(
  1044. ToolCallGuardrailConfig.from_mapping(
  1045. _agent_cfg.get("tool_loop_guardrails", {}), platform=platform,
  1046. )
  1047. )
  1048. except Exception as _tlg_err:
  1049. _ra().logger.warning("Tool loop guardrail config ignored: %s", _tlg_err)
  1050. def _memory_provider_init_kwargs(agent, platform) -> dict[str, Any]:
  1051. """Scoping kwargs for ``MemoryManager.initialize_all`` (status_callback is CLI-only:
  1052. gateway status travels a different path and the indicator no-ops without it)."""
  1053. kwargs = {
  1054. "session_id": agent.session_id,
  1055. "platform": platform or "cli",
  1056. "hermes_home": str(get_hermes_home()),
  1057. # platform="cron" (scheduler) / "subagent" (delegate_task) → providers skip writes (MemoryProvider.initialize).
  1058. "agent_context": platform if platform in ("cron", "subagent") else "primary",
  1059. }
  1060. if kwargs["platform"] == "cli":
  1061. kwargs["warning_callback"] = agent._emit_warning
  1062. kwargs["status_callback"] = agent._emit_status
  1063. # Session title (e.g. honcho derives chat-scoped session keys from it).
  1064. if agent._session_db:
  1065. with suppress(Exception):
  1066. _st = agent._session_db.get_session_title(agent.session_id)
  1067. if _st:
  1068. kwargs["session_title"] = _st
  1069. _source = agent._session_db.get_session_title_source(agent.session_id)
  1070. if _source:
  1071. kwargs["session_title_source"] = _source
  1072. # Gateway user/chat identity for per-user scoping (gateway_session_key: stable per-chat
  1073. # Honcho session isolation).
  1074. for _ident in _GATEWAY_IDENTITY_PARAMS:
  1075. _val = getattr(agent, f"_{_ident}")
  1076. if _val:
  1077. kwargs[_ident] = _val
  1078. if agent.session_cwd:
  1079. kwargs["cwd"] = agent.session_cwd
  1080. from agent.runtime_context import current
  1081. embedded = current()
  1082. if embedded is not None:
  1083. kwargs["agent_identity"] = embedded["botId"]
  1084. kwargs["agent_workspace"] = embedded["workspaceId"]
  1085. kwargs["project_id"] = embedded.get("projectId")
  1086. return kwargs
  1087. # Profile identity for per-profile provider scoping
  1088. with suppress(Exception):
  1089. from hermes_cli.profiles import get_active_profile_name
  1090. kwargs["agent_identity"] = get_active_profile_name()
  1091. kwargs["agent_workspace"] = "hermes"
  1092. return kwargs
  1093. def _init_memory(agent, _agent_cfg, skip_memory, platform, memory_manager=None):
  1094. from agent.yaovi_memory import initialize
  1095. if initialize(agent, _agent_cfg, skip_memory, platform):
  1096. return
  1097. # Persistent memory (MEMORY.md + USER.md) — loaded from disk
  1098. agent._memory_store = None
  1099. agent._memory_enabled = False
  1100. agent._user_profile_enabled = False
  1101. agent._memory_nudge_interval = 10
  1102. agent._turns_since_memory = 0
  1103. agent._iters_since_skill = 0
  1104. from agent.safe_worker_policy import safe_worker_enabled
  1105. if safe_worker_enabled():
  1106. agent._memory_manager = None
  1107. return
  1108. # skip_memory skips the external *provider*; enabled_toolsets=["memory"] still gets the
  1109. # built-in store so the memory tool never sees store=None.
  1110. # Flush/background agents can still pass enabled_toolsets=["memory"] so the built-in file store exists
  1111. # and the memory tool does not fail with store=None (#65429). A toolset on disabled_toolsets is not a
  1112. # request: a caller that denylists memory while its default toolset still names it must not get
  1113. # MEMORY.md loaded by an enabled-only check. (Cron agents now run with skip_memory=False and take the
  1114. # normal path here.)
  1115. _memory_toolset_requested = (
  1116. "memory" in (agent.enabled_toolsets or [])
  1117. and "memory" not in (agent.disabled_toolsets or [])
  1118. )
  1119. if not skip_memory or _memory_toolset_requested:
  1120. # Memory is optional — don't break agent init
  1121. with suppress(Exception):
  1122. from tools.memory_tool import (
  1123. MemoryStore, get_builtin_memory_config, get_builtin_memory_store_flags,
  1124. )
  1125. mem_config = get_builtin_memory_config(_agent_cfg)
  1126. agent._memory_enabled, agent._user_profile_enabled = get_builtin_memory_store_flags(
  1127. _agent_cfg
  1128. )
  1129. agent._memory_nudge_interval = int(mem_config.get("nudge_interval", 10))
  1130. if agent._memory_enabled or agent._user_profile_enabled:
  1131. agent._memory_store = MemoryStore(
  1132. memory_char_limit=mem_config.get("memory_char_limit", 2200),
  1133. user_char_limit=mem_config.get("user_char_limit", 1375),
  1134. memory_enabled=agent._memory_enabled,
  1135. user_profile_enabled=agent._user_profile_enabled,
  1136. )
  1137. agent._memory_store.load_from_disk()
  1138. # External memory provider plugin (one at a time, alongside built-in): memory.provider.
  1139. agent._memory_manager = None
  1140. if memory_manager is not None and not skip_memory:
  1141. # A caller that rebuilds the agent per turn (gateway api_server) hands back the session's
  1142. # already-initialized manager: providers keep their prefetch/retain state across turns instead
  1143. # of being re-initialized (#120116). No initialize_all — the providers are already bound.
  1144. agent._memory_manager = memory_manager
  1145. elif not skip_memory:
  1146. try:
  1147. _mem_provider_name = mem_config.get("provider", "") if mem_config else ""
  1148. if not is_core_memory_provider(_mem_provider_name):
  1149. from agent.memory_manager import MemoryManager as _MemoryManager
  1150. agent._memory_manager = _MemoryManager()
  1151. _mp = resolve_memory_provider(_mem_provider_name, say=agent._emit_startup_warning)
  1152. if _mp is not None:
  1153. agent._memory_manager.add_provider(_mp)
  1154. if agent._memory_manager.providers and agent._memory_manager.initialize_for_agent(
  1155. say=agent._emit_startup_warning, **_memory_provider_init_kwargs(agent, platform)):
  1156. _ra().logger.info("Memory provider '%s' activated", _mem_provider_name)
  1157. else:
  1158. _ra().logger.debug("Memory provider '%s' not found or not available", _mem_provider_name)
  1159. agent._memory_manager = None
  1160. except Exception as _mpe:
  1161. _ra().logger.warning("Memory provider plugin init failed: %s", _mpe)
  1162. agent._memory_manager = None
  1163. from agent.memory_manager_tools import inject_memory_provider_tools
  1164. inject_memory_provider_tools(agent)
  1165. def _apply_agent_section(agent, _agent_cfg):
  1166. # Skills config: nudge interval for skill creation reminders
  1167. agent._skill_nudge_interval = 10
  1168. with suppress(Exception):
  1169. agent._skill_nudge_interval = int(_agent_cfg.get("skills", {}).get("creation_nudge_interval", 10))
  1170. _agent_section = _cfg_dict(_agent_cfg, "agent")
  1171. agent.budget_warning_ratio = normalize_budget_warning_ratio(
  1172. _agent_section.get("budget_warning_ratio")
  1173. )
  1174. # Both: "auto" (model-list match), true, false, or list of model substrings; independent
  1175. # of each other (gates in agent/system_prompt.py).
  1176. agent._tool_use_enforcement = _agent_section.get("tool_use_enforcement", "auto")
  1177. agent._execution_guidance = _agent_section.get("execution_guidance", "auto")
  1178. # Wall-clock run budget from config — only when the constructor arg was not given.
  1179. if agent.run_budget_seconds is None:
  1180. agent.run_budget_seconds = _normalize_run_budget_seconds(
  1181. _agent_section.get("run_budget_seconds")
  1182. )
  1183. # Empty-response guard: a malformed section falls back to schema defaults (on, $0.25).
  1184. from agent.empty_response_guard import resolve_guard_settings
  1185. (
  1186. agent._empty_guard_enabled, agent._empty_guard_cost_threshold_usd
  1187. ) = resolve_guard_settings(_agent_section.get("empty_response_guard"))
  1188. # "auto" (codex_responses only), true (all api_modes), false, or model substrings.
  1189. agent._intent_ack_continuation = _agent_section.get("intent_ack_continuation", "auto")
  1190. # Responses `text.verbosity`: "" / unknown value = not sent (never flips the provider default).
  1191. _verbosity = str(_agent_section.get("text_verbosity") or "").strip().lower()
  1192. if _verbosity and _verbosity not in {"low", "medium", "high"}:
  1193. logger.warning("Unknown agent.text_verbosity %r; expected low, medium or high — ignoring", _verbosity)
  1194. _verbosity = ""
  1195. agent.text_verbosity = _verbosity or None
  1196. # Default-on boolean gates: anti-stall guards (notice-only), universal guidance toggles
  1197. # (ALL models, unlike enforcement), the local toolchain probe, Bot Mode protocol section.
  1198. for _key in (
  1199. "stall_guards", "task_completion_guidance", "parallel_tool_call_guidance",
  1200. "environment_probe", "bot_mode_protocol",
  1201. ):
  1202. setattr(agent, f"_{_key}", bool(_agent_section.get(_key, True)))
  1203. # Warm the probe (~0.5s of subprocesses) off-thread so the first prompt build finds it cached.
  1204. if agent._environment_probe:
  1205. with suppress(Exception):
  1206. from tools.env_probe import warm_environment_probe_async
  1207. warm_environment_probe_async()
  1208. # "Bot Chat" gate hint for hosts that defer the DB title write past the first prompt build.
  1209. agent._session_title_hint = None
  1210. # platform_hints: <platform>: {append|replace}, stored verbatim (agent/system_prompt.py).
  1211. agent._platform_hint_overrides = _cfg_dict(_agent_cfg, "platform_hints")
  1212. # App-level API retry count (wraps each model API call). Default 3; 1 = single attempt.
  1213. try:
  1214. _api_retries = max(int(_agent_section.get("api_max_retries", 3)), 1)
  1215. except (TypeError, ValueError):
  1216. _api_retries = 3
  1217. agent._api_max_retries = _api_retries
  1218. # Bounded post-exhaustion auto-recovery cycles once retries AND the fallback chain are spent
  1219. # on a transient outage (agent/turn_recovery_autorecover.py). 0 disables the ladder.
  1220. try:
  1221. agent._auto_recovery_cycles = max(int(_agent_section.get("auto_recovery_cycles", 5)), 0)
  1222. except (TypeError, ValueError):
  1223. agent._auto_recovery_cycles = 5
  1224. def _positive_int(raw: Any, *, reject: tuple = ()) -> Optional[int]:
  1225. """``int(raw)`` when positive, else None. ``reject`` lists types refused outright (bool, float)."""
  1226. if reject and isinstance(raw, reject):
  1227. return None
  1228. try:
  1229. parsed = int(raw)
  1230. except (TypeError, ValueError):
  1231. return None
  1232. return parsed if parsed > 0 else None
  1233. def _compression_threshold(agent, cfg: dict[str, Any]) -> tuple[float, bool]:
  1234. """Global threshold merged with the per-model override; stashes the autoraise notice.
  1235. Codex gpt-5.4/5.5 raise to 85% (272K cap → 50% would compact at ~136K); the opt-out flag
  1236. restores the global value, and the notice has its own display gate."""
  1237. threshold = float(cfg.get("threshold", 0.50))
  1238. autoraise = _cfg_flag(cfg, "codex_gpt55_autoraise", True)
  1239. notice_enabled = _cfg_flag(cfg, "codex_gpt55_autoraise_notice", True)
  1240. agent._compression_threshold_autoraised = None
  1241. with suppress(Exception):
  1242. from agent.auxiliary_client import (
  1243. _compression_threshold_for_model as _cthresh_fn,
  1244. _is_codex_gpt54_or_gpt55 as _is_codex_gpt54_or_gpt55_fn,
  1245. _is_codex_spark as _is_codex_spark_fn,
  1246. )
  1247. _model_cthresh = _cthresh_fn(
  1248. agent.model, agent.provider, allow_codex_gpt55_autoraise=autoraise,
  1249. )
  1250. # Codex autoraises apply only when they RAISE; Arcee Trinity keeps its
  1251. # unconditional override.
  1252. threshold, agent._compression_threshold_autoraised = _resolve_compression_threshold(
  1253. threshold,
  1254. _model_cthresh,
  1255. model=agent.model,
  1256. is_codex_autoraise=(
  1257. _is_codex_gpt54_or_gpt55_fn(agent.model, agent.provider)
  1258. or _is_codex_spark_fn(agent.model, agent.provider)
  1259. ),
  1260. )
  1261. return threshold, notice_enabled
  1262. def _compression_codex_settings(cfg: dict[str, Any]) -> tuple[str, bool, Optional[int]]:
  1263. """``codex_app_server_auto`` / ``codex_responses_native`` / ``codex_responses_compact_threshold``."""
  1264. app_server_auto = str(cfg.get("codex_app_server_auto", "native") or "native").lower()
  1265. if app_server_auto not in {"native", "hermes", "off"}:
  1266. _ra().logger.warning(
  1267. "Invalid compression.codex_app_server_auto=%r; using 'native'. "
  1268. "Valid values are: native, hermes, off.",
  1269. app_server_auto,
  1270. )
  1271. app_server_auto = "native"
  1272. # Native Responses server-side compaction (opt-in; gate in agent/native_compaction.py).
  1273. # Truthy coercion so "false"/"off" strings stay disabled.
  1274. responses_native = is_truthy_value(cfg.get("codex_responses_native", False))
  1275. _raw = cfg.get("codex_responses_compact_threshold")
  1276. compact_threshold = None
  1277. if _raw is not None:
  1278. compact_threshold = _positive_int(_raw, reject=(bool, float))
  1279. if compact_threshold is None:
  1280. _ra().logger.warning(
  1281. "Invalid compression.codex_responses_compact_threshold=%r; "
  1282. "using the automatic threshold derived from local compression.",
  1283. _raw,
  1284. )
  1285. return app_server_auto, responses_native, compact_threshold
  1286. def _parse_compression_config(agent, _agent_cfg) -> CompressionSettings:
  1287. """Parse the ``compression`` section. Defaults here MUST match DEFAULT_CONFIG."""
  1288. cfg = _cfg_dict(_agent_cfg, "compression")
  1289. threshold, autoraise_notice_enabled = _compression_threshold(agent, cfg)
  1290. # Plain int()/float() coercions raise on garbage; evaluated up front, in config order.
  1291. target_ratio = float(cfg.get("target_ratio", 0.20))
  1292. protect_last = int(cfg.get("protect_last_n", 20))
  1293. # max_attempts: retry rounds before "max compression attempts reached"; some sessions
  1294. # need >3 (incompressible tool schemas). Default 3, floor 1, cap 10.
  1295. max_attempts = _parse_config_int(cfg.get("max_attempts", 3), 3)
  1296. if max_attempts < 1:
  1297. max_attempts = 3
  1298. # threshold_tokens: absolute cap (lower of ratio threshold and this); clamped to the window at
  1299. # apply-time. Explicit null is the ratio-only opt-out and stays None.
  1300. threshold_tokens = cfg.get("threshold_tokens", cfg_get(DEFAULT_CONFIG, "compression", "threshold_tokens"))
  1301. if threshold_tokens is not None:
  1302. threshold_tokens = _positive_int(threshold_tokens)
  1303. # Non-system head messages to protect (system prompt is always protected); 0 is a
  1304. # legitimate "system prompt + summary + tail".
  1305. protect_first = max(0, int(cfg.get("protect_first_n", 3)))
  1306. checkpoint_required = is_truthy_value(cfg.get("checkpoint_required"), default=False)
  1307. _refuse_checkpoint_required_on_codex_app_server(
  1308. checkpoint_required, getattr(agent, "api_mode", None)
  1309. )
  1310. app_server_auto, responses_native, compact_threshold = _compression_codex_settings(cfg)
  1311. # Opt-in idle compaction: compact up front when a session resumes after this many
  1312. # seconds idle (0 = disabled). Consumed by build_turn_context().
  1313. idle_compact_after_seconds = max(0, int(cfg.get("idle_compact_after_seconds", 0)))
  1314. return CompressionSettings(
  1315. threshold=threshold,
  1316. autoraise_notice_enabled=autoraise_notice_enabled,
  1317. enabled=_cfg_flag(cfg, "enabled", True),
  1318. target_ratio=target_ratio,
  1319. protect_last=protect_last,
  1320. # "lean" keeps a clamped 2.5%/10K-25K verbatim tail (continuity rides the summary);
  1321. # "legacy" restores the 0.20*threshold tail. Unknown → lean inside the compressor.
  1322. tail_mode=str(cfg.get("tail_mode", "lean")).strip().lower(),
  1323. # Actionable user messages guaranteed to survive in the tail (default 1, floor 1).
  1324. min_tail_users=max(1, _parse_config_int(cfg.get("min_tail_user_messages", 1), 1)),
  1325. max_attempts=min(max_attempts, 10),
  1326. # Opt-in proactive tool-result prune trigger (0 = disabled; negatives = disabled).
  1327. proactive_prune_tokens=max(0, _parse_config_int(cfg.get("proactive_prune_tokens", 0), 0)),
  1328. proactive_prune_min_chars=_parse_config_int(
  1329. cfg.get("proactive_prune_min_result_chars", 8000), 8000
  1330. ),
  1331. proactive_prune_min_reclaim=max(
  1332. 0, _parse_config_int(cfg.get("proactive_prune_min_reclaim_tokens", 4096), 4096)
  1333. ),
  1334. protect_first=protect_first,
  1335. abort_on_summary_failure=_cfg_flag(cfg, "abort_on_summary_failure", False),
  1336. # Per-model threshold overrides: keys substring-matched against the model name
  1337. # (longest match wins); {} = global threshold for all models.
  1338. model_thresholds={
  1339. str(k): float(v) for k, v in _cfg_dict(cfg, "model_thresholds").items()
  1340. if isinstance(v, (int, float)) and not isinstance(v, bool)
  1341. },
  1342. threshold_tokens=threshold_tokens,
  1343. checkpoint_required=checkpoint_required,
  1344. # In-place compaction: no session-id rotation. default=True MUST match DEFAULT_CONFIG
  1345. # (a False default flipped agents into rotation mode when the key was omitted).
  1346. in_place=is_truthy_value(cfg.get("in_place"), default=True),
  1347. # Opt-in: micro-compaction rewrites sent history per turn (breaks the cache prefix).
  1348. micro_compact=is_truthy_value(cfg.get("micro_compact"), default=False),
  1349. # Pass cadence in completed turns; each pass costs one prompt-cache break (>= 1).
  1350. micro_compact_every_n_turns=max(
  1351. 1, _parse_config_int(cfg.get("micro_compact_every_n_turns", 1), 1)
  1352. ),
  1353. # Rolling-summary defrag threshold, in tokens.
  1354. micro_compact_defrag_tokens=max(
  1355. 1, _parse_config_int(cfg.get("micro_compact_defrag_threshold_tokens", 2000), 2000)
  1356. ),
  1357. codex_app_server_auto=app_server_auto,
  1358. codex_responses_native=responses_native,
  1359. codex_responses_compact_threshold=compact_threshold,
  1360. idle_compact_after_seconds=idle_compact_after_seconds,
  1361. prepare_ahead=is_truthy_value(cfg.get("prepare_ahead"), default=False),
  1362. )
  1363. def _warn_invalid_config_int(
  1364. what: str, value: Any, requirement: str, fallback: str, print_fallback: str = "",
  1365. agent: Any = None,
  1366. ) -> None:
  1367. """Log + stderr-print an invalid integer config value (``print_fallback``: user-facing
  1368. wording where it differs from the log line). The print is an automatic diagnostic and
  1369. honors the warning-notification policy; the log line never does."""
  1370. _ra().logger.warning(
  1371. "Invalid %s: %r — %s. Falling back to %s.", what, value, requirement, fallback,
  1372. )
  1373. from gateway.warning_notifications import warning_notifications_enabled
  1374. try:
  1375. if not warning_notifications_enabled(
  1376. getattr(agent, "_notification_platform", getattr(agent, "platform", "cli")),
  1377. getattr(agent, "_notification_config", None),
  1378. ):
  1379. return
  1380. except Exception:
  1381. pass
  1382. print(
  1383. f"\n⚠ Invalid {what}: {value!r}\n"
  1384. f" {requirement[0].upper() + requirement[1:]}.\n"
  1385. f" Falling back to {print_fallback or fallback}.\n",
  1386. file=sys.stderr,
  1387. )
  1388. def _custom_provider_configured_base_url(
  1389. _configured_provider: str, _agent_cfg, _custom_providers
  1390. ) -> str:
  1391. """Base URL of a named custom provider (``providers.<name>`` first, then
  1392. ``custom_providers``), normalized for route comparison; "" if unknown.
  1393. Disabled ``providers.*`` entries also mask their ``custom_providers`` twin.
  1394. """
  1395. _wanted = _normalize_custom_provider_name(_configured_provider)
  1396. _user_providers = _agent_cfg.get("providers")
  1397. _disabled_ids: set[str] = set()
  1398. if isinstance(_user_providers, dict):
  1399. from hermes_cli.config import is_provider_enabled
  1400. for _key, _entry in _user_providers.items():
  1401. if not isinstance(_entry, dict):
  1402. continue
  1403. _ids = _custom_provider_runtime_ids(_key) | _custom_provider_runtime_ids(_entry.get("name"))
  1404. if not is_provider_enabled(_entry):
  1405. _disabled_ids.update(_ids)
  1406. continue
  1407. if _wanted in _ids:
  1408. _url = normalize_route_base_url(
  1409. _entry.get("api") or _entry.get("url") or _entry.get("base_url")
  1410. )
  1411. if _url:
  1412. return _url
  1413. for _entry in _custom_providers:
  1414. if not isinstance(_entry, dict):
  1415. continue
  1416. _key_ids = _custom_provider_runtime_ids(_entry.get("provider_key"))
  1417. if _key_ids & _disabled_ids:
  1418. continue
  1419. if _wanted in _key_ids | _custom_provider_runtime_ids(_entry.get("name")):
  1420. _url = normalize_route_base_url(_entry.get("base_url"))
  1421. if _url:
  1422. return _url
  1423. return ""
  1424. # Provider ids whose runtime is resolved first-hand (never a named custom provider).
  1425. _RUNTIME_FIRST_PROVIDER_IDS = {
  1426. "auto", "moa", "vertex", "google-vertex", "vertex-ai", "gcp-vertex", "vertexai",
  1427. }
  1428. def _configured_default_base_url(_agent_cfg, _model_cfg, _custom_providers) -> str:
  1429. """Normalized route of the configured default model (``model.base_url``, else the named
  1430. custom provider's URL when ``model.provider`` is not a first-class/auth provider)."""
  1431. _configured_base_url = normalize_route_base_url(_model_cfg.get("base_url"))
  1432. _configured_provider = str(_model_cfg.get("provider") or "").strip()
  1433. _norm = _normalize_custom_provider_name(_configured_provider)
  1434. _custom_provider_candidate = bool(_norm)
  1435. if _norm in _RUNTIME_FIRST_PROVIDER_IDS:
  1436. _custom_provider_candidate = False
  1437. elif _custom_provider_candidate and _norm != "custom" and not _norm.startswith("custom:"):
  1438. with suppress(Exception):
  1439. from hermes_cli.auth import resolve_provider as resolve_auth_provider
  1440. _custom_provider_candidate = (
  1441. str(resolve_auth_provider(_norm) or "").strip().lower() != _norm
  1442. )
  1443. if not _configured_base_url and _custom_provider_candidate:
  1444. _configured_base_url = _custom_provider_configured_base_url(
  1445. _configured_provider, _agent_cfg, _custom_providers
  1446. )
  1447. return _configured_base_url
  1448. def _active_route_url(agent, base_url) -> str:
  1449. """The runtime route, keeping the requested URL's query string when it is the same route."""
  1450. _active = str(agent.base_url or "")
  1451. _requested = str(base_url or "")
  1452. if "?" in _requested.split("#", 1)[0]:
  1453. with suppress(TypeError, ValueError):
  1454. _without_query = urlunparse(urlparse(_requested)._replace(query=""))
  1455. if normalize_route_base_url(_without_query) == normalize_route_base_url(_active):
  1456. _active = _requested
  1457. return normalize_route_base_url(_active)
  1458. def _scope_context_length_to_default_runtime(
  1459. agent, _agent_cfg, _model_cfg, _custom_providers, _config_context_length, base_url
  1460. ) -> Optional[int]:
  1461. """Return ``model.context_length`` only if it describes the active runtime.
  1462. It describes the configured default model; a ``--model`` launch has already replaced
  1463. ``agent.model``, so carrying the default's window into that runtime is stale. Live
  1464. switch/fallback paths already clear it — direct-start stays consistent with them.
  1465. """
  1466. _default = _model_cfg.get("default")
  1467. if isinstance(_default, dict):
  1468. from hermes_cli.config import split_model_config_default
  1469. _default, _ = split_model_config_default(_default)
  1470. _configured_default_model = str(_default or "").strip()
  1471. _configured_default_runtime_model = _configured_default_model
  1472. _active_runtime_model = agent.model
  1473. if _configured_default_model:
  1474. with suppress(Exception):
  1475. from hermes_cli.model_normalize import normalize_model_for_provider
  1476. _configured_default_runtime_model = normalize_model_for_provider(
  1477. _configured_default_model, agent.provider
  1478. )
  1479. _active_runtime_model = normalize_model_for_provider(agent.model, agent.provider)
  1480. _configured_base_url = _configured_default_base_url(_agent_cfg, _model_cfg, _custom_providers)
  1481. _active_base_url = _active_route_url(agent, base_url)
  1482. _route_mismatch = _context_route_mismatch(
  1483. _configured_base_url, _active_base_url, str(_model_cfg.get("provider") or "").strip(),
  1484. agent.provider, already_normalized=True,
  1485. )
  1486. _model_mismatch = bool(
  1487. _configured_default_runtime_model
  1488. and _configured_default_runtime_model != _active_runtime_model
  1489. )
  1490. if _model_mismatch or _route_mismatch:
  1491. _ra().logger.debug(
  1492. "Ignoring model.context_length=%s for startup runtime %s at %s "
  1493. "(configured default is %s at %s)",
  1494. _config_context_length,
  1495. agent.model,
  1496. _active_base_url or agent.provider,
  1497. _configured_default_model,
  1498. _configured_base_url or _model_cfg.get("provider"),
  1499. )
  1500. return None
  1501. return _config_context_length
  1502. def set_config_context_length(agent, value: Optional[int]) -> None:
  1503. """Store the durable ``model.context_length`` pin on EVERY cached copy of it.
  1504. The pin is read from config exactly once, at construction, then cached twice: on
  1505. ``agent._config_context_length`` (switch/fallback resolution plus every display and ``/usage``
  1506. surface) and on ``context_compressor._config_context_length`` (the compressor's own
  1507. re-resolution). Live paths that updated only one copy left the other stale, so a session could
  1508. report a pinned ceiling while compressing against a different window (#116467).
  1509. """
  1510. agent._config_context_length = value
  1511. _compressor = getattr(agent, "context_compressor", None)
  1512. if _compressor is not None:
  1513. _compressor._config_context_length = value
  1514. def config_context_length_for_runtime(agent, config=None) -> Optional[int]:
  1515. """Re-read the durable ``model.context_length`` pin for ``agent``'s CURRENT runtime, or ``None``.
  1516. Single re-derivation point for the cached pin: construction resolves it once, and every live path
  1517. that re-resolves a runtime used to clear the cached copy without re-reading the config — so a
  1518. model/provider switch or a Desktop config round-trip silently dropped a ceiling the user still had
  1519. on disk, and resolution fell through to probing / catalog metadata / the 256K fallback (#116467).
  1520. Reuses construction's own scoping (``_scope_context_length_to_default_runtime``): the pin describes
  1521. the configured default route, so an unrelated runtime never inherits it.
  1522. """
  1523. try:
  1524. from hermes_cli.config import get_compatible_custom_providers, load_config
  1525. _agent_cfg = config if isinstance(config, dict) else load_config()
  1526. if not isinstance(_agent_cfg, dict):
  1527. return None
  1528. _model_section = _agent_cfg.get("model", {})
  1529. if not isinstance(_model_section, dict):
  1530. return None
  1531. _pin = _model_section.get("context_length")
  1532. if _pin is None or isinstance(_pin, bool):
  1533. return None
  1534. _pin = int(_pin)
  1535. if _pin <= 0:
  1536. return None
  1537. return _scope_context_length_to_default_runtime(
  1538. agent, _agent_cfg, _model_section, get_compatible_custom_providers(_agent_cfg),
  1539. _pin, str(getattr(agent, "base_url", "") or ""),
  1540. )
  1541. except Exception:
  1542. logger.debug("Could not re-read model.context_length for the current runtime", exc_info=True)
  1543. return None
  1544. _CTX_LEN_REQUIREMENT = "must be a positive integer (e.g. 256000, not '256K')"
  1545. def _warn_invalid_custom_provider_context_length(agent, _custom_providers) -> None:
  1546. """Surface a context_length the helper silently skipped (not a positive int)."""
  1547. _target = normalize_route_base_url(agent.base_url)
  1548. if not _target:
  1549. return
  1550. for _cp_entry in _custom_providers:
  1551. if not isinstance(_cp_entry, dict):
  1552. continue
  1553. if normalize_route_base_url(_cp_entry.get("base_url")) != _target:
  1554. continue
  1555. _cp_models = _cp_entry.get("models", {})
  1556. _cp_model_cfg = _cp_models.get(agent.model, {}) if isinstance(_cp_models, dict) else None
  1557. _cp_ctx = _cp_model_cfg.get("context_length") if isinstance(_cp_model_cfg, dict) else None
  1558. if _cp_ctx is not None and _positive_int(_cp_ctx) is None:
  1559. _warn_invalid_config_int(
  1560. f"context_length for model {agent.model!r} in custom_providers",
  1561. _cp_ctx, _CTX_LEN_REQUIREMENT, "auto-detection", "auto-detected context window",
  1562. agent=agent,
  1563. )
  1564. return
  1565. def _resolve_context_length(agent, _agent_cfg, base_url):
  1566. # Aux compression model context_length hint (custom endpoints often can't report it).
  1567. try:
  1568. _aux_cfg = cfg_get(_agent_cfg, "auxiliary", "compression", default={})
  1569. except Exception:
  1570. _aux_cfg = {}
  1571. _aux_ctx = _aux_cfg.get("context_length") if isinstance(_aux_cfg, dict) else None
  1572. try:
  1573. agent._aux_compression_context_length_config = int(_aux_ctx) if _aux_ctx is not None else None
  1574. except (TypeError, ValueError):
  1575. agent._aux_compression_context_length_config = None
  1576. _model_cfg = _agent_cfg.get("model", {})
  1577. _model_section = _model_cfg if isinstance(_model_cfg, dict) else {}
  1578. _config_context_length = _model_section.get("context_length")
  1579. if _config_context_length is not None:
  1580. try:
  1581. _config_context_length = int(_config_context_length)
  1582. except (TypeError, ValueError):
  1583. _warn_invalid_config_int(
  1584. "model.context_length in config.yaml", _config_context_length,
  1585. "must be a plain integer (e.g. 256000, not '256K')",
  1586. "auto-detection", "auto-detected context window", agent=agent,
  1587. )
  1588. _config_context_length = None
  1589. # Resolve custom_providers before route-scoping: a named provider may keep its URL here.
  1590. try:
  1591. from hermes_cli.config import get_compatible_custom_providers
  1592. _custom_providers = get_compatible_custom_providers(_agent_cfg)
  1593. except Exception:
  1594. _custom_providers = _agent_cfg.get("custom_providers")
  1595. if not isinstance(_custom_providers, list):
  1596. _custom_providers = []
  1597. # ``model.context_length`` describes the configured default model; drop it when the
  1598. # startup runtime (model or route) differs from that default.
  1599. if _config_context_length is not None:
  1600. _config_context_length = _scope_context_length_to_default_runtime(
  1601. agent, _agent_cfg, _model_section, _custom_providers, _config_context_length, base_url
  1602. )
  1603. # Reused by _check_compression_model_feasibility (aux compression model detection).
  1604. agent._custom_providers = _custom_providers
  1605. _merge_custom_provider_extra_body(agent, _custom_providers)
  1606. if _config_context_length is None and _custom_providers:
  1607. with suppress(Exception):
  1608. from hermes_cli.config import get_custom_provider_context_length
  1609. _cp_ctx_resolved = get_custom_provider_context_length(
  1610. model=agent.model, base_url=agent.base_url, custom_providers=_custom_providers
  1611. )
  1612. if _cp_ctx_resolved:
  1613. _config_context_length = int(_cp_ctx_resolved)
  1614. if _config_context_length is None:
  1615. _warn_invalid_custom_provider_context_length(agent, _custom_providers)
  1616. # Persisted for switch_model / fallback AFTER the custom_providers branch (per-model overrides).
  1617. agent._config_context_length = _config_context_length
  1618. if _config_context_length is not None:
  1619. from agent.context_pin import warn_once_on_pin_disagreement
  1620. warn_once_on_pin_disagreement(agent.model, agent.base_url or "", _config_context_length)
  1621. _lmstudio_runtime_context_length = agent._ensure_lmstudio_runtime_loaded(_config_context_length)
  1622. if agent._lmstudio_load_was_unverified(_lmstudio_runtime_context_length):
  1623. _ra().logger.warning(
  1624. "LM Studio model activation was rejected or completed without a "
  1625. "verifiable active context length; falling back to configured context"
  1626. )
  1627. _effective_context_length = agent._effective_lmstudio_context_length(
  1628. _config_context_length, _lmstudio_runtime_context_length,
  1629. )
  1630. return _config_context_length, _custom_providers, _effective_context_length, _model_cfg
  1631. def _select_context_engine(_agent_cfg):
  1632. """Config-driven context engine: ``context.engine`` → plugins/context_engine/<name>/ →
  1633. general plugin system → None (built-in ContextCompressor)."""
  1634. from agent.safe_worker_policy import safe_worker_enabled
  1635. if safe_worker_enabled():
  1636. return None
  1637. _engine_name = "compressor"
  1638. with suppress(Exception):
  1639. _ctx_cfg = _agent_cfg.get("context", {}) if isinstance(_agent_cfg, dict) else {}
  1640. _engine_name = _ctx_cfg.get("engine", "compressor") or "compressor"
  1641. if _engine_name == "compressor":
  1642. return None # built-in; don't auto-activate plugins
  1643. _selected_engine = None
  1644. _copy_failed = False
  1645. try:
  1646. from plugins.context_engine import load_context_engine
  1647. _selected_engine = load_context_engine(_engine_name)
  1648. except Exception as _ce_load_err:
  1649. _ra().logger.debug("Context engine load from plugins/context_engine/: %s", _ce_load_err)
  1650. if _selected_engine is None:
  1651. try:
  1652. from hermes_cli.plugins import get_plugin_context_engine
  1653. _candidate = get_plugin_context_engine()
  1654. except Exception:
  1655. _candidate = None
  1656. if _candidate is not None and _candidate.name == _engine_name:
  1657. # The plugin system holds ONE shared instance; each agent gets its own so a child's
  1658. # update_model() can't mutate the parent's (#42449). clone_for_agent() defaults to
  1659. # deepcopy; engines with uncopyable state (locks, DB conns) override it. A failure
  1660. # falls back to the built-in compressor with an ACCURATE message, not "not found".
  1661. try:
  1662. _selected_engine = _candidate.clone_for_agent()
  1663. except Exception as _copy_err:
  1664. _copy_failed = True
  1665. _ra().logger.warning(
  1666. "Context engine '%s' could not be safely copied for this "
  1667. "agent (%s) — falling back to built-in compressor. Plugin "
  1668. "engines that hold uncopyable state (locks, DB connections) "
  1669. "should override clone_for_agent() (or __deepcopy__) to copy "
  1670. "only mutable budget state.",
  1671. _engine_name, _copy_err,
  1672. )
  1673. if _selected_engine is None and not _copy_failed:
  1674. _ra().logger.warning(
  1675. "Context engine '%s' not found — falling back to built-in compressor", _engine_name
  1676. )
  1677. return _selected_engine
  1678. def _compressor_max_tokens(agent):
  1679. """``agent.max_tokens``, or the native-Gemini adapter default when unset: generateContent
  1680. still sends maxOutputTokens=65,535 and the threshold is pct×(window − max_tokens), so
  1681. reserving 0 let the provider 400 before compaction fired."""
  1682. if agent.max_tokens is not None:
  1683. return agent.max_tokens
  1684. with suppress(Exception):
  1685. from agent.gemini_native_adapter import (
  1686. GEMINI_DEFAULT_MAX_OUTPUT_TOKENS, is_native_gemini_base_url
  1687. )
  1688. _gemini_provider = str(agent.provider or "").strip().lower() in {
  1689. "gemini", "google", "google-gemini", "google-ai-studio",
  1690. }
  1691. if _gemini_provider or is_native_gemini_base_url(agent.base_url):
  1692. return GEMINI_DEFAULT_MAX_OUTPUT_TOKENS
  1693. return None
  1694. def _build_context_engine(agent, _agent_cfg, cs, _custom_providers, _effective_context_length, session_db):
  1695. _selected_engine = _select_context_engine(_agent_cfg)
  1696. if _selected_engine is not None:
  1697. agent.context_compressor = _selected_engine
  1698. # External engines own compaction policy — the host threshold (and its Codex
  1699. # autoraise) never reaches the plugin, so drop the notice.
  1700. agent._compression_threshold_autoraised = None
  1701. # External engines own compaction policy: the host compression threshold (including the Codex
  1702. # gpt-5.5 autoraise above) only configures the built-in ContextCompressor and never reaches the
  1703. # plugin, so the autoraise notice would announce a change that does not apply. (#44439)
  1704. from agent.model_metadata import get_model_context_length
  1705. _plugin_ctx_len = get_model_context_length(
  1706. agent.model, base_url=agent.base_url, api_key=getattr(agent, "api_key", ""),
  1707. config_context_length=_effective_context_length, provider=agent.provider,
  1708. custom_providers=_custom_providers,
  1709. )
  1710. # Per-model overrides BEFORE the initial update_model() so the first threshold
  1711. # resolution already sees them.
  1712. if cs.model_thresholds:
  1713. agent.context_compressor.model_thresholds = cs.model_thresholds
  1714. agent.context_compressor.update_model(
  1715. model=agent.model, context_length=_plugin_ctx_len, base_url=agent.base_url,
  1716. api_key=getattr(agent, "api_key", ""), provider=agent.provider, api_mode=agent.api_mode,
  1717. )
  1718. if not agent.quiet_mode:
  1719. _ra().logger.info("Using context engine: %s", _selected_engine.name)
  1720. else:
  1721. agent.context_compressor = ContextCompressor(
  1722. model=agent.model, threshold_percent=cs.threshold, protect_first_n=cs.protect_first,
  1723. protect_last_n=cs.protect_last, summary_target_ratio=cs.target_ratio,
  1724. summary_model_override=None, quiet_mode=agent.quiet_mode, base_url=agent.base_url,
  1725. api_key=getattr(agent, "api_key", ""), config_context_length=_effective_context_length,
  1726. provider=agent.provider, api_mode=agent.api_mode,
  1727. abort_on_summary_failure=cs.abort_on_summary_failure,
  1728. max_tokens=_compressor_max_tokens(agent), model_thresholds=cs.model_thresholds,
  1729. threshold_tokens_cap=cs.threshold_tokens,
  1730. proactive_prune_tokens=cs.proactive_prune_tokens,
  1731. proactive_prune_min_result_chars=cs.proactive_prune_min_chars,
  1732. proactive_prune_min_reclaim_tokens=cs.proactive_prune_min_reclaim,
  1733. min_tail_user_messages=cs.min_tail_users, tail_mode=cs.tail_mode,
  1734. custom_providers=_custom_providers,
  1735. )
  1736. _bind_session_state = getattr(agent.context_compressor, "bind_session_state", None)
  1737. if callable(_bind_session_state):
  1738. with suppress(Exception):
  1739. _bind_session_state(session_db=session_db, session_id=agent.session_id)
  1740. agent.compression_enabled = cs.enabled
  1741. agent.compression_in_place = cs.in_place
  1742. _cc = agent.context_compressor
  1743. # Micro-compaction has no pre-compress checkpoint hook; suppress it while the gate is
  1744. # armed (mirrors native_compaction.py).
  1745. if cs.checkpoint_required and cs.micro_compact:
  1746. logger.warning(
  1747. "compression.checkpoint_required is enabled: post-turn "
  1748. "micro-compaction is disabled for this agent so every lossy "
  1749. "rewrite passes through the checkpoint-gated compressor."
  1750. )
  1751. cs.micro_compact = False
  1752. for _attr, _value in (
  1753. ("_micro_compact_enabled", cs.micro_compact),
  1754. ("_micro_compact_every_n_turns", cs.micro_compact_every_n_turns),
  1755. ("_micro_compact_defrag_threshold_tokens", cs.micro_compact_defrag_tokens),
  1756. ):
  1757. if hasattr(_cc, _attr):
  1758. setattr(_cc, _attr, _value)
  1759. if cs.prepare_ahead and isinstance(_cc, ContextCompressor):
  1760. from agent.prepared_compaction import PreparedCompaction
  1761. _cc.prepared_compaction = PreparedCompaction()
  1762. agent.compression_checkpoint_required = cs.checkpoint_required
  1763. from agent.conversation_compression_checkpoint import _warn_checkpoint_required_without_capable_provider
  1764. _warn_checkpoint_required_without_capable_provider(agent)
  1765. agent.codex_app_server_auto_compaction = cs.codex_app_server_auto
  1766. agent.codex_responses_native_compaction = cs.codex_responses_native
  1767. agent.codex_responses_compact_threshold = cs.codex_responses_compact_threshold
  1768. from agent.native_compaction import resolve_native_compaction_capabilities
  1769. agent.runtime_capabilities = resolve_native_compaction_capabilities(
  1770. model=agent.model, base_url=agent.base_url, provider=agent.provider,
  1771. is_codex_backend=(agent.provider or "").strip().lower() == "openai-codex",
  1772. )
  1773. agent.max_compression_attempts = cs.max_attempts
  1774. agent.compression_idle_compact_after_seconds = cs.idle_compact_after_seconds
  1775. def _enforce_minimum_context(agent):
  1776. # Reject windows below the 64K floor needed for reliable tool-calling; an explicit
  1777. # positive model.context_length on LM Studio is allowed below the floor.
  1778. _ctx = getattr(agent.context_compressor, "context_length", 0)
  1779. # A local Ollama server serves num_ctx, not the GGUF's advertised window: a Modelfile or
  1780. # model.ollama_num_ctx at 64K+ is a usable window even when the metadata says 40K (#100437).
  1781. # Only a local endpoint can honour num_ctx, so a stale override never admits a hosted model.
  1782. if agent._ollama_num_ctx and agent.base_url and is_local_endpoint(agent.base_url):
  1783. _ctx = max(_ctx or 0, agent._ollama_num_ctx)
  1784. _allow_lmstudio_explicit_below_floor = (
  1785. str(agent.provider or "").strip().lower() == "lmstudio"
  1786. and isinstance(agent._config_context_length, int)
  1787. and not isinstance(agent._config_context_length, bool)
  1788. and agent._config_context_length > 0
  1789. )
  1790. if _ctx and _ctx < MINIMUM_CONTEXT_LENGTH and not _allow_lmstudio_explicit_below_floor:
  1791. floor_k = MINIMUM_CONTEXT_LENGTH // 1000
  1792. if agent.base_url and is_local_endpoint(agent.base_url):
  1793. # Any OpenAI-compatible local server (llama.cpp, vLLM, Ollama, ...) — the window is the
  1794. # server's runtime setting, not the model's; never assume Ollama here (#87075).
  1795. remedy = (
  1796. f"Your local server is serving a {_ctx:,}-token window. Start it with at least "
  1797. f"{floor_k}K context (llama.cpp: -c {MINIMUM_CONTEXT_LENGTH}; vLLM: --max-model-len; "
  1798. f"Ollama: OLLAMA_CONTEXT_LENGTH={MINIMUM_CONTEXT_LENGTH} or a Modelfile num_ctx), "
  1799. f"or set model.ollama_num_ctx in config.yaml to the window it really serves "
  1800. f"(at least {floor_k}K)."
  1801. )
  1802. else:
  1803. remedy = (
  1804. f"Choose a model with at least {floor_k}K context. If your server "
  1805. f"reports a window smaller than the model's true window, set "
  1806. f"model.context_length in config.yaml to the real value "
  1807. f"(this must be at least {floor_k}K)."
  1808. )
  1809. raise ValueError(
  1810. f"Model {agent.model} has a context window of {_ctx:,} tokens, "
  1811. f"which is below the minimum {MINIMUM_CONTEXT_LENGTH:,} required "
  1812. f"by Hermes Agent. {remedy}"
  1813. )
  1814. def _warn_nonagentic_hermes_model(agent):
  1815. # Nous Hermes 3/4 are chat models, not tool-call-tuned. cli.py show_banner() already
  1816. # warns on the CLI, so skip platform=="cli"; non-quiet non-CLI surfaces still get it.
  1817. if agent.quiet_mode or (agent.platform or "cli") == "cli":
  1818. return
  1819. with suppress(Exception):
  1820. from hermes_cli.model_switch import _check_hermes_model_warning
  1821. _hermes_warn = _check_hermes_model_warning(agent.model or "")
  1822. if _hermes_warn:
  1823. _user_msg = (
  1824. "⚠ Nous Research Hermes 3 & 4 models are NOT agentic — they "
  1825. "lack reliable tool-calling for agent workflows (delegation, "
  1826. "cron, proactive tools). Consider an agentic model instead "
  1827. "(Claude, GPT, Gemini, Qwen-Coder, etc.)."
  1828. )
  1829. agent._emit_warning(_user_msg)
  1830. _ra().logger.warning(_hermes_warn)
  1831. def _inject_context_engine_tools(agent):
  1832. # Context engine tool schemas (lcm_*), deduped against existing names (plugins may
  1833. # register the same schemas; duplicates 400 provider-side) and gated on enabled_toolsets
  1834. # so `platform_toolsets: telegram: []` can't leak them.
  1835. # Skip names that are already present — the model_tools.get_tool_definitions() quiet_mode cache returned a
  1836. # shared list pre-#17335, so a stray mutation here would poison subsequent agent inits in the same
  1837. # Gateway process and trip provider-side 'duplicate tool name' errors. Even with the cache fix, dedup is
  1838. # the right defense against plugin paths that may register the same schemas via ctx.register_tool().
  1839. # Mirrors the memory tools dedup above. Respect the platform's enabled_toolsets configuration (#5544):
  1840. # context engine tools follow the same gating pattern as memory provider tools — without the gate,
  1841. # `platform_toolsets: telegram: []` would still leak lcm_* tools into the tool surface and incur the
  1842. # same local-model latency penalty.
  1843. agent._context_engine_tool_names: set = set()
  1844. if (
  1845. agent.context_compressor
  1846. and agent.tools is not None
  1847. and (agent.enabled_toolsets is None or "context_engine" in agent.enabled_toolsets)
  1848. ):
  1849. _existing_tool_names = {
  1850. t.get("function", {}).get("name") for t in agent.tools if isinstance(t, dict)
  1851. }
  1852. from agent.memory_manager_tools import normalize_tool_schema
  1853. for _raw_schema in agent.context_compressor.get_tool_schemas():
  1854. _schema = normalize_tool_schema(_raw_schema)
  1855. if _schema is None:
  1856. # A nameless tool makes strict providers 400 and disables the whole toolset.
  1857. _ra().logger.warning(
  1858. # Skip it. See #47707.
  1859. "Context engine returned a tool schema with no resolvable "
  1860. "name; skipping to avoid poisoning the request (%r)",
  1861. _raw_schema,
  1862. )
  1863. continue
  1864. _tname = _schema["name"]
  1865. if _tname in _existing_tool_names:
  1866. continue # already registered via plugin/cache path
  1867. agent.tools.append({"type": "function", "function": _schema})
  1868. for _names in (agent.valid_tool_names, agent._context_engine_tool_names, _existing_tool_names):
  1869. _names.add(_tname)
  1870. if agent.context_compressor:
  1871. try:
  1872. agent.context_compressor.on_session_start(
  1873. agent.session_id, hermes_home=str(get_hermes_home()),
  1874. platform=agent.platform or "cli", model=agent.model,
  1875. context_length=getattr(agent.context_compressor, "context_length", 0),
  1876. conversation_id=getattr(agent, "_gateway_session_key", None),
  1877. )
  1878. except Exception as _ce_err:
  1879. _ra().logger.debug("Context engine on_session_start: %s", _ce_err)
  1880. def _init_usage_state(agent):
  1881. from agent.runtime_cwd import scope_terminal_cwd
  1882. # Prefer the session's explicitly adopted workspace (a Desktop session created under the
  1883. # spawn-time home pin records none; a picked/adopted one does — agent.session_cwd is set
  1884. # at build time and on every workspace move). TERMINAL_CWD is the launch fallback.
  1885. working_dir = getattr(agent, "session_cwd", None) or scope_terminal_cwd() or None
  1886. agent._subdirectory_hints = SubdirectoryHintTracker(
  1887. working_dir=working_dir, enabled=not agent.skip_context_files)
  1888. _set_defaults(agent, _USAGE_STATE)
  1889. # Per-session usage accounting.
  1890. _USAGE_STATE: dict[str, Any] = {
  1891. "_user_turn_count": 0,
  1892. "_is_user_initiated_turn": False, # first API call of a user turn (provider request_headers attribution)
  1893. # Usage anchors (agent/usage_anchor.py): last response's exact usage + transcript
  1894. # snapshot; invalidated on compaction/session switch so stale anchors never suppress compression.
  1895. "_usage_anchor": None,
  1896. "_turn_base_usage_anchor": None,
  1897. "_request_pressure_anchored": False, # whether the last pressure figure came from the anchor
  1898. # Cumulative token usage for the session
  1899. "session_prompt_tokens": 0,
  1900. "session_completion_tokens": 0,
  1901. "session_total_tokens": 0,
  1902. "session_api_calls": 0,
  1903. "session_input_tokens": 0,
  1904. "session_output_tokens": 0,
  1905. "session_cache_read_tokens": 0,
  1906. "session_cache_write_tokens": 0,
  1907. "session_reasoning_tokens": 0,
  1908. "session_estimated_cost_usd": 0.0,
  1909. "session_cost_status": "unknown",
  1910. "session_cost_source": "none",
  1911. # Status-bar latency/velocity history (last 10 calls), shared by loop + codex_runtime.
  1912. "_api_latency_history": lambda: deque(maxlen=10),
  1913. "_api_output_history": lambda: deque(maxlen=10),
  1914. }
  1915. def init_agent(
  1916. agent, base_url: str | None = None, api_key: str | None = None, provider: str | None = None, api_mode: str | None = None,
  1917. acp_command: str | None = None, acp_args: list[str] | None = None, command: str | None = None,
  1918. args: list[str] | None = None, model: str = "", max_iterations: int = sys.maxsize,
  1919. enabled_toolsets: list[str] | None = None, disabled_toolsets: list[str] | None = None,
  1920. save_trajectories: bool = False, verbose_logging: bool = False, quiet_mode: bool = False,
  1921. tool_progress_mode: str = "all", ephemeral_system_prompt: str | None = None,
  1922. log_prefix_chars: int = 100, log_prefix: str = "", providers_allowed: list[str] | None = None,
  1923. providers_ignored: list[str] | None = None, providers_order: list[str] | None = None,
  1924. provider_sort: str | None = None, provider_require_parameters: bool = False,
  1925. provider_data_collection: str | None = None, openrouter_min_coding_score: Optional[float] = None,
  1926. session_id: str | None = None, tool_progress_callback: Callable[..., Any] | None = None,
  1927. tool_start_callback: Callable[..., Any] | None = None, tool_complete_callback: Callable[..., Any] | None = None,
  1928. thinking_callback: Callable[..., Any] | None = None, reasoning_callback: Callable[..., Any] | None = None,
  1929. clarify_callback: Callable[..., Any] | None = None, read_terminal_callback: Callable[..., Any] | None = None,
  1930. read_preview_callback: Callable[..., Any] | None = None, drive_preview_callback: Callable[..., Any] | None = None,
  1931. read_window_below_callback: Callable[..., Any] | None = None, connection_callback: Callable[..., Any] | None = None,
  1932. tour_callback: Callable[..., Any] | None = None, theme_callback: Callable[..., Any] | None = None,
  1933. setup_beat_callback: Callable[..., Any] | None = None,
  1934. step_callback: Callable[..., Any] | None = None,
  1935. stream_delta_callback: Callable[..., Any] | None = None, interim_assistant_callback: Callable[..., Any] | None = None,
  1936. tool_gen_callback: Callable[..., Any] | None = None, status_callback: Callable[..., Any] | None = None,
  1937. notice_callback: Callable[..., Any] | None = None, notice_clear_callback: Callable[..., Any] | None = None,
  1938. event_callback: Optional[Callable[[str, dict], None]] = None,
  1939. reaction_callback: Optional[Callable[[str], None]] = None, max_tokens: int | None = None,
  1940. reasoning_config: dict[str, Any] | None = None, service_tier: str | None = None,
  1941. request_overrides: dict[str, Any] | None = None, prefill_messages: list[dict[str, Any]] | None = None,
  1942. platform: str | None = None, user_id: str | None = None, user_id_alt: str | None = None, user_name: str | None = None,
  1943. chat_id: str | None = None, chat_name: str | None = None, chat_type: str | None = None, thread_id: str | None = None,
  1944. gateway_session_key: str | None = None, skip_context_files: bool = False,
  1945. load_soul_identity: bool = False, skip_memory: bool = False,
  1946. skip_background_review: bool = False, session_db=None, parent_session_id: str | None = None,
  1947. iteration_budget: IterationBudget = None, run_budget_seconds: Optional[float] = None,
  1948. fallback_model: dict[str, Any] | None = None, credential_pool=None, checkpoints_enabled: bool = False,
  1949. checkpoint_max_snapshots: int = 20, checkpoint_max_total_size_mb: int = 500,
  1950. checkpoint_max_file_size_mb: int = 10, pass_session_id: bool = False,
  1951. requested_provider: str | None = None, capabilities: Optional[dict[str, bool]] = None, cwd: Optional[str] = None,
  1952. side_agent: bool = False, memory_manager=None,
  1953. tool_result_metadata_callback: Optional[Callable[..., dict]] = None,
  1954. ):
  1955. from agent.safe_worker_policy import safe_worker_enabled
  1956. if safe_worker_enabled():
  1957. skip_context_files = skip_memory = skip_background_review = True
  1958. load_soul_identity = False
  1959. prefill_messages = []
  1960. fallback_model = {}
  1961. _install_safe_stdio()
  1962. _params = locals()
  1963. for _name in _PASSTHROUGH_PARAMS:
  1964. setattr(agent, _name, _params[_name])
  1965. for _name in _GATEWAY_IDENTITY_PARAMS:
  1966. setattr(agent, f"_{_name}", _params[_name])
  1967. agent.session_cwd = cwd or None
  1968. # Shared iteration budget: parent creates, children inherit.
  1969. agent.iteration_budget = iteration_budget or IterationBudget(max_iterations)
  1970. # CLI replaces this with _cprint so raw ANSI status lines go through prompt_toolkit's
  1971. # renderer (StdoutProxy would mangle them). None = builtins.print.
  1972. agent._print_fn = None
  1973. agent.background_review_callback = None # Optional sync callback for gateway delivery
  1974. agent.memory_notifications = "on" # Memory update notifications: "off", "on", "verbose"
  1975. # Skips the end-of-turn review fork (~30K tokens/event); one switch for both review paths.
  1976. agent.skip_background_review = bool(skip_background_review)
  1977. agent.log_prefix = f"{log_prefix} " if log_prefix else ""
  1978. # Effective base URL for feature detection (prompt caching, reasoning, etc.)
  1979. from hermes_cli.providers import is_actual_route
  1980. if is_actual_route(provider, base_url):
  1981. from hermes_cli.auth import normalize_actual_base_url
  1982. base_url = normalize_actual_base_url(base_url)
  1983. agent.base_url = base_url or ""
  1984. provider_name = provider.strip().lower() if isinstance(provider, str) and provider.strip() else None
  1985. agent.provider = provider_name or ""
  1986. agent.requested_provider = (
  1987. requested_provider.strip().lower()
  1988. if isinstance(requested_provider, str) and requested_provider.strip()
  1989. else agent.provider
  1990. )
  1991. agent.capabilities = {
  1992. key: value for key, value in (capabilities or {}).items()
  1993. if isinstance(key, str) and isinstance(value, bool)
  1994. }
  1995. agent._credential_pool = credential_pool
  1996. agent.acp_command = acp_command or command
  1997. agent.acp_args = list(acp_args or args or [])
  1998. _resolve_api_mode(agent, api_mode, provider_name, base_url)
  1999. _finalize_routing(agent, api_mode, credential_pool)
  2000. # Platform callbacks are stored under their parameter names verbatim.
  2001. for _cb in _CALLBACK_PARAMS:
  2002. setattr(agent, _cb, _params[_cb])
  2003. agent.suppress_status_output = False
  2004. _set_defaults(agent, _CONTROL_STATE)
  2005. # Early config readers must reach the file handlers on first initialization.
  2006. _setup_logging(agent)
  2007. # reasoning_content echo opt-in; switch_model / fallback / restore keep it in sync.
  2008. agent._reasoning_echo_flag = agent._read_reasoning_echo_from_config()
  2009. agent.request_overrides = dict(request_overrides or {})
  2010. agent.prefill_messages = prefill_messages or [] # Prefilled conversation turns
  2011. agent._force_ascii_payload = False
  2012. # Routes that rejected image content / named reasoning keys; build_api_request strips those from wire copies only.
  2013. agent._image_rejecting_models = set()
  2014. agent._reasoning_rejecting_routes = {} # (provider, host, model) -> rejected reasoning keys
  2015. # Models whose Anthropic organization answered a fast request with a fast-mode limit of 0;
  2016. # agent.fast_mode stops sending ``speed`` to them for the rest of the session.
  2017. agent._fast_mode_unavailable_models = set()
  2018. _init_prompt_cache_config(agent)
  2019. _init_turn_state(agent, run_budget_seconds)
  2020. _set_defaults(agent, _STREAM_STATE)
  2021. _build_client(agent, api_key, base_url, fallback_model)
  2022. _init_fallback_chain(agent, fallback_model)
  2023. _load_tools(agent, enabled_toolsets, disabled_toolsets)
  2024. _init_session_state(
  2025. agent, session_id, session_db, parent_session_id, reasoning_config, max_tokens,
  2026. checkpoints_enabled, checkpoint_max_snapshots, checkpoint_max_total_size_mb, checkpoint_max_file_size_mb,
  2027. )
  2028. # Load config once for memory, skills, and compression sections
  2029. try:
  2030. from hermes_cli.config import load_config_readonly as _load_agent_config
  2031. _agent_cfg = _load_agent_config()
  2032. except Exception as exc: # health: allow BLE001 -- init must survive any config failure; the class is logged
  2033. # Config exceptions may contain secrets; omit their message and traceback
  2034. # even when a caller installs a non-redacting log handler.
  2035. logger.warning(
  2036. "Agent configuration could not be loaded (%s); using defaults for "
  2037. "memory, skills, compression and related settings. Check the active "
  2038. "Hermes Python environment and dependencies; run 'hermes config check' "
  2039. "after configuration imports work again.",
  2040. type(exc).__name__,
  2041. )
  2042. _agent_cfg = {}
  2043. _apply_display_config(agent, _agent_cfg, platform)
  2044. _init_memory(agent, _agent_cfg, skip_memory, platform, memory_manager=memory_manager)
  2045. _apply_agent_section(agent, _agent_cfg)
  2046. cs = _parse_compression_config(agent, _agent_cfg)
  2047. _config_context_length, _custom_providers, _effective_context_length, _model_cfg = _resolve_context_length(
  2048. agent, _agent_cfg, base_url
  2049. )
  2050. _build_context_engine(agent, _agent_cfg, cs, _custom_providers, _effective_context_length, session_db)
  2051. _configure_ollama_num_ctx(agent, _model_cfg, _config_context_length)
  2052. _enforce_minimum_context(agent)
  2053. _warn_nonagentic_hermes_model(agent)
  2054. _inject_context_engine_tools(agent)
  2055. _init_usage_state(agent)
  2056. _clamp_compressor_to_ollama_num_ctx(agent)
  2057. _emit_compression_summary(agent, cs)
  2058. _snapshot_primary_runtime(agent)
  2059. __all__ = ["init_agent"]