config.py 188 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616161716181619162016211622162316241625162616271628162916301631163216331634163516361637163816391640164116421643164416451646164716481649165016511652165316541655165616571658165916601661166216631664166516661667166816691670167116721673167416751676167716781679168016811682168316841685168616871688168916901691169216931694169516961697169816991700170117021703170417051706170717081709171017111712171317141715171617171718171917201721172217231724172517261727172817291730173117321733173417351736173717381739174017411742174317441745174617471748174917501751175217531754175517561757175817591760176117621763176417651766176717681769177017711772177317741775177617771778177917801781178217831784178517861787178817891790179117921793179417951796179717981799180018011802180318041805180618071808180918101811181218131814181518161817181818191820182118221823182418251826182718281829183018311832183318341835183618371838183918401841184218431844184518461847184818491850185118521853185418551856185718581859186018611862186318641865186618671868186918701871187218731874187518761877187818791880188118821883188418851886188718881889189018911892189318941895189618971898189919001901190219031904190519061907190819091910191119121913191419151916191719181919192019211922192319241925192619271928192919301931193219331934193519361937193819391940194119421943194419451946194719481949195019511952195319541955195619571958195919601961196219631964196519661967196819691970197119721973197419751976197719781979198019811982198319841985198619871988198919901991199219931994199519961997199819992000200120022003200420052006200720082009201020112012201320142015201620172018201920202021202220232024202520262027202820292030203120322033203420352036203720382039204020412042204320442045204620472048204920502051205220532054205520562057205820592060206120622063206420652066206720682069207020712072207320742075207620772078207920802081208220832084208520862087208820892090209120922093209420952096209720982099210021012102210321042105210621072108210921102111211221132114211521162117211821192120212121222123212421252126212721282129213021312132213321342135213621372138213921402141214221432144214521462147214821492150215121522153215421552156215721582159216021612162216321642165216621672168216921702171217221732174217521762177217821792180218121822183218421852186218721882189219021912192219321942195219621972198219922002201220222032204220522062207220822092210221122122213221422152216221722182219222022212222222322242225222622272228222922302231223222332234223522362237223822392240224122422243224422452246224722482249225022512252225322542255225622572258225922602261226222632264226522662267226822692270227122722273227422752276227722782279228022812282228322842285228622872288228922902291229222932294229522962297229822992300230123022303230423052306230723082309231023112312231323142315231623172318231923202321232223232324232523262327232823292330233123322333233423352336233723382339234023412342234323442345234623472348234923502351235223532354235523562357235823592360236123622363236423652366236723682369237023712372237323742375237623772378237923802381238223832384238523862387238823892390239123922393239423952396239723982399240024012402240324042405240624072408240924102411241224132414241524162417241824192420242124222423242424252426242724282429243024312432243324342435243624372438243924402441244224432444244524462447244824492450245124522453245424552456245724582459246024612462246324642465246624672468246924702471247224732474247524762477247824792480248124822483248424852486248724882489249024912492249324942495249624972498249925002501250225032504250525062507250825092510251125122513251425152516251725182519252025212522252325242525252625272528252925302531253225332534253525362537253825392540254125422543254425452546254725482549255025512552255325542555255625572558255925602561256225632564256525662567256825692570257125722573257425752576257725782579258025812582258325842585258625872588258925902591259225932594259525962597259825992600260126022603260426052606260726082609261026112612261326142615261626172618261926202621262226232624262526262627262826292630263126322633263426352636263726382639264026412642264326442645264626472648264926502651265226532654265526562657265826592660266126622663266426652666266726682669267026712672267326742675267626772678267926802681268226832684268526862687268826892690269126922693269426952696269726982699270027012702270327042705270627072708270927102711271227132714271527162717271827192720272127222723272427252726272727282729273027312732273327342735273627372738273927402741274227432744274527462747274827492750275127522753275427552756275727582759276027612762276327642765276627672768276927702771277227732774277527762777277827792780278127822783278427852786278727882789279027912792279327942795279627972798279928002801280228032804280528062807280828092810281128122813281428152816281728182819282028212822282328242825282628272828282928302831283228332834283528362837283828392840284128422843284428452846284728482849285028512852285328542855285628572858285928602861286228632864286528662867286828692870287128722873287428752876287728782879288028812882288328842885288628872888288928902891289228932894289528962897289828992900290129022903290429052906290729082909291029112912291329142915291629172918291929202921292229232924292529262927292829292930293129322933293429352936293729382939294029412942294329442945294629472948294929502951295229532954295529562957295829592960296129622963296429652966296729682969297029712972297329742975297629772978297929802981298229832984298529862987298829892990299129922993299429952996299729982999300030013002300330043005300630073008300930103011301230133014301530163017301830193020302130223023302430253026302730283029303030313032303330343035303630373038303930403041304230433044304530463047304830493050305130523053305430553056305730583059306030613062306330643065306630673068306930703071307230733074307530763077307830793080308130823083308430853086308730883089309030913092309330943095309630973098309931003101310231033104310531063107310831093110311131123113311431153116311731183119312031213122312331243125312631273128312931303131313231333134313531363137313831393140314131423143314431453146314731483149315031513152315331543155315631573158315931603161316231633164316531663167316831693170317131723173317431753176317731783179318031813182318331843185318631873188318931903191319231933194319531963197319831993200320132023203320432053206320732083209321032113212321332143215321632173218321932203221322232233224322532263227322832293230323132323233323432353236323732383239324032413242324332443245324632473248324932503251325232533254325532563257325832593260326132623263326432653266326732683269327032713272327332743275327632773278327932803281328232833284328532863287328832893290329132923293329432953296329732983299330033013302330333043305330633073308330933103311331233133314331533163317331833193320332133223323332433253326332733283329333033313332333333343335333633373338333933403341334233433344334533463347334833493350335133523353335433553356335733583359336033613362336333643365336633673368336933703371337233733374337533763377337833793380338133823383338433853386338733883389339033913392339333943395339633973398339934003401340234033404340534063407340834093410341134123413341434153416341734183419342034213422342334243425342634273428342934303431343234333434343534363437343834393440344134423443344434453446344734483449345034513452345334543455345634573458345934603461346234633464346534663467346834693470347134723473347434753476347734783479348034813482348334843485348634873488348934903491349234933494349534963497349834993500350135023503350435053506350735083509351035113512351335143515351635173518351935203521352235233524352535263527352835293530353135323533353435353536353735383539354035413542354335443545354635473548354935503551355235533554355535563557355835593560356135623563356435653566356735683569357035713572357335743575357635773578357935803581358235833584358535863587358835893590359135923593359435953596359735983599360036013602360336043605360636073608360936103611361236133614361536163617361836193620362136223623362436253626362736283629363036313632363336343635363636373638363936403641364236433644364536463647364836493650365136523653365436553656365736583659366036613662366336643665366636673668366936703671367236733674367536763677367836793680368136823683368436853686368736883689369036913692369336943695369636973698369937003701370237033704370537063707370837093710371137123713371437153716371737183719372037213722372337243725372637273728372937303731373237333734373537363737373837393740374137423743374437453746374737483749375037513752375337543755375637573758375937603761376237633764376537663767376837693770377137723773377437753776377737783779378037813782378337843785378637873788378937903791379237933794379537963797379837993800380138023803380438053806380738083809381038113812381338143815381638173818381938203821382238233824382538263827382838293830383138323833383438353836383738383839384038413842384338443845384638473848384938503851385238533854385538563857385838593860386138623863386438653866386738683869387038713872387338743875387638773878387938803881388238833884388538863887388838893890389138923893389438953896389738983899390039013902390339043905390639073908390939103911391239133914391539163917391839193920392139223923392439253926392739283929393039313932393339343935393639373938393939403941394239433944394539463947394839493950395139523953395439553956395739583959396039613962396339643965396639673968396939703971
  1. """Configuration management for Hermes Agent: config.yaml / .env loading, saving,
  2. validation, migration, and the ``hermes config`` command."""
  3. # Stale-module bridge — must run before ANY import below can bind a root-level symbol.
  4. # A pre-handoff updater purges only package prefixes after the pull, so a root module
  5. # (``utils``) stays cached from the OLD tree; the first fresh consumer of its new symbols
  6. # dies with ImportError before any later heal point is reached. See hermes_cli.stale_modules.
  7. from hermes_cli.stale_modules import drop_stale_root_modules
  8. drop_stale_root_modules()
  9. import copy
  10. import difflib
  11. import json
  12. import logging
  13. import os
  14. import platform
  15. import re
  16. import shlex
  17. import shutil
  18. import stat
  19. import subprocess
  20. import sys
  21. import tempfile
  22. import threading
  23. from contextlib import contextmanager, suppress
  24. from decimal import Decimal, InvalidOperation
  25. from pathlib import Path
  26. from typing import Dict, Any, Literal, Optional, List, Tuple, Set
  27. import hermes_yaml as yaml
  28. from hermes_cli.cli_output import line_input
  29. from hermes_cli.colors import Colors, color
  30. from hermes_cli import managed_scope
  31. from hermes_cli.default_soul import DEFAULT_SOUL_MD, is_legacy_template_soul
  32. from hermes_cli.left_core_migration import profile_env_names as _left_core_profile_env
  33. from hermes_cli.secret_prompt import masked_secret_prompt
  34. # Managed-mode, container and HERMES_UID/GID policy live in hermes_constants (import-safe);
  35. # re-exported here so existing callers/patch targets keep working.
  36. from hermes_constants import (
  37. _IGNORED_MANAGED_VALUES, _LEGACY_MANAGED_SYSTEM, _MANAGED_FALSE_VALUES, _MANAGED_TRUE_VALUES,
  38. _chown_to_hermes_uid, _container_or_chmod_skipped, _resolve_hermes_uid_gid,
  39. apply_secure_dir_policy, get_managed_system)
  40. # Re-export from hermes_constants — canonical definition lives there.
  41. from hermes_constants import get_hermes_home, get_process_hermes_home
  42. from utils import atomic_replace, fast_safe_load, file_cache_version, file_signature, mkstemp_beside
  43. from hermes_cli.config_issues import ConfigIssue, _issue
  44. from hermes_cli.config_backend import (
  45. ConfigWriteError, config_cache_version, config_destination, config_exists, config_version,
  46. get_config_backend, probe_config_readable, read_config_doc, supports_file_tooling,
  47. write_config_document)
  48. from hermes_cli.config_read_errors import (
  49. _CONFIG_PARSE_FAILURES, _FIX_PERMS, _FIX_YAML, FailedConfigRead, _backups_dir_display,
  50. _refuse_failed_read, _refuse_overwrite, _warn_config_parse_failure, _yaml_error_details,
  51. _yaml_error_location)
  52. logger = logging.getLogger(__name__)
  53. def is_uv_tool_install() -> bool:
  54. # Shim to stop the old updater doing work until relaunch, not select uv tool.
  55. return False
  56. def is_unsupported_install_method(method: str) -> bool:
  57. # Shim to stop the old updater doing work until relaunch. no legacy detection.
  58. return False
  59. def format_unsupported_install_warning(method: str) -> str:
  60. # Shim to stop the old updater doing work until relaunch. no obsolete advice.
  61. return ""
  62. class InvalidUserConfigError(RuntimeError):
  63. """Raised when a run that cannot repair config finds invalid user YAML."""
  64. _IS_WINDOWS = platform.system() == "Windows"
  65. _ENV_VAR_NAME_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
  66. # Env var names that influence how the next subprocess executes — never writable through
  67. # ``save_env_value``: dynamic loader (LD_*/DYLD_*: attacker code loads before main()),
  68. # interpreter init (PYTHON*, NODE_*: Hermes restarts through them), PATH (fix tool lookup
  69. # with absolute paths instead), git rewrites (fire on every plugin install/update),
  70. # implicitly-invoked commands (BROWSER/EDITOR/VISUAL/PAGER = RCE on next $EDITOR), SHELL,
  71. # and Hermes runtime-location / security-policy flags (config.yaml is the supported surface).
  72. #
  73. # ``HERMES_*`` overall is NOT blocked — many integration credentials use that prefix
  74. # (HERMES_LANGFUSE_PUBLIC_KEY, HERMES_SPOTIFY_CLIENT_ID, ...). The denylist is name-by-name so
  75. # it cannot break provider setup wizards. Enforced on *write* only: pre-existing/out-of-band
  76. # ``.env`` values keep working; the dashboard's writable surface just cannot escalate.
  77. # Whole families whose every member steers execution or config injection, matched by prefix
  78. # because enumeration cannot cover unbounded names (GIT_CONFIG_KEY_17 / GIT_CONFIG_VALUE_17).
  79. _ENV_VAR_NAME_DENY_PREFIXES: tuple[str, ...] = (
  80. "LD_", "DYLD_",
  81. # PARAMETERS/COUNT/KEY_*/VALUE_* inject config pairs; GLOBAL/SYSTEM/NOSYSTEM redirect the
  82. # config sources _subprocess_compat already nulls for the same reason.
  83. "GIT_CONFIG_",
  84. )
  85. _ENV_VAR_NAME_DENYLIST: frozenset[str] = frozenset({
  86. # Loader / linker (the LD_/DYLD_ prefixes cover the family; kept name-by-name for clarity)
  87. "LD_PRELOAD", "LD_LIBRARY_PATH", "LD_AUDIT", "LD_DEBUG",
  88. "DYLD_INSERT_LIBRARIES", "DYLD_LIBRARY_PATH", "DYLD_FRAMEWORK_PATH",
  89. "DYLD_FALLBACK_LIBRARY_PATH", "DYLD_FALLBACK_FRAMEWORK_PATH",
  90. # Python / Node — init-time injection beyond the loader paths
  91. "PYTHONPATH", "PYTHONHOME", "PYTHONSTARTUP", "PYTHONUSERBASE",
  92. "PYTHONEXECUTABLE", "PYTHONNOUSERSITE", "PYTHONBREAKPOINT", "PYTHONCASEOK",
  93. "NODE_OPTIONS", "NODE_PATH",
  94. # Other interpreter / toolchain injection (same class as PYTHONPATH / NODE_OPTIONS)
  95. "PERL5OPT", "PERL5LIB", "PERLLIB", "RUBYOPT", "RUBYLIB", "CLASSPATH",
  96. "JAVA_TOOL_OPTIONS", "_JAVA_OPTIONS", "JDK_JAVA_OPTIONS",
  97. "GOFLAGS", "RUSTFLAGS",
  98. # General / git — executed helpers, repo/config redirection, and template hooks
  99. "PATH", "SHELL", "BROWSER", "EDITOR", "VISUAL", "PAGER", "MANPAGER",
  100. "GIT_SSH_COMMAND", "GIT_EXEC_PATH", "GIT_SHELL",
  101. "GIT_SSH", "GIT_ASKPASS", "SSH_ASKPASS", "SUDO_ASKPASS",
  102. "GIT_EDITOR", "GIT_SEQUENCE_EDITOR", "GIT_PAGER", "GIT_EXTERNAL_DIFF",
  103. "GIT_PROXY_COMMAND", "GIT_TEMPLATE_DIR", "GIT_DIR",
  104. # Shell init files / interactive hooks — sourced before or during execution
  105. "BASH_ENV", "ENV", "ZDOTDIR", "PROMPT_COMMAND", "VIMINIT", "EXINIT",
  106. # Hermes runtime location
  107. "HERMES_HOME", "HERMES_PROFILE", "HERMES_CONFIG", "HERMES_ENV",
  108. "HERMES_CONFIG_PATH", "HERMES_ENV_PATH",
  109. # MCP catalog trust root; package-manager wrappers may still set it in the process env.
  110. "HERMES_OPTIONAL_MCPS",
  111. # Security policy / approval-routing context — set via their dedicated controls only.
  112. "HERMES_YOLO_MODE", "HERMES_ACCEPT_HOOKS", "HERMES_REDACT_SECRETS",
  113. "HERMES_INTERACTIVE", "HERMES_EXEC_ASK", "HERMES_GATEWAY_SESSION",
  114. "HERMES_CRON_SESSION", "HERMES_SINGLE_QUERY_SESSION",
  115. "HERMES_SESSION_KEY", "HERMES_SESSION_PLATFORM"})
  116. def _env_var_policy_name(key: str, *, is_windows: Optional[bool] = None) -> str:
  117. """Name used for env policy comparisons: Windows env names are case-insensitive, POSIX not.
  118. The override keeps both semantics testable on any host."""
  119. windows = _IS_WINDOWS if is_windows is None else is_windows
  120. return key.upper() if windows else key
  121. def validate_env_var_name_for_write(key: str) -> None:
  122. """Validate an env name before a generic persistence write (exposed for batch callers)."""
  123. if not _ENV_VAR_NAME_RE.match(key):
  124. raise ValueError(f"Invalid environment variable name: {key!r}")
  125. policy_name = _env_var_policy_name(key)
  126. from hermes_cli.auth_external_process import env_writer_launch_denylist as _launch_env # ACP argv authority
  127. if (policy_name in _ENV_VAR_NAME_DENYLIST or policy_name in map(_env_var_policy_name, _launch_env())
  128. or policy_name.startswith(_ENV_VAR_NAME_DENY_PREFIXES)):
  129. raise ValueError(
  130. f"Environment variable {key!r} is on the writer denylist. "
  131. "Names that influence subprocess execution (LD_PRELOAD, PYTHONPATH, PATH, EDITOR, ...) "
  132. "or Hermes runtime location and security policy (HERMES_HOME, HERMES_YOLO_MODE, ...) "
  133. "cannot be persisted via the env writer. If you really need this, edit ~/.hermes/.env "
  134. "directly.")
  135. # Serializes all config read/write paths and guards the module-level caches below. libyaml's
  136. # C extension is not thread-safe for concurrent safe_load() on one file, and tool threads
  137. # (approval, browser, setup flows) load/save config concurrently during long agent runs.
  138. # RLock because callers hold it across a read-modify-write and then call save_config(), which
  139. # acquires it again (hermes_cli/plugins.py: `with ..., config_mod._CONFIG_LOCK:` then
  140. # read_user_config_raw() + save_config()). save_config itself no longer re-enters via
  141. # read_raw_config; it takes its raw mapping from require_readable_config_before_write.
  142. _CONFIG_LOCK = threading.RLock()
  143. # path -> last successfully loaded (expanded) config; served after a parse failure so a
  144. # mid-edit broken YAML never silently drops user overrides (e.g. approvals.deny rules).
  145. _LAST_EXPANDED_CONFIG_BY_PATH: dict[str, Any] = {}
  146. # path -> (user_mtime_ns, user_size, managed_mtime_ns, managed_size, merged, env_ref_snapshot).
  147. # load_config() returns a deepcopy of the cached value while the signature matches (skips
  148. # safe_load + merge + normalize + expand, ~13 ms). Writers use the config writer seam (fresh inode
  149. # -> new mtime_ns) so no explicit invalidation is needed. The managed-file signature is folded
  150. # in so editing the managed-scope config.yaml invalidates, and the env snapshot invalidates
  151. # when a referenced ${VAR} changes value (late .env load, in-process rotation).
  152. # (path, mtime_ns, size) -> cached expanded config dict. load_config() returns a deepcopy of the cached
  153. # value when the file hasn't changed since the last load, skipping yaml.safe_load + _deep_merge +
  154. # _normalize_* + _expand_env_vars (~13 ms/call). save_config() + migrate_config() write via
  155. # the config writer seam, which produces a fresh inode, so stat() sees a new signature and the next load
  156. # repopulates automatically — no explicit invalidation hook. See #58514.
  157. _LOAD_CONFIG_CACHE: dict[str, tuple[Any, ...]] = {}
  158. # path -> (mtime_ns, size, ino, ctime_ns, racy digest, raw yaml dict) for read_raw_config() (no defaults merged in).
  159. _RAW_CONFIG_CACHE: dict[str, tuple[Any, ...]] = {}
  160. # Env var names written to .env that aren't in OPTIONAL_ENV_VARS (managed by setup/provider
  161. # flows directly). Also the set reload_env() may remove from os.environ.
  162. _EXTRA_ENV_KEYS = frozenset({
  163. "OPENAI_API_KEY", "OPENAI_BASE_URL", "ANTHROPIC_API_KEY", "ANTHROPIC_TOKEN",
  164. "DISCORD_HOME_CHANNEL", "DISCORD_HOME_CHANNEL_NAME",
  165. "TELEGRAM_HOME_CHANNEL", "TELEGRAM_HOME_CHANNEL_NAME",
  166. "SLACK_HOME_CHANNEL", "SLACK_HOME_CHANNEL_NAME",
  167. "SIGNAL_ACCOUNT", "SIGNAL_HTTP_URL", "SIGNAL_ALLOWED_USERS", "SIGNAL_GROUP_ALLOWED_USERS",
  168. "SIGNAL_HOME_CHANNEL", "SIGNAL_HOME_CHANNEL_NAME", "SMS_HOME_CHANNEL", "SMS_HOME_CHANNEL_NAME",
  169. "DINGTALK_CLIENT_ID", "DINGTALK_CLIENT_SECRET", "DINGTALK_HOME_CHANNEL", "DINGTALK_HOME_CHANNEL_NAME",
  170. "FEISHU_APP_ID", "FEISHU_APP_SECRET", "FEISHU_ENCRYPT_KEY", "FEISHU_VERIFICATION_TOKEN",
  171. "FEISHU_HOME_CHANNEL", "FEISHU_HOME_CHANNEL_NAME", "YUANBAO_HOME_CHANNEL", "YUANBAO_HOME_CHANNEL_NAME",
  172. "WECOM_BOT_ID", "WECOM_SECRET", "WECOM_CALLBACK_CORP_ID", "WECOM_CALLBACK_CORP_SECRET",
  173. "WECOM_CALLBACK_AGENT_ID", "WECOM_CALLBACK_TOKEN", "WECOM_CALLBACK_ENCODING_AES_KEY",
  174. "WECOM_CALLBACK_HOST", "WECOM_CALLBACK_PORT", "WECOM_HOME_CHANNEL", "WECOM_HOME_CHANNEL_NAME",
  175. "WEIXIN_ACCOUNT_ID", "WEIXIN_TOKEN", "WEIXIN_BASE_URL", "WEIXIN_CDN_BASE_URL",
  176. "WEIXIN_HOME_CHANNEL", "WEIXIN_HOME_CHANNEL_NAME", "WEIXIN_DM_POLICY", "WEIXIN_GROUP_POLICY",
  177. "WEIXIN_ALLOWED_USERS", "WEIXIN_GROUP_ALLOWED_USERS", "WEIXIN_ALLOW_ALL_USERS",
  178. "BLUEBUBBLES_SERVER_URL", "BLUEBUBBLES_PASSWORD", "BLUEBUBBLES_HOME_CHANNEL", "BLUEBUBBLES_HOME_CHANNEL_NAME",
  179. "QQ_APP_ID", "QQ_CLIENT_SECRET", "QQBOT_HOME_CHANNEL", "QQBOT_HOME_CHANNEL_NAME",
  180. "QQ_HOME_CHANNEL", "QQ_HOME_CHANNEL_NAME", # legacy aliases (pre-rename, still read for back-compat)
  181. "QQ_ALLOWED_USERS", "QQ_GROUP_ALLOWED_USERS", "QQ_ALLOW_ALL_USERS", "QQ_MARKDOWN_SUPPORT",
  182. "QQ_STT_API_KEY", "QQ_STT_BASE_URL", "QQ_STT_MODEL",
  183. "IRC_SERVER", "IRC_PORT", "IRC_NICKNAME", "IRC_CHANNEL", "IRC_USE_TLS", "IRC_SERVER_PASSWORD",
  184. "IRC_NICKSERV_PASSWORD", "TERMINAL_ENV", "TERMINAL_SSH_KEY", "TERMINAL_SSH_PORT",
  185. # Deprecated (replaced by display.tool_progress) but STILL READ by the gateway as a
  186. # back-compat fallback. The boolean HERMES_TOOL_PROGRESS variant is unsupported (its only
  187. # consumer, the v3->4 migration, is below the v12 support floor); doctor flags it as ignored.
  188. "HERMES_TOOL_PROGRESS_MODE",
  189. "WHATSAPP_MODE", "WHATSAPP_ENABLED",
  190. "MATTERMOST_HOME_CHANNEL", "MATTERMOST_HOME_CHANNEL_NAME", "MATTERMOST_REPLY_MODE",
  191. "MATRIX_PASSWORD", "MATRIX_ENCRYPTION", "MATRIX_DEVICE_ID", "MATRIX_HOME_ROOM",
  192. "MATRIX_REQUIRE_MENTION", "MATRIX_FREE_RESPONSE_ROOMS", "MATRIX_AUTO_THREAD", "MATRIX_DM_AUTO_THREAD",
  193. "MATRIX_RECOVERY_KEY",
  194. # ACP (Agent Client Protocol) keys — profile-isolable so profiles can use different backends.
  195. "HERMES_ACP_AUTH_METHOD", "HERMES_ACP_AUTO_APPROVE"}) | _left_core_profile_env() # moved providers' env
  196. # ---- Managed mode (NixOS declarative config) ----
  197. _NIX_MANAGED_SYSTEMS = {"nixos", "home-manager"}
  198. # Nix store root; identifies `nix run` / `nix profile install` installs (which don't set
  199. # HERMES_MANAGED). Module-level so tests can patch it without touching /nix/store.
  200. _NIX_STORE = Path("/nix/store")
  201. def is_managed() -> bool:
  202. """Check if Hermes is running in package-manager-managed mode."""
  203. return get_managed_system() is not None
  204. # Nix installs arrive by several routes (nix run, nix profile, system flake, home-manager) and
  205. # the running process cannot tell which, so the text names the routes instead of one command.
  206. _NIX_UPDATE_MSG = (
  207. "Update Hermes through the Nix source that installed it "
  208. "(e.g. nix profile upgrade, or update your flake input and rebuild with nixos-rebuild or home-manager switch)"
  209. )
  210. def get_managed_update_command() -> Optional[str]:
  211. """Return the preferred upgrade command for a managed install."""
  212. return _NIX_UPDATE_MSG if get_managed_system() in _NIX_MANAGED_SYSTEMS else None
  213. # "apt" is the Termux APT distribution identifier, not a generic Debian/Ubuntu signal; another
  214. # APT distribution needs its own method. "home-manager" is listed because the managed marker can
  215. # return it and a stamp must name every method this function returns.
  216. _SUPPORTED_INSTALL_METHODS = frozenset({"apt", "docker", "nix", "nixos", "home-manager", "git", "unknown"})
  217. def _install_method_stamp(path: Path) -> Optional[str]:
  218. try:
  219. method = path.read_text(encoding="utf-8-sig").strip().lower()
  220. except OSError:
  221. return None
  222. return method if method in _SUPPORTED_INSTALL_METHODS else None
  223. def detect_install_method(project_root: Optional[Path] = None) -> str:
  224. """Detect how Hermes was installed: apt/docker/nix/nixos/home-manager/git/unknown.
  225. Order: code-scoped ``<install tree>/.install_method`` stamp (authoritative) -> legacy
  226. ``$HERMES_HOME/.install_method`` -> managed marker -> /nix/store path -> .git dir -> unknown.
  227. The stamp lives next to the code because HERMES_HOME is shared data: a container and a host
  228. install can bind-mount the same home, so a home-scoped ``docker`` stamp would make the host
  229. ``hermes update`` refuse to run. A legacy ``docker`` value is therefore ignored unless we are
  230. really inside a container, and being in a container alone never implies 'docker'.
  231. Source installers clone a git checkout and publish ``install-stamp.json``;
  232. the ``.git`` fallback identifies it as a source install. Older installations
  233. may carry ``.install_method``, which remains authoritative for compatibility.
  234. The published image bakes a ``docker`` marker into ``/opt/hermes``. A manual
  235. clone in a container still resolves via ``.git``, not container presence alone.
  236. See issue #34397.
  237. """
  238. # The stamp is a property of the running code tree (parent of hermes_cli/), NOT of $HERMES_HOME,
  239. # so it survives two installs sharing a home.
  240. root = project_root if project_root is not None else get_project_root()
  241. method = _install_method_stamp(root / ".install_method")
  242. if method:
  243. return method
  244. method = _install_method_stamp(get_hermes_home() / ".install_method")
  245. if method and not (method == "docker" and not _running_in_container()):
  246. return method
  247. managed = get_managed_system()
  248. if managed:
  249. return managed.lower().replace(" ", "-")
  250. # Code under /nix/store/ is the hallmark of a nix-built install.
  251. try:
  252. resolved = root.resolve()
  253. if resolved != _NIX_STORE and _NIX_STORE in resolved.parents:
  254. return "nix"
  255. except OSError:
  256. pass
  257. # A .git directory, or a ``gitdir:`` pointer file for worktrees.
  258. git_path = root / ".git"
  259. try:
  260. if git_path.is_dir() or git_path.read_text(encoding="utf-8-sig").strip().startswith("gitdir:"):
  261. return "git"
  262. except OSError:
  263. pass
  264. return "unknown"
  265. def _running_in_container() -> bool:
  266. """Import-safe wrapper around ``hermes_constants.is_container``."""
  267. try:
  268. from hermes_constants import is_container
  269. return is_container()
  270. except Exception:
  271. return False
  272. def is_nix_install_method(method: str) -> bool:
  273. """True for every install method Nix owns ("nix", "nixos", "home-manager")."""
  274. return method == "nix" or method in _NIX_MANAGED_SYSTEMS
  275. _UPDATE_COMMAND_BY_METHOD = {
  276. "docker": "docker pull nousresearch/hermes-agent:latest",
  277. "apt": "pkg upgrade hermes-agent", # "apt" == Termux APT by contract; uses Termux's `pkg`.
  278. }
  279. def recommended_update_command_for_method(method: str) -> str:
  280. """Return the update command or guidance for a given install method."""
  281. if is_nix_install_method(method):
  282. return _NIX_UPDATE_MSG
  283. return _UPDATE_COMMAND_BY_METHOD.get(method, "hermes update")
  284. def recommended_update_command() -> str:
  285. """Return the best update command for the current installation.
  286. Managed state wins over the code-scoped stamp: a managed install can carry a stale stamp
  287. naming an update path the managed guard refuses."""
  288. return get_managed_update_command() or recommended_update_command_for_method(
  289. detect_install_method(get_project_root()))
  290. # Shared by ``cmd_update`` and ``_cmd_update_check`` (hermes_cli/main.py) so the wording never
  291. # forks. The published image excludes ``.git``, so the git update path can never succeed there
  292. # and the generic "reinstall via install.sh" fallback would install a NEW host-side Hermes.
  293. _DOCKER_UPDATE_MESSAGE = """\
  294. ✗ ``hermes update`` doesn't apply inside the Docker container.
  295. Hermes Agent runs as a published image (nousresearch/hermes-agent), not a
  296. git checkout — the container has no working tree to pull into. Update by
  297. pulling a fresh image and restarting your container instead:
  298. docker pull nousresearch/hermes-agent:latest
  299. # then restart whatever started the container, e.g.:
  300. docker compose up -d --force-recreate hermes-agent
  301. # or, for ad-hoc runs, exit the current container and `docker run` again
  302. Verify the new version after restart:
  303. docker run --rm nousresearch/hermes-agent:latest --version
  304. Notes:
  305. • If you pinned a specific tag (e.g. ``:v0.14.0``) the ``:latest`` tag
  306. won't move your container — pull the newer tag you actually want, or
  307. switch to ``:latest`` / ``:main`` for rolling updates. See available
  308. tags at https://hub.docker.com/r/nousresearch/hermes-agent/tags
  309. • On a ``-desktop`` tag (the one carrying Bot Screen)? Keep the suffix:
  310. the unsuffixed image has no Xvnc/Xfce and no sudo to add them, so
  311. pulling it stops the bots' screens from starting.
  312. • Your config and session history live under ``$HERMES_HOME`` (``/opt/data``
  313. in the container, typically bind-mounted from the host) and persist
  314. across image upgrades — re-pulling doesn't lose any state.
  315. • Running a fork? Build your own image with this repo's ``Dockerfile``
  316. and replace the ``docker pull`` step with your build/push pipeline."""
  317. def format_docker_update_message() -> str:
  318. """Return the user-facing message for ``hermes update`` inside Docker."""
  319. return _DOCKER_UPDATE_MESSAGE
  320. def format_managed_message(action: str = "modify this Hermes installation") -> str:
  321. """Build a user-facing error for managed installs."""
  322. managed_system = get_managed_system() or "a package manager"
  323. return (
  324. f"Cannot {action}: this Hermes installation is managed by {managed_system}.\n"
  325. "Use your package manager to upgrade or reinstall Hermes.")
  326. def managed_error(action: str = "modify configuration"):
  327. """Print user-friendly error for managed mode."""
  328. print(format_managed_message(action), file=sys.stderr)
  329. def get_container_exec_info() -> Optional[dict]:
  330. """Read container mode metadata from HERMES_HOME/.container-mode.
  331. Written by the NixOS activation script when container.enable = true; tells the host CLI to
  332. exec into the container instead of running locally. None when container mode is off, when
  333. already inside the container, or when HERMES_DEV=1 is set. Only FileNotFoundError is
  334. swallowed; other errors (permissions, malformed data) propagate."""
  335. if os.environ.get("HERMES_DEV") == "1":
  336. return None
  337. from hermes_constants import is_container
  338. if is_container():
  339. return None
  340. try:
  341. info = {}
  342. with open(get_hermes_home() / ".container-mode", "r", encoding="utf-8-sig") as f:
  343. for line in f:
  344. line = line.strip()
  345. if "=" in line and not line.startswith("#"):
  346. key, _, value = line.partition("=")
  347. info[key.strip()] = value.strip()
  348. except FileNotFoundError:
  349. return None
  350. return {
  351. "backend": info.get("backend", "docker"),
  352. "container_name": info.get("container_name", "hermes-agent"),
  353. "exec_user": info.get("exec_user", "hermes"),
  354. "hermes_bin": info.get("hermes_bin", "/data/current-package/bin/hermes")}
  355. # ---- Config paths / HERMES_HOME skeleton ----
  356. def get_config_path() -> Path:
  357. """Get the main config file path."""
  358. return get_hermes_home() / "config.yaml"
  359. def require_parseable_user_config(*, ignore_user_config: bool = False) -> None:
  360. """Reject an existing invalid config before a non-interactive agent run.
  361. Interactive surfaces keep ``load_config()``'s recovery behavior so the operator can repair
  362. the file; a one-shot run has no such chance, and defaults there could silently pick a hosted
  363. provider and spend against ``.env`` credentials. Missing/empty files stay valid first-run
  364. states; ``--ignore-user-config`` / HERMES_IGNORE_USER_CONFIG=1 remain authoritative."""
  365. if ignore_user_config or os.environ.get("HERMES_IGNORE_USER_CONFIG") == "1":
  366. return
  367. config_path = get_config_path()
  368. try:
  369. data = read_config_doc(config_path)
  370. except FileNotFoundError:
  371. return
  372. except Exception as exc:
  373. parse_error = exc
  374. else:
  375. if data is None or isinstance(data, dict):
  376. return
  377. parse_error = TypeError(f"top-level YAML value must be a mapping, got {type(data).__name__}")
  378. from hermes_cli.config_backups import backup_config
  379. backup_path = backup_config(config_path, "corrupt")
  380. where = _yaml_error_location(parse_error)
  381. message = (
  382. f"Hermes stopped because your settings file ({config_path}) has a formatting error"
  383. f"{f' at {where}' if where else ''}. Fix it with `hermes config edit` and check with "
  384. "`hermes config check`, or add --ignore-user-config to run once with default settings.")
  385. if backup_path is not None:
  386. message += f" A copy of the broken file is at {backup_path}."
  387. message += f" Details: {_yaml_error_details(parse_error)}"
  388. logger.error(message)
  389. raise InvalidUserConfigError(message) from parse_error
  390. def get_env_path() -> Path:
  391. """Get the .env file path (for API keys)."""
  392. return get_hermes_home() / ".env"
  393. def get_project_root() -> Path:
  394. """Get the project installation directory."""
  395. return Path(__file__).parent.parent.resolve()
  396. def _secure_dir(path):
  397. """chmod a directory owner-only (0700) and apply HERMES_UID/GID ownership. No-op when managed;
  398. in a container only an explicit HERMES_HOME_MODE is applied. HERMES_HOME_MODE (e.g. 0701)
  399. overrides the mode so a web server can traverse HERMES_HOME to a served subdirectory without
  400. directory listings.
  401. Also applies ``HERMES_UID``/``HERMES_GID``-based ownership when those env vars are set (#34107 — Docker
  402. deployments need this so profile subdirs created at runtime by kanban workers don't land as root:root
  403. and block subsequent uid-mapped workers).
  404. Delegates to the canonical import-safe primitive ``hermes_constants.apply_secure_dir_policy``
  405. so callers outside this package (``get_scratch_dir``) share one implementation (#117347).
  406. """
  407. return apply_secure_dir_policy(path)
  408. def _secure_file(path):
  409. """chmod a file 0600. Skipped when managed (activation sets 0640 group-readable) or in a
  410. container (mounts often need broader permissions)."""
  411. if is_managed() or _container_or_chmod_skipped():
  412. return
  413. try:
  414. if os.path.exists(str(path)):
  415. os.chmod(path, 0o600)
  416. except (OSError, NotImplementedError):
  417. pass
  418. def seed_config_file(config_path: Path, template: Optional[Path] = None) -> bool:
  419. """Create a missing config.yaml the way the installers do: copy cli-config.yaml.example (the display keys
  420. there are commented out), else write stripped DEFAULT_CONFIG. Never DEFAULT_CONFIG verbatim -- the gateway
  421. merges no defaults, so every written display key becomes a global that beats each platform's own default
  422. (#121230). Shared by ``hermes config edit`` and ``hermes doctor --fix`` so the seeders cannot drift.
  423. Returns True when the template was copied (the fallback, like save_config, writes get_config_path())."""
  424. template = template or get_project_root() / "cli-config.yaml.example"
  425. config_path.parent.mkdir(parents=True, exist_ok=True)
  426. if template.exists():
  427. shutil.copy2(template, config_path)
  428. _secure_file(config_path)
  429. return True
  430. save_config(DEFAULT_CONFIG)
  431. return False
  432. def _ensure_default_soul_md(home: Path) -> None:
  433. """Seed DEFAULT_SOUL_MD on first run; upgrade a legacy comment-only scaffold in place.
  434. A SOUL.md the user actually customized is never touched."""
  435. soul_path = home / "SOUL.md"
  436. if soul_path.exists():
  437. try:
  438. existing = soul_path.read_text(encoding="utf-8-sig")
  439. except (OSError, UnicodeDecodeError):
  440. return
  441. if not is_legacy_template_soul(existing):
  442. return
  443. try:
  444. soul_path.write_text(DEFAULT_SOUL_MD, encoding="utf-8")
  445. except OSError:
  446. if not soul_path.is_symlink():
  447. raise
  448. # A symlink the seed cannot write through — cyclic (``SOUL.md -> SOUL.md``, ELOOP) or
  449. # dangling into a missing directory (ENOENT) — can never hold an identity file, and the
  450. # OSError became HomeInitializationError on EVERY boot (launchd exit-75 relaunch storm,
  451. # #114592). Seed the default IN PLACE OF the link, never through it; mkstemp + replace
  452. # keeps concurrent gateway boots off one shared path. A working link is never reached
  453. # here: the write above succeeds through it.
  454. fd, tmp_name = tempfile.mkstemp(prefix=".SOUL.md.", suffix=".seed", dir=str(home))
  455. try:
  456. with os.fdopen(fd, "w", encoding="utf-8") as handle:
  457. handle.write(DEFAULT_SOUL_MD)
  458. os.replace(tmp_name, soul_path)
  459. except OSError:
  460. with suppress(OSError):
  461. os.unlink(tmp_name)
  462. raise
  463. _secure_file(soul_path)
  464. # Home paths whose directory skeleton was created this process. Only successful passes are
  465. # recorded, so a raised managed-mode/missing-profile error keeps re-checking on later loads.
  466. _HERMES_HOME_ENSURED: set = set()
  467. _HERMES_HOME_SUBDIRS = (
  468. "cron", "sessions", "logs", "logs/curator", "memories",
  469. "pairing", "hooks", "image_cache", "audio_cache", "skills")
  470. def ensure_hermes_home():
  471. """Ensure the ~/.hermes directory skeleton exists with secure permissions.
  472. Memoized per home path: this runs on EVERY ``load_config()`` and the ~14 mkdir/chmod syscalls
  473. made repeated loads the dominant cost of hot read paths."""
  474. home = get_hermes_home()
  475. key = str(home)
  476. # Named profiles must be created explicitly. Check tombstones BEFORE the memo so a stale
  477. # empty shell cannot skip the deleted-profile guard.
  478. from hermes_constants import assert_named_profile_home_live
  479. assert_named_profile_home_live(home)
  480. if key in _HERMES_HOME_ENSURED and home.is_dir():
  481. return
  482. from hermes_cli.config_home import initialize_home
  483. # The Yaovi kernel keeps long-term memory in the workspace; no MEMORY.md/USER.md directory.
  484. subdirs = tuple(d for d in _HERMES_HOME_SUBDIRS if d != "memories") if os.environ.get("YAOVI_KERNEL") == "1" else _HERMES_HOME_SUBDIRS
  485. initialize_home(home, subdirs, _HERMES_HOME_ENSURED)
  486. # ---- Config loading/saving ----
  487. from hermes_cli.config_defaults import DEFAULT_CONFIG, OPTIONAL_ENV_VARS
  488. from hermes_cli import config_provider_env as _config_provider_env
  489. from hermes_cli.config_provider_env import core_declared_env_names
  490. from hermes_cli.config_providers import (
  491. _API_MODE_ALIASES, _CAMEL_ALIASES, _KNOWN_PROVIDER_KEYS, _PROVIDER_NORMALIZE_WARNED,
  492. _canonical_api_mode, _coerce_ssl_verify, _custom_provider_entry_to_provider_config,
  493. _entries_for_route, _normalize_custom_provider_entry, _normalize_provider_models,
  494. _pick_provider_base_url, _route_model_cfg, _warn_once_per_provider,
  495. apply_custom_provider_extra_headers_to_client_kwargs,
  496. apply_custom_provider_tls_to_client_kwargs, coerce_provider_id, find_provider_entry,
  497. get_compatible_custom_providers, get_custom_provider_api_mode, get_custom_provider_context_length,
  498. get_custom_provider_extra_headers, get_custom_provider_model_capability,
  499. get_custom_provider_session_affinity_header,
  500. get_custom_provider_tls_settings, is_provider_enabled, normalize_extra_headers,
  501. providers_dict_to_custom_providers, stringify_provider_map)
  502. # Back-compat re-exports — :mod:`hermes_cli.personality` owns personality/overlay semantics.
  503. from hermes_cli.personality import (
  504. NEUTRAL_PERSONALITY_NAMES as _NEUTRAL_PERSONALITY_NAMES,
  505. prompt_text as _prompt_text,
  506. render_personality_prompt,
  507. resolve_ephemeral_system_prompt as resolve_ephemeral_system_prompt_from_config)
  508. # ---- Config schema-version stamp ---- (moved into config_version_stamp; re-exported here
  509. # because callers and tests import these from hermes_cli.config)
  510. from hermes_cli.config_version_stamp import (
  511. check_config_version, note_first_stamp, read_config_version_stamp, stamp_missing_config)
  512. # ---- Config Migration System ----
  513. # Env vars introduced per config version; migration only mentions vars new since the user's
  514. # previous version.
  515. ENV_VARS_BY_VERSION: dict[int, list[str]] = {
  516. 3: ["FIRECRAWL_API_KEY", "BROWSERBASE_API_KEY", "BROWSERBASE_PROJECT_ID", "FAL_KEY"],
  517. 4: ["VOICE_TOOLS_OPENAI_KEY", "ELEVENLABS_API_KEY"],
  518. 5: ["WHATSAPP_ENABLED", "WHATSAPP_MODE", "WHATSAPP_ALLOWED_USERS",
  519. "SLACK_BOT_TOKEN", "SLACK_APP_TOKEN", "SLACK_ALLOWED_USERS"],
  520. 10: ["TAVILY_API_KEY"],
  521. 11: ["TERMINAL_MODAL_MODE"]}
  522. # Intentionally empty: the LLM provider is required but handled by the setup wizard's provider
  523. # selection step, so no single env var is universally required.
  524. REQUIRED_ENV_VARS = {}
  525. def get_missing_env_vars(required_only: bool = False) -> list[dict[str, Any]]:
  526. """Check which environment variables are missing."""
  527. groups = [(REQUIRED_ENV_VARS, True)]
  528. if not required_only:
  529. groups.append((OPTIONAL_ENV_VARS, False))
  530. return [
  531. {"name": var_name, **info, "is_required": is_required}
  532. for table, is_required in groups
  533. for var_name, info in table.items()
  534. if not get_env_value(var_name)]
  535. def _split_key_path(key: str) -> list[str]:
  536. """Split a dotted config-key path, honoring backslash-escaped dots (``a\\.b`` -> ``a.b``).
  537. Backslashes before any other character are preserved verbatim.
  538. ``hermes config set`` uses ``.`` as the nesting separator, so a key that itself contains a literal dot
  539. (e.g. provider names like ``qwen3.5-397b-wafer``) was silently split into bogus nested segments
  540. (#84064).
  541. """
  542. parts: list[str] = []
  543. current: list[str] = []
  544. i = 0
  545. while i < len(key):
  546. ch = key[i]
  547. if ch == "\\" and key[i + 1:i + 2] == ".":
  548. current.append(".")
  549. i += 2
  550. continue
  551. if ch == ".":
  552. parts.append("".join(current))
  553. current = []
  554. else:
  555. current.append(ch)
  556. i += 1
  557. parts.append("".join(current))
  558. return parts
  559. def _greedy_literal_match(container: dict, parts: list) -> Optional[tuple[str, int]]:
  560. """Return ``(literal_key, n_consumed)`` for the longest dotted literal key present in
  561. *container*, or None. With no multi-segment literal this is the historic plain-split walk.
  562. Dots in config key names are the norm, not the exception — model IDs (``grok-4.6``, ``glm-5.3``), Matrix
  563. room IDs (``!room:chat.example.cc``), and versioned provider names all embed dots. Users typing
  564. ``providers.myprov.models.grok-4.6.context_length`` do not know the escape syntax exists, so when
  565. navigating an EXISTING mapping we prefer an existing literal key equal to the dot-join of the next N
  566. path segments (longest match wins) over blindly splitting. See #84064 / #80006 / 91095 / #91607 /
  567. #99124.
  568. """
  569. if not isinstance(container, dict) or not parts:
  570. return None
  571. return next(
  572. ((".".join(parts[:n]), n) for n in range(len(parts), 0, -1) if ".".join(parts[:n]) in container),
  573. None)
  574. def _phantom_sibling(container: dict, part: str) -> Optional[str]:
  575. """Existing literal dotted key that creating an intermediate mapping ``part`` would shadow
  576. (``grok-4`` beside ``grok-4.5``) — the write would produce a phantom sibling the runtime never
  577. reads, so callers fail loudly instead.
  578. Called when a write is about to CREATE a new intermediate mapping named ``part``. See #84064.
  579. """
  580. if not isinstance(container, dict):
  581. return None
  582. prefix = part + "."
  583. return next((k for k in container if isinstance(k, str) and k.startswith(prefix)), None)
  584. def _set_nested(config, dotted_key: str, value):
  585. """Set a value at a dotted key path, creating intermediate dicts on demand.
  586. Numeric segments index lists; the index must already exist (lists are never grown).
  587. Guards against #17876: before this fix the code unconditionally replaced any non-dict value (including
  588. lists) with ``{}``, silently destroying list-typed config like ``custom_providers`` whenever a caller
  589. used an indexed path.
  590. Dotted key names (#84064 family): when navigating an existing mapping, an existing literal key equal to
  591. the dot-join of the next N segments is preferred over blind splitting (see ``_greedy_literal_match``),
  592. so ``models.grok-4.6.supports_vision`` lands on the real ``grok-4.6`` entry. And when a write WOULD
  593. create a new intermediate mapping that shadows an existing dotted sibling (``grok-4`` beside
  594. ``grok-4.5``), it raises ``ValueError`` instead of silently writing a phantom the runtime never reads.
  595. """
  596. parts = _split_key_path(dotted_key)
  597. current = config
  598. i = 0
  599. while i < len(parts):
  600. remaining = parts[i:]
  601. at_leaf = len(remaining) == 1
  602. if isinstance(current, list):
  603. part = remaining[0]
  604. if at_leaf:
  605. current[int(part)] = value
  606. return
  607. try:
  608. current = current[int(part)]
  609. except (TypeError, ValueError):
  610. raise TypeError(
  611. f"Cannot navigate into list at key {dotted_key!r}: "
  612. f"segment {part!r} is not a numeric index")
  613. i += 1
  614. elif isinstance(current, dict):
  615. match = _greedy_literal_match(current, remaining)
  616. if match is not None:
  617. key, consumed = match
  618. if i + consumed == len(parts):
  619. current[key] = value
  620. return
  621. # Preserve dicts and lists; replace scalar with a fresh dict.
  622. if not isinstance(current.get(key), (dict, list)):
  623. current[key] = {}
  624. current = current[key]
  625. i += consumed
  626. continue
  627. part = remaining[0]
  628. if at_leaf:
  629. current[part] = value
  630. return
  631. shadowed = _phantom_sibling(current, part)
  632. if shadowed is not None:
  633. escaped = shadowed.replace(".", "\\.")
  634. raise ValueError(
  635. f"Refusing to create nested key {part!r} in {dotted_key!r}: the mapping "
  636. f"already contains a literal key {shadowed!r} that contains a dot. If you "
  637. f"meant that key, escape its dots with a backslash (e.g. {escaped}).")
  638. current = current.setdefault(part, {})
  639. i += 1
  640. else:
  641. raise TypeError(f"Cannot navigate into {type(current).__name__} at key {dotted_key!r}")
  642. def clear_model_endpoint_credentials(
  643. model_cfg: dict[str, Any], *, clear_api_key: bool = True, clear_api_mode: bool = True,
  644. clear_base_url: bool = False) -> dict[str, Any]:
  645. """Remove stale inline endpoint credentials from a model config.
  646. ``model.api_key`` is valid only for explicit custom endpoints; built-in providers resolve
  647. credentials from env/auth.json/the pool. Leftovers keep secrets in config.yaml and can
  648. contaminate later custom resolution paths."""
  649. if not isinstance(model_cfg, dict):
  650. return model_cfg
  651. if clear_api_key:
  652. model_cfg.pop("api_key", None)
  653. model_cfg.pop("api", None)
  654. # key_env is a first-class credential POINTER (runtime_provider and
  655. # auxiliary_client resolve it), written by custom-endpoint activation.
  656. # Leaving it behind on a provider switch routes the NEW provider's
  657. # requests to the OLD endpoint's env var — same staleness class as an
  658. # inline api_key, so it clears under the same flag.
  659. model_cfg.pop("key_env", None)
  660. model_cfg.pop("api_key_env", None)
  661. if clear_api_mode:
  662. model_cfg.pop("api_mode", None)
  663. if clear_base_url:
  664. model_cfg.pop("base_url", None)
  665. return model_cfg
  666. _MISSING = object()
  667. def _locate_nested(config, parts: list):
  668. """Walk *parts* through nested dicts/lists (escape-aware, greedy-literal like ``_set_nested``).
  669. Returns ``(parents, container, key)`` where ``container[key]`` is the addressed leaf and
  670. ``parents`` lists the ``(container, key)`` hops above it, or ``None`` when any hop is missing,
  671. a list index is non-numeric/out of range, or a scalar is hit before the path is consumed."""
  672. parents = []
  673. current = config
  674. i = 0
  675. while True:
  676. remaining = parts[i:]
  677. if isinstance(current, list):
  678. try:
  679. key = int(remaining[0])
  680. current[key]
  681. except (TypeError, ValueError, IndexError):
  682. return None
  683. consumed = 1
  684. elif isinstance(current, dict):
  685. match = _greedy_literal_match(current, remaining)
  686. if match is None:
  687. return None
  688. key, consumed = match
  689. else:
  690. return None
  691. i += consumed
  692. if i == len(parts):
  693. return parents, current, key
  694. parents.append((current, key))
  695. current = current[key]
  696. def _get_nested(config, dotted_key: str):
  697. """Return a dotted-path value (``_MISSING`` when absent); same navigation as ``_set_nested``
  698. so ``models.grok-4.6.context_length`` reads the real ``grok-4.6`` entry.
  699. Mirrors ``_set_nested``'s navigation: honors backslash-escaped dots and prefers an existing literal
  700. dotted key over blind splitting, so ``config get providers.p.models.grok-4.6.context_length`` reads the
  701. real ``grok-4.6`` entry instead of reporting the key unset (#84064).
  702. """
  703. loc = _locate_nested(config, _split_key_path(dotted_key))
  704. if loc is None:
  705. return _MISSING
  706. _, container, key = loc
  707. return container[key]
  708. def _unset_nested(config, dotted_key: str) -> bool:
  709. """Remove a dotted-path value; True if it existed. Empty dict containers left behind are
  710. dropped, while user-authored empty lists and non-empty sibling branches are preserved.
  711. Same escape-aware, greedy-literal navigation as ``_set_nested`` / ``_get_nested`` (#84064): unsetting an
  712. unescaped dotted key removes the real literal entry rather than a phantom sibling.
  713. """
  714. loc = _locate_nested(config, _split_key_path(dotted_key))
  715. if loc is None:
  716. return False
  717. parents, current, key = loc
  718. del current[key]
  719. # ``parent[part] is current`` for every hop, so each now-empty dict container is dropped.
  720. for parent, part in reversed(parents):
  721. if current != {}:
  722. break
  723. del parent[part]
  724. current = parent
  725. return True
  726. _ENV_CONFIG_KEYS = frozenset({
  727. 'OPENROUTER_API_KEY', 'OPENAI_API_KEY', 'ANTHROPIC_API_KEY', 'VOICE_TOOLS_OPENAI_KEY',
  728. 'EXA_API_KEY', 'PARALLEL_API_KEY', 'FIRECRAWL_API_KEY', 'FIRECRAWL_API_URL',
  729. 'FIRECRAWL_GATEWAY_URL', 'TOOL_GATEWAY_URL', 'CONNECTOR_GATEWAY_URL',
  730. 'TOOL_GATEWAY_DOMAIN', 'TOOL_GATEWAY_SCHEME',
  731. 'TOOL_GATEWAY_USER_TOKEN', 'TAVILY_API_KEY', 'PERPLEXITY_API_KEY', 'API_SERVER_KEY',
  732. 'BROWSERBASE_API_KEY', 'BROWSERBASE_PROJECT_ID', 'BROWSER_USE_API_KEY',
  733. 'FAL_KEY', 'TELEGRAM_BOT_TOKEN', 'DISCORD_BOT_TOKEN',
  734. 'TERMINAL_SSH_HOST', 'TERMINAL_SSH_USER', 'TERMINAL_SSH_KEY',
  735. 'SUDO_PASSWORD', 'SLACK_BOT_TOKEN', 'SLACK_APP_TOKEN',
  736. 'GITHUB_TOKEN', 'HONCHO_API_KEY'})
  737. def _is_env_config_key(key: str) -> bool:
  738. """Return whether `hermes config set` routes this credential-shaped key to .env through the
  739. provider credential lifecycle. Non-secret env settings (``*_HOME_CHANNEL``, ``*_ALLOWED_USERS``)
  740. are ``config_env_routing.is_env_setting_key`` and take the plain ``.env`` path."""
  741. if "." in key:
  742. return False
  743. key_upper = key.upper()
  744. return (
  745. key_upper in _ENV_CONFIG_KEYS
  746. or key_upper.endswith(('_API_KEY', '_TOKEN', '_SECRET'))
  747. or key_upper.startswith('TERMINAL_SSH'))
  748. def _format_config_get_value(value, *, as_json: bool) -> str:
  749. """Format a config value for command-line output."""
  750. if as_json:
  751. return json.dumps(value, ensure_ascii=False)
  752. if isinstance(value, bool):
  753. return "true" if value else "false"
  754. if value is None:
  755. return "null"
  756. if isinstance(value, (dict, list)):
  757. return yaml.safe_dump(value, sort_keys=False).rstrip() # config-writer: ok — renders a value for display, never written to disk
  758. return str(value)
  759. def get_missing_config_fields() -> list[dict[str, Any]]:
  760. """Check which config fields are missing or outdated (recursive)."""
  761. from hermes_cli.moa_config import skip_deep_merge
  762. missing = []
  763. def _check(defaults: dict, current: dict, prefix: str = ""):
  764. for key, default_value in defaults.items():
  765. if key.startswith('_'):
  766. continue
  767. full_key = key if not prefix else f"{prefix}.{key}"
  768. if key not in current:
  769. missing.append({"key": full_key, "default": default_value,
  770. "description": f"New config option: {full_key}"})
  771. elif (isinstance(default_value, dict) and isinstance(current.get(key), dict)
  772. and not skip_deep_merge(prefix, key)):
  773. _check(default_value, current[key], full_key)
  774. _check(DEFAULT_CONFIG, load_config())
  775. return missing
  776. def get_missing_skill_config_vars() -> list[dict[str, Any]]:
  777. """Return skill-declared config vars (``skills.config.<key>``) that are missing or empty."""
  778. try:
  779. from agent.skill_utils import discover_all_skill_config_vars, SKILL_CONFIG_PREFIX
  780. except Exception:
  781. return []
  782. try:
  783. all_vars = discover_all_skill_config_vars()
  784. except Exception as e:
  785. # A malformed SKILL.md must never break `hermes update`; this prompting is a nicety.
  786. logger.debug("discover_all_skill_config_vars failed: %s", e)
  787. return []
  788. if not all_vars:
  789. return []
  790. config = load_config()
  791. values = ((var, cfg_get(config, *f"{SKILL_CONFIG_PREFIX}.{var['key']}".split("."))) for var in all_vars)
  792. return [var for var, v in values if v is None or (isinstance(v, str) and not v.strip())]
  793. # ---- Config structure validation ----
  794. # DEFAULT_CONFIG is the single source of truth for documented roots; the set is derived so new
  795. # defaults are accepted automatically. These optional/legacy roots are valid on disk but
  796. # intentionally absent from DEFAULT_CONFIG (omitted when unused / alternate schema forms).
  797. _EXTRA_KNOWN_ROOT_KEYS = {
  798. "custom_providers", # legacy list form; modern equivalent is providers: {}
  799. "fallback_model", # optional single dict or chain list; omitted when disabled
  800. "mcp_servers", # MCP server definitions written by setup/tools flows
  801. "image_gen", # agent/image_gen_registry.py
  802. "video_gen", # agent/video_gen_registry.py
  803. "plugins", # plugin enable/disable lists (hermes_cli/plugins_cmd.py)
  804. "smart_model_routing", # written by the setup wizard
  805. "platform_toolsets", # written by the setup wizard
  806. "known_plugin_toolsets", # hermes_cli/tools_config.py toolset-save flow
  807. "known_builtin_toolsets", # ditto — builtin toolsets a platform's checklist has offered
  808. "tool_gateway_declined_tools", # per-tool Tool Gateway offer declines
  809. # Top-level forms read/bridged by gateway/config.py:
  810. "group_sessions_per_user", "thread_sessions_per_user",
  811. "stt_echo_transcripts", "reset_triggers", "always_log_local", "filter_silence_narration",
  812. "multiplex_profiles", "profile_routes", "platforms", "require_mention",
  813. "unauthorized_dm_behavior", "signal", "allow_all_users",
  814. "timeouts", # unified timeout resolution section (agent/deadline.py)
  815. }
  816. _KNOWN_ROOT_KEYS = frozenset(DEFAULT_CONFIG.keys()) | _EXTRA_KNOWN_ROOT_KEYS
  817. # Valid fields inside a custom_providers list entry (key_env is read at runtime by
  818. # runtime_provider.py and auxiliary_client.py).
  819. _VALID_CUSTOM_PROVIDER_FIELDS = {
  820. "name", "base_url", "api_key", "api_mode", "model", "models",
  821. "context_length", "rate_limit_delay", "extra_body",
  822. "ssl_ca_cert", "ssl_verify", "key_env", "catalog_provider"}
  823. # Fields that look like they should be inside custom_providers, not at root
  824. _CUSTOM_PROVIDER_LIKE_FIELDS = {"base_url", "api_key", "rate_limit_delay", "api_mode"}
  825. def _require_fields(
  826. issues: list[ConfigIssue], entry: dict[str, Any], label: str,
  827. fields: tuple[tuple[str, str], ...], suffix: str = "") -> None:
  828. """Append a warning for every falsy ``field`` of *entry* (message: ``<label> is missing '<f>' field``)."""
  829. for field, hint in fields:
  830. if not entry.get(field):
  831. _issue(issues, "warning", f"{label} is missing '{field}' field{suffix}", hint)
  832. _CP_REQUIRED_FIELDS = (
  833. ("name", "Add a name, e.g.: name: my-provider"),
  834. ("base_url", "Add the API endpoint URL, e.g.: base_url: https://api.example.com/v1"))
  835. _FB_REQUIRED_FIELDS = (
  836. ("provider", "Add: provider: openrouter (or another provider)"),
  837. ("model", "Add: model: <model-name>"))
  838. _FB_SINGLE_REQUIRED_FIELDS = (
  839. ("provider", "Add: provider: openrouter (or another provider)"),
  840. ("model", "Add: model: anthropic/claude-sonnet-4 (or another model)"))
  841. def _validate_entry_list(
  842. entries: list, label: str, issues: list[ConfigIssue], fields, *, non_dict: tuple[str, str, str],
  843. ) -> None:
  844. """Validate each list entry: ``non_dict`` = (severity, message-with-{i}-and-{type}, hint) for
  845. non-dict items; dict items get ``_require_fields`` with *fields*."""
  846. severity, message, hint = non_dict
  847. for i, entry in enumerate(entries):
  848. if not isinstance(entry, dict):
  849. _issue(issues, severity, message.format(i=i, type=type(entry).__name__), hint)
  850. else:
  851. _require_fields(issues, entry, f"{label}[{i}]", fields)
  852. _CP_LIST_HINT = "Change to:\n custom_providers:\n - name: my-provider\n base_url: https://...\n api_key: ..."
  853. def _validate_custom_providers(cp: Any, issues: list[ConfigIssue]) -> None:
  854. """custom_providers must be a list of dicts — a dict or a scalar is silently dropped by the runtime."""
  855. if isinstance(cp, dict):
  856. _issue(issues, "error",
  857. "custom_providers is a dict — it must be a YAML list (items prefixed with '-')", _CP_LIST_HINT)
  858. suspicious = set(cp.keys()) & _CUSTOM_PROVIDER_LIKE_FIELDS
  859. if suspicious:
  860. _issue(issues, "warning",
  861. f"Root-level keys {sorted(suspicious)} look like custom_providers entry fields",
  862. "These should be indented under a '- name: ...' list entry, not at root level")
  863. elif isinstance(cp, list):
  864. _validate_entry_list(cp, "custom_providers", issues, _CP_REQUIRED_FIELDS, non_dict=(
  865. "warning", "custom_providers[{i}] is not a dict (got {type})",
  866. "Each entry should have at minimum: name, base_url"))
  867. else:
  868. # get_compatible_custom_providers() returns [] for any non-list: the legacy entries vanish
  869. # ("0 endpoints") with nothing naming the cause.
  870. _issue(issues, "error",
  871. f"custom_providers is a {type(cp).__name__} — it must be a YAML list (items prefixed with '-'); "
  872. "legacy custom_providers entries are ignored until it is", _CP_LIST_HINT)
  873. def _validate_fallback_model(fb: Any, issues: list[ConfigIssue]) -> None:
  874. """fallback_model: single dict OR list of dicts (chain)."""
  875. if isinstance(fb, list):
  876. _validate_entry_list(fb, "fallback_model", issues, _FB_REQUIRED_FIELDS, non_dict=(
  877. "error", "fallback_model[{i}] should be a dict, got {type}", "Each entry needs provider + model"))
  878. elif not isinstance(fb, dict):
  879. _issue(issues, "error",
  880. f"fallback_model should be a dict with 'provider' and 'model', got {type(fb).__name__}",
  881. "Change to:\n fallback_model:\n provider: openrouter\n model: anthropic/claude-sonnet-4")
  882. elif fb:
  883. _require_fields(issues, fb, "fallback_model", _FB_SINGLE_REQUIRED_FIELDS,
  884. suffix=" — fallback will be disabled")
  885. def validate_config_structure(config: Optional[dict[str, Any]] = None) -> list[ConfigIssue]:
  886. """Validate config.yaml structure and return detected issues (accepts a pre-loaded dict).
  887. Catches common YAML mistakes that otherwise surface as confusing runtime errors."""
  888. if config is None:
  889. try:
  890. config = load_config()
  891. except Exception as exc:
  892. from hermes_cli.config_home import config_load_issue
  893. return [config_load_issue(exc)]
  894. from hermes_cli.config_value_checks import (
  895. _validate_quoted_containers, _validate_timezone, _validate_voice, _validate_web_backends)
  896. issues: list[ConfigIssue] = []
  897. _validate_voice(config, issues)
  898. _validate_timezone(config, issues)
  899. cp = config.get("custom_providers")
  900. fb = config.get("fallback_model")
  901. for value, validator in ((cp, _validate_custom_providers), (fb, _validate_fallback_model)):
  902. if value is not None:
  903. validator(value, issues)
  904. if isinstance(cp, dict) and "fallback_model" not in config and "fallback_model" in (cp or {}):
  905. _issue(issues, "error", "fallback_model appears inside custom_providers instead of at root level",
  906. "Move fallback_model to the top level of config.yaml (no indentation)")
  907. if cp and not config.get("model"):
  908. _issue(issues, "warning",
  909. "custom_providers defined but no 'model' section — Hermes won't know which provider to use",
  910. "Add a model section:\n model:\n provider: custom\n default: your-model-name\n"
  911. " base_url: https://...")
  912. # Only provider-like fields are flagged as misplaced roots. Arbitrary unknown top-level keys
  913. # are deliberately NOT warned about: top-level scalars are bridged into os.environ so users
  914. # can feed skills/external apps env-style keys — a closed-world allowlist cannot enumerate those.
  915. for key in config:
  916. if not key.startswith("_") and key not in _KNOWN_ROOT_KEYS and key in _CUSTOM_PROVIDER_LIKE_FIELDS:
  917. _issue(issues, "warning",
  918. f"Root-level key '{key}' looks misplaced — should it be under 'model:' or inside a 'custom_providers' entry?",
  919. f"Move '{key}' under the appropriate section")
  920. _validate_web_backends(config, issues)
  921. _validate_quoted_containers(config, issues)
  922. return issues
  923. def print_config_warnings(config: Optional[dict[str, Any]] = None) -> None:
  924. """Print config structure warnings to stderr at startup; nothing if config is healthy."""
  925. try:
  926. issues = validate_config_structure(config)
  927. except Exception:
  928. issues = []
  929. if not issues:
  930. return
  931. lines = ["\033[33m⚠ Config issues detected in config.yaml:\033[0m"]
  932. for ci in issues:
  933. marker = "\033[31m✗\033[0m" if ci.severity == "error" else "\033[33m⚠\033[0m"
  934. lines.append(f" {marker} {ci.message}")
  935. lines.append(" \033[2mRun 'hermes doctor' for fix suggestions.\033[0m")
  936. sys.stderr.write("\n".join(lines) + "\n\n")
  937. def warn_deprecated_cwd_env_vars() -> None:
  938. """Warn if MESSAGING_CWD / TERMINAL_CWD is set in .env (canonical: terminal.cwd in config.yaml).
  939. Reads the file rather than ``os.environ`` because runtime bridges and session restoration
  940. legitimately set ``TERMINAL_CWD``."""
  941. try:
  942. env_map = load_env()
  943. except Exception:
  944. return
  945. lines: list[str] = []
  946. for name in ("MESSAGING_CWD", "TERMINAL_CWD"):
  947. val = str(env_map.get(name) or "").strip()
  948. if val:
  949. lines.append(f" \033[33m⚠\033[0m {name}={val} found in .env — this is deprecated.")
  950. if lines:
  951. from hermes_constants import display_hermes_home
  952. hint_path = display_hermes_home()
  953. lines.insert(0, "\033[33m⚠ Deprecated .env settings detected:\033[0m")
  954. lines.append(
  955. " \033[2mMove to config.yaml instead: "
  956. "terminal:\\n cwd: /your/project/path\033[0m")
  957. lines.append(f" \033[2mThen remove the old entries from {hint_path}/.env\033[0m")
  958. sys.stderr.write("\n".join(lines) + "\n\n")
  959. def _persist_migration(config: dict[str, Any]) -> None:
  960. """Persist a migrated config under THE migration write invariant: a migration may only
  961. persist values that DIFFER from the schema default, plus explicit removals/renames of user
  962. data. Every migration step MUST write through here (``save_config`` with default-stripping
  963. ON, no ``merge_existing``) so the invariant cannot regress one migration at a time. A migration
  964. is Hermes' own write, never a user turning a feature off. A backend without file tooling
  965. migrates in memory on read and never writes back (D12)."""
  966. from hermes_cli.observability.shared_metrics_disabled import hermes_applied_write
  967. if not supports_file_tooling():
  968. get_config_backend().apply_in_memory(get_config_path().parent, config)
  969. return
  970. with hermes_applied_write():
  971. save_config(config)
  972. def _prompt_and_save_env(name: str, info: dict[str, Any], prompt: str, results: dict[str, Any]) -> bool:
  973. """Prompt for one env var (masked when ``info['password']``), save it, record it; False if skipped."""
  974. value = masked_secret_prompt(prompt) if info.get("password") else line_input(prompt).strip()
  975. if not value:
  976. return False
  977. save_env_value(name, value)
  978. results["env_added"].append(name)
  979. print(f" ✓ Saved {name}")
  980. return True
  981. def _ask_yes_no(prompt: str) -> bool:
  982. try:
  983. answer = input(prompt).strip().lower()
  984. except (EOFError, KeyboardInterrupt):
  985. answer = "n"
  986. return answer in {"y", "yes"}
  987. def migrate_config(interactive: bool = True, quiet: bool = False) -> dict[str, Any]:
  988. """Migrate config to latest version, prompting for new required fields."""
  989. results = {"env_added": [], "config_added": [], "warnings": []}
  990. stamp_missing_config() # a missing config.yaml reads as current below: stamp its legacy browser settings
  991. # Validate before any side effect: sanitize_env_file() rewrites .env, never for refused (malformed) YAML.
  992. stamp, latest_ver = read_config_version_stamp(raise_on_parse_error=True)
  993. current_ver = 0 if stamp is None else stamp
  994. try:
  995. fixes = sanitize_env_file()
  996. if fixes and not quiet:
  997. print(f" ✓ Normalized .env line formatting ({fixes} line(s) changed)")
  998. except Exception:
  999. pass # best-effort; never block migration on sanitize failure
  1000. # Auto-migration support floor (v12): an EXPLICIT on-disk ``_config_version`` below the
  1001. # floor is NOT migrated and NOT rewritten — surface a message and leave the file untouched
  1002. # (deep-merge supplies defaults at read time). A config with NO version key is not an
  1003. # ancient install: it gets only the legacy-key steps and a version stamp.
  1004. # Missing/unparseable files never trip the floor gate.
  1005. # Imported lazily because the steps call back into this module.
  1006. from hermes_cli.config_migrations import (
  1007. SUPPORT_FLOOR_VERSION, run_migrations, support_floor_message)
  1008. has_explicit_version = stamp is not None
  1009. floor_refused = (
  1010. has_explicit_version and current_ver < SUPPORT_FLOOR_VERSION and current_ver < latest_ver)
  1011. if floor_refused:
  1012. msg = support_floor_message()
  1013. results["warnings"].append(msg)
  1014. # stderr so it is visible even on quiet startup paths.
  1015. sys.stderr.write(f"⚠ hermes config: {msg}\n")
  1016. if not quiet:
  1017. print(f" ⚠ {msg}")
  1018. else:
  1019. run_migrations(current_ver, results, quiet, unversioned=not has_explicit_version)
  1020. _disable_suspicious_mcp_servers(results, quiet)
  1021. _warn_invalid_platform_toolsets(results, quiet)
  1022. if current_ver < latest_ver and not quiet and not floor_refused:
  1023. print(f"Config version: {current_ver} → {latest_ver}")
  1024. missing_env = get_missing_env_vars(required_only=True)
  1025. if missing_env and not quiet:
  1026. print("\n⚠️ Missing required environment variables:")
  1027. for var in missing_env:
  1028. print(f" • {var['name']}: {var['description']}")
  1029. if interactive and missing_env:
  1030. print("\nLet's configure them now:\n")
  1031. for var in missing_env:
  1032. if var.get("url"):
  1033. print(f" Get your key at: {var['url']}")
  1034. if not _prompt_and_save_env(var["name"], var, f" {var['prompt']}: ", results):
  1035. results["warnings"].append(f"Skipped {var['name']} - some features may not work")
  1036. print()
  1037. if interactive and not quiet:
  1038. _offer_new_optional_env_vars(current_ver, latest_ver, results)
  1039. # New default keys are NOT materialised to disk (load_config() deep-merges DEFAULT_CONFIG at
  1040. # read time); this list only feeds the "N new config option(s)" display.
  1041. results["config_added"].extend(field["key"] for field in get_missing_config_fields())
  1042. if current_ver < latest_ver and not floor_refused:
  1043. config = read_raw_config()
  1044. config["_config_version"] = latest_ver
  1045. _persist_migration(config)
  1046. missing_skill_config = get_missing_skill_config_vars()
  1047. if missing_skill_config and interactive and not quiet:
  1048. _offer_skill_config_vars(missing_skill_config, results)
  1049. return results
  1050. def _disable_suspicious_mcp_servers(results: dict[str, Any], quiet: bool) -> None:
  1051. """Post-migration: disable exfiltration-shaped MCP stdio entries (hand-edited or from older
  1052. installs). The stanza is preserved for auditability but marked disabled."""
  1053. config = read_raw_config()
  1054. # Preserve the stanza for auditability but mark it disabled so the next startup will not spawn it.
  1055. # (#45620)
  1056. raw_mcp_servers = config.get("mcp_servers")
  1057. if not isinstance(raw_mcp_servers, dict):
  1058. return
  1059. try:
  1060. from hermes_cli.mcp_security import validate_mcp_server_entry
  1061. except Exception:
  1062. return
  1063. mcp_touched = False
  1064. for server_name, entry in raw_mcp_servers.items():
  1065. issues = validate_mcp_server_entry(server_name, entry) if isinstance(entry, dict) else None
  1066. if not issues:
  1067. continue
  1068. entry["enabled"] = False
  1069. mcp_touched = True
  1070. results["warnings"].append(f"Disabled suspicious MCP server '{server_name}'")
  1071. if not quiet:
  1072. for issue in issues:
  1073. print(f" ⚠ {issue}")
  1074. print(f" ⚠ Disabled MCP server '{server_name}' pending review")
  1075. if mcp_touched:
  1076. config["mcp_servers"] = raw_mcp_servers
  1077. _persist_migration(config)
  1078. def _warn_invalid_platform_toolsets(results: dict[str, Any], quiet: bool) -> None:
  1079. """Surface invalid toolset names in platform_toolsets: ``resolve_toolset()`` returns [] for an
  1080. unknown name, silently disabling the affected tools. Best-effort; never blocks migration."""
  1081. try:
  1082. from hermes_cli.toolset_validation import saved_toolset_resolver, validate_platform_toolsets
  1083. config = read_raw_config()
  1084. for w in validate_platform_toolsets(config.get("platform_toolsets"), saved_toolset_resolver(config)):
  1085. results["warnings"].append(w)
  1086. if not quiet:
  1087. print(f" ⚠ {w}")
  1088. except Exception as _ts_val_err:
  1089. logger.debug("platform_toolsets validation skipped: %s", _ts_val_err)
  1090. def _offer_list(heading: str, items: list[str], question: str) -> bool:
  1091. """Print a bulleted offer list and ask; False (with the "set later" hint) when declined."""
  1092. print(heading)
  1093. for item in items:
  1094. print(f" • {item}")
  1095. print()
  1096. if not _ask_yes_no(question):
  1097. print(" Set later with: hermes config set <key> <value>")
  1098. return False
  1099. print()
  1100. return True
  1101. def _offer_new_optional_env_vars(current_ver: int, latest_ver: int, results: dict[str, Any]) -> None:
  1102. """Interactively offer env vars that are NEW since the user's previous config version."""
  1103. new_var_names: set = set()
  1104. for ver in range(current_ver + 1, latest_ver + 1):
  1105. new_var_names.update(ENV_VARS_BY_VERSION.get(ver, []))
  1106. new_and_unset = [
  1107. (name, OPTIONAL_ENV_VARS[name])
  1108. for name in sorted(new_var_names)
  1109. if not get_env_value(name) and name in OPTIONAL_ENV_VARS]
  1110. if not new_and_unset or not _offer_list(
  1111. f"\n {len(new_and_unset)} new optional key(s) in this update:",
  1112. [f"{name} — {info.get('description', '')}" for name, info in new_and_unset],
  1113. " Configure new keys? [y/N]: "):
  1114. return
  1115. for name, info in new_and_unset:
  1116. print(f" {info.get('description', name)}")
  1117. if info.get("url"):
  1118. print(f" Get your key at: {info['url']}")
  1119. _prompt_and_save_env(name, info, f" {info.get('prompt', name)} (Enter to skip): ", results)
  1120. print()
  1121. def _offer_skill_config_vars(missing_skill_config: list[dict[str, Any]], results: dict[str, Any]) -> None:
  1122. """Prompt for skill-declared settings that are missing/empty and persist the answers."""
  1123. if not _offer_list(
  1124. f"\n {len(missing_skill_config)} skill setting(s) not configured:",
  1125. [f"{v['key']} — {v['description']} (from skill: {v.get('skill', 'unknown')})" for v in missing_skill_config],
  1126. " Configure skill settings? [y/N]: "):
  1127. return
  1128. config = read_raw_config()
  1129. try:
  1130. from agent.skill_utils import SKILL_CONFIG_PREFIX
  1131. except Exception:
  1132. SKILL_CONFIG_PREFIX = "skills.config"
  1133. for var in missing_skill_config:
  1134. default = var.get("default", "")
  1135. default_hint = f" (default: {default})" if default else ""
  1136. value = line_input(f" {var['prompt']}{default_hint}: ").strip() or str(default or "")
  1137. if value:
  1138. _set_nested(config, f"{SKILL_CONFIG_PREFIX}.{var['key']}", value)
  1139. results["config_added"].append(var["key"])
  1140. print(f" ✓ Saved {var['key']} = {value}")
  1141. else:
  1142. results["warnings"].append(
  1143. f"Skipped {var['key']} — skill '{var.get('skill', '?')}' may ask for it later")
  1144. print()
  1145. _persist_migration(config)
  1146. def _merge_partial_save(raw: dict, override: dict) -> dict:
  1147. """Merge *override* over *raw* for partial ``save_config`` writes.
  1148. Omitted top-level sections are preserved; shared dict sections deep-merge so one nested key
  1149. can change without dropping siblings on disk. Key REMOVALS are not supported here —
  1150. migrations go through ``_persist_migration`` with a full ``read_raw_config()`` dict."""
  1151. result = copy.deepcopy(override)
  1152. for key, value in raw.items():
  1153. if key not in result:
  1154. result[key] = copy.deepcopy(value)
  1155. elif isinstance(result.get(key), dict) and isinstance(value, dict):
  1156. result[key] = _deep_merge(value, result[key])
  1157. return result
  1158. def _deep_merge(base: dict, override: dict) -> dict:
  1159. """Recursively merge *override* into *base*: dict-over-dict recurses (so overriding one leaf
  1160. keeps sibling defaults), and ``None`` over a dict section is ignored.
  1161. An empty section key in config.yaml (``terminal:`` with no value) parses as YAML ``None``; treating that
  1162. as an override would replace the entire default dict with ``None`` and crash every downstream consumer
  1163. that expects a mapping (#58277).
  1164. """
  1165. result = base.copy()
  1166. for key, value in override.items():
  1167. over_dict = isinstance(result.get(key), dict)
  1168. if over_dict and isinstance(value, dict):
  1169. result[key] = _deep_merge(result[key], value)
  1170. elif not (over_dict and value is None):
  1171. result[key] = value
  1172. return result
  1173. def _strip_dotted_keys(cfg: dict, dotted_keys: set) -> tuple[dict, set]:
  1174. """Remove dotted leaf keys from *cfg* in place -> ``(cfg, keys_actually_present)``.
  1175. ``save_config`` drops managed-scope leaves this way so a bulk write never persists a user
  1176. value that would lose to the managed layer on the next load."""
  1177. stripped: set = set()
  1178. for dotted in dotted_keys:
  1179. *parents, leaf = dotted.split(".")
  1180. node = cfg_get(cfg, *parents)
  1181. if isinstance(node, dict) and leaf in node:
  1182. del node[leaf]
  1183. stripped.add(dotted)
  1184. return cfg, stripped
  1185. _ENV_REF_RE = re.compile(r"\${([^}]+)}")
  1186. def _env_ref_lookup(name: str) -> Optional[str]:
  1187. """Resolve the env var behind a ``${VAR}`` / ``${env:VAR}`` ref — plain ``os.environ`` outside
  1188. a profile secret scope (legacy behavior for the default profile).
  1189. Inside a scope (a multiplexed gateway turn, a secondary profile's config load, a cron job) the read goes
  1190. through ``agent.secret_scope.get_secret`` so the ref resolves against *that* profile's ``.env``: under
  1191. multiplexing a miss is a miss, never another profile's ``os.environ`` value (#84079 — every profile
  1192. "had" the default profile's ``${MATRIX_ACCESS_TOKEN}`` and fanned out). Same policy as
  1193. ``gateway.config._getenv`` and ``get_env_value``.
  1194. """
  1195. try:
  1196. from agent.secret_scope import current_secret_scope, get_secret as _get_secret
  1197. except Exception:
  1198. return os.environ.get(name)
  1199. if current_secret_scope() is None:
  1200. return os.environ.get(name)
  1201. return _get_secret(name)
  1202. def _env_expand_match(m: re.Match) -> str:
  1203. """Expand one ``${VAR}`` (legacy bare name) or ``${env:VAR}`` (Cursor-style SecretRef).
  1204. Other SecretRef sources (``file:``, ``bitwarden:``, ``vault:``...) are NOT resolved here:
  1205. external backends inject their values into the environment at startup (the ``secrets:``
  1206. block), so a config ref only ever needs the env shape. Unresolved refs stay verbatim so
  1207. callers can detect them."""
  1208. raw = m.group(0)
  1209. inner = m.group(1).strip()
  1210. name = _env_ref_var_name(inner)
  1211. if name is None:
  1212. if not inner.startswith("env:") and _is_non_env_secret_ref(inner):
  1213. logger.warning(
  1214. "Config ref %r uses source %r which is not resolvable in "
  1215. "config.yaml — external secret sources inject env vars at "
  1216. "startup, so reference the variable as ${env:NAME} instead",
  1217. raw, inner.split(":", 1)[0])
  1218. return raw # non-env source, or empty ``${env:}``
  1219. val = _env_ref_lookup(name)
  1220. if val is not None:
  1221. return val
  1222. if inner.startswith("env:"):
  1223. logger.warning(
  1224. "Config ref %r: %s is not set (check ~/.hermes/.env); "
  1225. "keeping the literal placeholder", raw, name)
  1226. return raw
  1227. def _is_non_env_secret_ref(ref: str) -> bool:
  1228. """True for a SecretRef body with a non-``env`` source (``bitwarden:FOO``, ``vault:...``)."""
  1229. return ":" in ref and re.match(r"^[a-z][a-z0-9_-]*:", ref) is not None
  1230. def _env_ref_var_name(ref: str) -> Optional[str]:
  1231. """Env-var name a ``${...}`` body reads, or None for a non-env source / empty ``env:``."""
  1232. ref = ref.strip()
  1233. if ref.startswith("env:"):
  1234. return ref[len("env:"):].strip() or None
  1235. if _is_non_env_secret_ref(ref):
  1236. return None
  1237. return ref
  1238. def _expand_env_vars(obj):
  1239. """Recursively expand ``${VAR}`` / ``${env:VAR}`` in string values (keys/non-strings untouched)."""
  1240. if isinstance(obj, str):
  1241. return _ENV_REF_RE.sub(_env_expand_match, obj)
  1242. if isinstance(obj, dict):
  1243. return {k: _expand_env_vars(v) for k, v in obj.items()}
  1244. if isinstance(obj, list):
  1245. return [_expand_env_vars(item) for item in obj]
  1246. return obj
  1247. def _env_ref_snapshot(obj, snapshot=None):
  1248. """Map each env-sourced ``${...}`` ref in *obj* to its current value.
  1249. Stored with cached ``load_config()`` results so a cache hit can detect that the expansion was
  1250. made against a different environment (load before ``load_hermes_dotenv()``, in-process
  1251. rotation) — file mtime/size alone cannot see either.
  1252. See #58514.
  1253. """
  1254. if snapshot is None:
  1255. snapshot = {}
  1256. if isinstance(obj, str):
  1257. for raw in _ENV_REF_RE.findall(obj):
  1258. name = _env_ref_var_name(raw)
  1259. if name is not None:
  1260. snapshot[name] = _env_ref_lookup(name)
  1261. elif isinstance(obj, dict):
  1262. for value in obj.values():
  1263. _env_ref_snapshot(value, snapshot)
  1264. elif isinstance(obj, list):
  1265. for item in obj:
  1266. _env_ref_snapshot(item, snapshot)
  1267. return snapshot
  1268. def _items_by_unique_name(items):
  1269. """Return a name-indexed dict only when all items have unique string names."""
  1270. if not isinstance(items, list):
  1271. return None
  1272. indexed = {}
  1273. for item in items:
  1274. if not isinstance(item, dict) or not isinstance(item.get("name"), str):
  1275. return None
  1276. name = item["name"]
  1277. if name in indexed:
  1278. return None
  1279. indexed[name] = item
  1280. return indexed
  1281. def _preserve_env_ref_templates(current, raw, loaded_expanded=None):
  1282. """Restore raw ``${VAR}`` templates where the value is otherwise unchanged, so persisting a
  1283. loaded (expanded) config never writes the plaintext secret back to ``config.yaml``."""
  1284. if isinstance(current, str) and isinstance(raw, str) and _ENV_REF_RE.search(raw):
  1285. if current in (raw, loaded_expanded) or _expand_env_vars(raw) == current:
  1286. return raw
  1287. return current
  1288. if isinstance(current, dict) and isinstance(raw, dict):
  1289. return {
  1290. key: _preserve_env_ref_templates(
  1291. value, raw.get(key),
  1292. loaded_expanded.get(key) if isinstance(loaded_expanded, dict) else None)
  1293. for key, value in current.items()}
  1294. if isinstance(current, list) and isinstance(raw, list):
  1295. # Match named objects (e.g. custom_providers) by name so reordering keeps templates;
  1296. # with duplicate names fall back to positional matching rather than shadowing an entry.
  1297. current_by_name = _items_by_unique_name(current)
  1298. raw_by_name = _items_by_unique_name(raw)
  1299. loaded_by_name = _items_by_unique_name(loaded_expanded)
  1300. if current_by_name is not None and raw_by_name is not None:
  1301. return [
  1302. _preserve_env_ref_templates(
  1303. item, raw_by_name.get(item.get("name")),
  1304. loaded_by_name.get(item.get("name")) if loaded_by_name is not None else None)
  1305. for item in current]
  1306. return [
  1307. _preserve_env_ref_templates(
  1308. item,
  1309. raw[index] if index < len(raw) else None,
  1310. loaded_expanded[index]
  1311. if isinstance(loaded_expanded, list) and index < len(loaded_expanded)
  1312. else None)
  1313. for index, item in enumerate(current)]
  1314. return current
  1315. def _explicit_config_paths(config: dict[str, Any]) -> set[tuple[str, ...]]:
  1316. """Leaf paths explicitly present in a RAW (un-normalized) config, so values injected by
  1317. normalisation are never mistaken for user-set ones. Feeds ``_strip_default_values``."""
  1318. paths: set[tuple[str, ...]] = set()
  1319. def _walk(value: Any, path: tuple[str, ...]) -> None:
  1320. if isinstance(value, dict):
  1321. for key, child in value.items():
  1322. _walk(child, path + (key,))
  1323. elif path:
  1324. paths.add(path)
  1325. _walk(config, ())
  1326. return paths
  1327. def _strip_default_values(
  1328. config: dict[str, Any], defaults: dict[str, Any] = DEFAULT_CONFIG,
  1329. preserve_keys: Optional[set[tuple[str, ...]]] = None) -> dict[str, Any]:
  1330. """Return *config* without keys whose values match *defaults*.
  1331. Paths in *preserve_keys* (explicitly present in the user's raw config) are always kept even
  1332. when equal to the default. Dicts whose every child is stripped are removed entirely so
  1333. default-only subtrees never bloat ``config.yaml``."""
  1334. preserve_keys = {("_config_version",)} | set(preserve_keys or ())
  1335. # None is a valid authored value, not a signal to remove the node.
  1336. dropped = object()
  1337. def _strip(value: Any, default: Any, path: tuple[str, ...]) -> Any:
  1338. if path in preserve_keys:
  1339. return copy.deepcopy(value)
  1340. if isinstance(value, dict) and value:
  1341. default_dict = default if isinstance(default, dict) else {}
  1342. stripped = {k: _strip(v, default_dict.get(k), path + (k,)) for k, v in value.items()}
  1343. return {k: v for k, v in stripped.items() if v is not dropped} or dropped
  1344. return dropped if value == default else copy.deepcopy(value)
  1345. stripped = _strip(config, defaults, ())
  1346. return {} if stripped is dropped else stripped
  1347. def split_model_config_default(raw_default: Any) -> tuple[str, str]:
  1348. """Canonicalize ``model.default``/``model.model`` -> ``(model, provider)``; a dict value pairs
  1349. the model string with the provider it must be routed through."""
  1350. if isinstance(raw_default, dict):
  1351. provider = str(raw_default.get("provider") or "").strip()
  1352. model = raw_default.get("model") or raw_default.get("default")
  1353. return (str(model or "").strip(), provider)
  1354. return (str(raw_default or "").strip(), "")
  1355. def _normalize_root_model_keys(config: dict[str, Any]) -> dict[str, Any]:
  1356. """Canonicalize the ``model`` section at the single load/save chokepoint.
  1357. Root-level ``provider``/``base_url``/``context_length`` (older layouts) are moved under
  1358. ``model`` only when the corresponding ``model.*`` key is empty — never overriding. ``api_base``
  1359. (the OpenAI-SDK/LiteLLM name users reach for) is an alias for ``base_url``; the runtime reads
  1360. only ``model.base_url``. A dict-valued ``default``/``model``/``name`` is flattened so no reader
  1361. sees a nested dict, and the id is canonicalized to ``default``.
  1362. Also aliases ``api_base`` → ``base_url`` (issue #8919). ``api_base`` is the intuitive name OpenAI-SDK /
  1363. LiteLLM users reach for, and ``hermes config set`` blindly accepts any dotted key — so
  1364. ``model.api_base`` got written, confirmed, and then silently ignored by the runtime resolver (which
  1365. reads only ``model.base_url``), causing requests to fall back to OpenRouter. We migrate the alias to the
  1366. canonical key (fallback-only — never override an explicit ``base_url``) and drop the alias so it can't
  1367. confuse later loads.
  1368. Finally, canonicalizes the model-id key to ``model.default`` (issue #34500). The runtime resolver and
  1369. ~14 other readers select the chat model via ``model.default``; ``model.model`` was already aliased
  1370. inline at some sites but ``model.name`` was not, so a custom-provider config like ``model: {name: <id>,
  1371. provider: <custom>}`` resolved to an empty model and the API request went out with ``model=`` (HTTP 400
  1372. from OpenAI-compatible backends) — while display paths (``hermes status``/``dump``) read ``name`` and
  1373. *showed* the model, making the failure silent. Normalizing here (the single load/save chokepoint) means
  1374. every reader, present and future, sees a populated ``default`` and the stale alias is migrated out of
  1375. config.yaml on the next save. Precedence: ``default`` > ``model`` > ``name`` (never overrides an
  1376. explicit ``default``, so existing configs are unaffected).
  1377. """
  1378. model_in = config.get("model")
  1379. model_provider = model_in.get("provider") if isinstance(model_in, dict) else None
  1380. needs_model_work = (model_provider is not None and not isinstance(model_provider, str)) or (
  1381. isinstance(model_in, dict) and (
  1382. model_in.get("api_base")
  1383. or model_in.get("model") or model_in.get("name")
  1384. or any(isinstance(model_in.get(k), dict) for k in ("default", "model", "name"))))
  1385. has_root = any(config.get(k) for k in ("provider", "base_url", "context_length", "api_base"))
  1386. if not has_root and not needs_model_work:
  1387. return config
  1388. config = dict(config)
  1389. model = config.get("model")
  1390. model = dict(model) if isinstance(model, dict) else {"default": model} if model else {}
  1391. config["model"] = model
  1392. # Flatten ``{provider: <p>, model: <m>}``. The nested provider wins over the merged default
  1393. # ``"auto"`` (which runtime resolution treats as authoritative) but never over a configured one.
  1394. for _key in ("default", "model", "name"):
  1395. _val = model.get(_key)
  1396. if isinstance(_val, dict):
  1397. _nested_model = _val.get("model") or _val.get("default")
  1398. _nested_provider = str(_val.get("provider") or "").strip()
  1399. model[_key] = str(_nested_model or "").strip()
  1400. if _nested_provider:
  1401. _outer_provider = str(model.get("provider") or "").strip()
  1402. if not _outer_provider or _outer_provider == "auto":
  1403. model["provider"] = _nested_provider
  1404. for key in ("provider", "base_url", "context_length"):
  1405. root_val = config.get(key)
  1406. if root_val and not model.get(key):
  1407. model[key] = root_val
  1408. config.pop(key, None)
  1409. # Provider identity is a string (#117345): an unquoted YAML scalar (``provider: 2``)
  1410. # loads as int, and downstream readers call ``(provider or "").strip()`` — a gateway
  1411. # turn dies before the agent runs. Normalize at the load/save chokepoint so every
  1412. # reader (and the next save, which rewrites config.yaml) heals the persisted value.
  1413. # Guard on presence: coerce_provider_id(None) is "" — injecting an empty key into
  1414. # provider-less configs would add churn to config.yaml on the next save.
  1415. if model.get("provider") is not None:
  1416. model["provider"] = coerce_provider_id(model.get("provider"))
  1417. for alias_val in (config.get("api_base"), model.get("api_base")):
  1418. if alias_val and not model.get("base_url"):
  1419. model["base_url"] = alias_val
  1420. config.pop("api_base", None)
  1421. model.pop("api_base", None)
  1422. # ``model``/``name`` are last-resort aliases (in that order), then dropped.
  1423. alias = model.get("model") or model.get("name")
  1424. if not model.get("default") and alias:
  1425. model["default"] = alias
  1426. if model.get("default"):
  1427. model.pop("model", None)
  1428. model.pop("name", None)
  1429. return config
  1430. def _normalize_max_turns_config(config: dict[str, Any]) -> dict[str, Any]:
  1431. """Move legacy root-level ``max_turns`` under ``agent``; the schema default is injected only
  1432. when the user set max_turns somewhere (so save_config can otherwise omit it)."""
  1433. config = dict(config)
  1434. agent_config = dict(config.get("agent") or {})
  1435. if "max_turns" in config and "max_turns" not in agent_config:
  1436. agent_config["max_turns"] = config["max_turns"]
  1437. if agent_config or "agent" in config: # a sparse save must not grow an `agent: {}` section
  1438. config["agent"] = agent_config
  1439. config.pop("max_turns", None)
  1440. return config
  1441. def _canonicalize_config(config: dict[str, Any]) -> dict[str, Any]:
  1442. """The load/save normalization pipeline: max_turns relocation, then model-section canon."""
  1443. return _normalize_root_model_keys(_normalize_max_turns_config(config))
  1444. # Sentinel for an unlimited turn budget. ``sys.maxsize`` survives the str->int round-trip through
  1445. # the HERMES_MAX_ITERATIONS env bridge, works in every ``<``/``>=``/``max - used`` comparison in
  1446. # the iteration budget without an "unlimited" special case, and is unreachable in practice.
  1447. TURN_LIMIT_UNLIMITED = sys.maxsize
  1448. # Spellings that mean "no limit" (compared lowercased, whitespace-stripped).
  1449. _UNLIMITED_SPELLINGS = frozenset({
  1450. "none", "null", "unlimited", "infinite", "infinity", "inf", "∞", "-1", "0"})
  1451. def resolve_turn_limit(raw: Any, default: int = TURN_LIMIT_UNLIMITED) -> int:
  1452. """Normalize a raw ``agent.max_turns`` value into an int iteration cap (always >= 1)."""
  1453. # bool is a subclass of int; reject explicitly so True/False don't become 1/0.
  1454. if raw is None or isinstance(raw, bool):
  1455. return default
  1456. if isinstance(raw, (int, float)):
  1457. n = int(raw)
  1458. elif isinstance(raw, str):
  1459. s = raw.strip().lower()
  1460. if not s:
  1461. return default
  1462. if s in _UNLIMITED_SPELLINGS:
  1463. return TURN_LIMIT_UNLIMITED
  1464. try:
  1465. n = int(s)
  1466. except ValueError:
  1467. try:
  1468. n = int(float(s))
  1469. except ValueError:
  1470. logger.debug("resolve_turn_limit: unparseable value %r → default %d", raw, default)
  1471. return default
  1472. else:
  1473. # Unknown type (list, dict, …) — don't crash the agent over a bad config.
  1474. logger.debug("resolve_turn_limit: unsupported type %s (%r) → default %d", type(raw).__name__, raw, default)
  1475. return default
  1476. return TURN_LIMIT_UNLIMITED if n <= 0 else n
  1477. def cfg_get(cfg: Optional[dict[str, Any]], *keys: str, default: Any = None) -> Any:
  1478. """Traverse nested dict keys safely, returning ``default`` on any miss.
  1479. Explicit ``None`` values are returned as-is (``dict.get`` semantics: ``default`` only when the
  1480. key is absent). Named ``cfg_get`` to avoid shadowing the ubiquitous ``cfg_path`` local."""
  1481. if not isinstance(cfg, dict):
  1482. return default
  1483. node: Any = cfg
  1484. for key in keys:
  1485. if not isinstance(node, dict) or key not in node:
  1486. return default
  1487. node = node[key]
  1488. return node
  1489. def _raw_config_cache_hit(path_key: str, cache_key: tuple[Any, ...]) -> Optional[dict[str, Any]]:
  1490. """Pure lookup: the cached raw config for ``path_key`` if its signature equals ``cache_key``,
  1491. else ``None``. Shared by the lock-free fast path and the locked re-check of
  1492. ``_read_raw_config_impl`` so the predicate cannot drift between them."""
  1493. cached = _RAW_CONFIG_CACHE.get(path_key)
  1494. if cached is not None and cached[:len(cache_key)] == cache_key:
  1495. return cached[len(cache_key)]
  1496. return None
  1497. def _raw_config_cache_store(path_key: str, cache_key: tuple[Any, ...], data: dict[str, Any]) -> None:
  1498. """Publish ``data`` (caller-owned copy) as the raw config for ``path_key`` at ``cache_key``.
  1499. One whole-tuple replace, so the lock-free readers see either the old or the new entry."""
  1500. _RAW_CONFIG_CACHE[path_key] = (*cache_key, data)
  1501. def _worker_config_snapshot() -> Optional[dict[str, Any]]:
  1502. """A safe worker's frozen config, or None. Install-time loads run from ``hermes_cli`` alone
  1503. (the installer's completion step ships no ``agent`` package), and without ``agent`` there
  1504. is no worker policy to consult."""
  1505. try:
  1506. from agent.safe_worker_policy import worker_config_snapshot
  1507. except ModuleNotFoundError as exc:
  1508. if exc.name != "agent":
  1509. raise
  1510. return None
  1511. return worker_config_snapshot()
  1512. def _read_raw_config_impl(*, want_deepcopy: bool) -> dict[str, Any]:
  1513. snapshot = _worker_config_snapshot()
  1514. if snapshot is not None:
  1515. return snapshot
  1516. # Lock-free fast path for cache hits — same shape as `_load_config_impl`. `_RAW_CONFIG_CACHE`
  1517. # publishes each entry as ONE `(*sig, data)` tuple replaced wholesale, so a reader sees either
  1518. # the complete old entry or the complete new one; `_CONFIG_LOCK` only serializes the re-parse
  1519. # and the writers (`save_config()` holds it across an atomic YAML write, which used to stall
  1520. # every cached read for the duration). A lost race just falls through to the locked re-check.
  1521. try:
  1522. config_path = get_config_path()
  1523. cache_key = config_cache_version(config_path)
  1524. hit = _raw_config_cache_hit(str(config_path), cache_key)
  1525. if hit is not None:
  1526. return copy.deepcopy(hit) if want_deepcopy else hit
  1527. except Exception:
  1528. pass
  1529. with _CONFIG_LOCK:
  1530. config_path = get_config_path()
  1531. try:
  1532. cache_key = config_cache_version(config_path)
  1533. except FileNotFoundError:
  1534. return {}
  1535. except OSError as e:
  1536. return FailedConfigRead(error=e)
  1537. path_key = str(config_path)
  1538. hit = _raw_config_cache_hit(path_key, cache_key)
  1539. if hit is not None:
  1540. return copy.deepcopy(hit) if want_deepcopy else hit
  1541. try:
  1542. data = read_config_doc(config_path) or {}
  1543. except Exception as e:
  1544. _warn_config_parse_failure(config_path, e)
  1545. return FailedConfigRead(error=e)
  1546. if not isinstance(data, dict):
  1547. return FailedConfigRead(error=TypeError(f"top-level YAML must be a mapping, got {type(data).__name__}"))
  1548. _CONFIG_PARSE_FAILURES.pop(path_key, None) # the file reads now (a transient error left the record)
  1549. # The cache stores its own deepcopy. The readonly path returns THAT object (identity
  1550. # invariant: later cache hits return the same dict); the mutable path returns the parse.
  1551. cached_copy = copy.deepcopy(data)
  1552. _raw_config_cache_store(path_key, cache_key, cached_copy)
  1553. return data if want_deepcopy else cached_copy
  1554. def read_raw_config() -> dict[str, Any]:
  1555. """Read config.yaml as-is (no defaults merged, no migration); ``{}`` if missing/unparseable.
  1556. Cached on the file signature (mtime_ns, size, ino, ctime_ns); returns a deepcopy since callers mutate before ``save_config()``."""
  1557. return _read_raw_config_impl(want_deepcopy=True)
  1558. def read_user_config_raw(config_path: Optional[Path] = None) -> dict[str, Any]:
  1559. """Read a user ``config.yaml`` EXACTLY as written (no defaults/overlay/expansion, no cache).
  1560. ONLY legal for write-back round-trips and raw-file diagnostics — behavioral reads must use
  1561. load_config()/load_config_readonly()."""
  1562. if config_path is None:
  1563. config_path = get_config_path()
  1564. try:
  1565. data = read_config_doc(config_path) or {}
  1566. except FileNotFoundError:
  1567. return {}
  1568. return data if isinstance(data, dict) else {}
  1569. def read_raw_config_readonly() -> dict[str, Any]:
  1570. """``read_raw_config()`` without the per-call deepcopy, for callers that ONLY READ.
  1571. **Mutating the result corrupts the in-process cache for every subsequent caller.** Meant for
  1572. per-turn policy checks that were paying a full config deepcopy 2-3x per agent turn."""
  1573. return _read_raw_config_impl(want_deepcopy=False)
  1574. def require_readable_config_before_write(config_path: Optional[Path] = None) -> dict[str, Any]:
  1575. """Refuse to replace an existing config.yaml that cannot be read or parsed; return the mapping.
  1576. Guards two collapse-to-empty failure modes that would let a read-then-write caller silently
  1577. wipe user overrides: an unreadable file (permissions / broken mount) and an unparseable or
  1578. non-mapping root — bare-``except`` loaders treat both as ``{}``, so a subsequent write would
  1579. replace the recoverable file with only the caller's partial dict. Fails closed."""
  1580. if config_path is None:
  1581. snapshot = _worker_config_snapshot()
  1582. if snapshot is not None:
  1583. # A bypass worker's config IS its frozen snapshot; it never reads the profile file.
  1584. return copy.deepcopy(snapshot)
  1585. config_path = get_config_path()
  1586. try:
  1587. config_version(config_path)
  1588. except FileNotFoundError:
  1589. return {}
  1590. except OSError as exc:
  1591. raise _refuse_overwrite(config_path, "cannot be accessed", exc, _FIX_PERMS) from exc
  1592. try:
  1593. loaded = read_config_doc(config_path)
  1594. except OSError as exc:
  1595. raise _refuse_overwrite(config_path, "cannot be read", exc, _FIX_PERMS) from exc
  1596. except Exception as exc:
  1597. _warn_config_parse_failure(config_path, exc, fallback="refuse-write")
  1598. raise _refuse_overwrite(
  1599. config_path, "has a formatting error", exc, _FIX_YAML.format(backups=_backups_dir_display())) from exc
  1600. if loaded is None:
  1601. return {}
  1602. if not isinstance(loaded, dict):
  1603. exc = TypeError(f"top-level YAML must be a mapping, got {type(loaded).__name__}")
  1604. _warn_config_parse_failure(config_path, exc, fallback="refuse-write")
  1605. raise _refuse_overwrite(
  1606. config_path, f"must start with settings names, but its top level is a {type(loaded).__name__}",
  1607. exc, _FIX_YAML.format(backups=_backups_dir_display())) from exc
  1608. return loaded
  1609. def _omitted_config_paths(
  1610. existing: dict[str, Any], proposed: dict[str, Any], prefix: tuple[str, ...] = (),
  1611. ) -> list[str]:
  1612. """Mapping paths that *proposed* would delete by omission from *existing*.
  1613. The round-trip writer recurses through mappings, so the completeness check must recurse too:
  1614. checking top-level key counts still lets a partial ``plugins: {...}`` payload erase sibling
  1615. settings inside that section. Replacing a non-empty mapping with a scalar/list is likewise a
  1616. deletion of that mapping's children and is reported at the mapping path.
  1617. """
  1618. omitted: list[str] = []
  1619. for key, old_value in existing.items():
  1620. path = (*prefix, str(key))
  1621. if key not in proposed:
  1622. omitted.append(".".join(path))
  1623. continue
  1624. new_value = proposed[key]
  1625. if isinstance(old_value, dict):
  1626. if isinstance(new_value, dict):
  1627. omitted.extend(_omitted_config_paths(old_value, new_value, path))
  1628. elif old_value:
  1629. omitted.append(".".join(path))
  1630. return omitted
  1631. def _write_config_state(
  1632. config_path: Path, data: dict[str, Any], *, allow_omissions: bool,
  1633. extra_content_on_create: Optional[str] = None,
  1634. ) -> None:
  1635. """Shared comment-preserving config writer; omission policy is selected by the public wrapper."""
  1636. _refuse_failed_read(config_path, data)
  1637. if not allow_omissions:
  1638. # A guard read, not the caller's read: *data* came from the caller's own earlier read, so a
  1639. # Remote Config save must still be diffed against THAT read, not a poll that landed since.
  1640. from hermes_cli.config_backend import keeping_read_base
  1641. existing = keeping_read_base(lambda: require_readable_config_before_write(config_path))
  1642. omitted = _omitted_config_paths(existing, data)
  1643. if omitted:
  1644. shown = ", ".join(omitted[:12])
  1645. if len(omitted) > 12:
  1646. shown += f", +{len(omitted) - 12} more"
  1647. exc = ValueError(f"omitted config paths: {shown}")
  1648. raise _refuse_overwrite(
  1649. config_path,
  1650. "would lose settings omitted by this write",
  1651. exc,
  1652. "Pass the complete current config, or use atomic_config_replace() only when "
  1653. "deletion by omission is deliberate.",
  1654. ) from exc
  1655. write_config_document(config_path, data, extra_content_on_create=extra_content_on_create)
  1656. def atomic_config_write(
  1657. config_path: Path, data: dict[str, Any], *, extra_content_on_create: Optional[str] = None,
  1658. ) -> None:
  1659. """Persist config without allowing an incomplete mapping to delete existing settings.
  1660. Values explicitly present in *data* may change, but every existing mapping path must remain.
  1661. Use ``atomic_config_replace`` for a deliberate full-state replacement where omitted keys are
  1662. meant to be deleted. Both paths retain the unreadable-file guard and ruamel comment preservation.
  1663. """
  1664. _write_config_state(
  1665. config_path, data, allow_omissions=False, extra_content_on_create=extra_content_on_create)
  1666. def atomic_config_replace(
  1667. config_path: Path, data: dict[str, Any], *, extra_content_on_create: Optional[str] = None,
  1668. ) -> None:
  1669. """Persist the complete desired config state; omitted mapping keys are deliberately deleted."""
  1670. _write_config_state(
  1671. config_path, data, allow_omissions=True, extra_content_on_create=extra_content_on_create)
  1672. def load_config() -> dict[str, Any]:
  1673. """Load the merged configuration (DEFAULT_CONFIG + config.yaml + managed scope, env-expanded).
  1674. Cached on the file signature; returns a deepcopy since most call sites mutate the result.
  1675. Read-only hot paths should use ``load_config_readonly()`` to skip the deepcopy."""
  1676. from agent.runtime_context import configuration
  1677. embedded = configuration(DEFAULT_CONFIG)
  1678. return embedded if embedded is not None else _load_config_impl(want_deepcopy=True)
  1679. def load_config_readonly() -> dict[str, Any]:
  1680. """``load_config()`` without the defensive deepcopy (~half of the 265us cache-hit cost).
  1681. **Mutating the returned dict (or any nested structure) corrupts the in-process cache for
  1682. every subsequent caller** — only for code paths that never write to the result."""
  1683. from agent.runtime_context import configuration
  1684. embedded = configuration(DEFAULT_CONFIG)
  1685. return embedded if embedded is not None else _load_config_impl(want_deepcopy=False)
  1686. def _ensure_dict(parent: dict[str, Any], key: str) -> dict[str, Any]:
  1687. """Return ``parent[key]`` as a dict, replacing a missing or non-dict value with ``{}``."""
  1688. child = parent.get(key)
  1689. if not isinstance(child, dict):
  1690. child = {}
  1691. parent[key] = child
  1692. return child
  1693. def write_platform_config_field(
  1694. platform_key: str, field_key: str, value: Any, *, raw: bool = False) -> None:
  1695. """Persist one scalar field under ``platforms.<platform_key>``.
  1696. ``raw=True`` (CLI setup flows) edits only the user's raw file; dashboard routes use the
  1697. default loaded-config path to keep their profile-scoped ``load_config`` behavior."""
  1698. config = read_raw_config() if raw else load_config()
  1699. platforms = _ensure_dict(config, "platforms")
  1700. _ensure_dict(platforms, platform_key)[field_key] = value
  1701. save_config(config)
  1702. # ``terminal.<key>`` -> env var read by tools.terminal_tool. Every key maps to ``TERMINAL_<KEY>``
  1703. # except ``backend`` (historically ``TERMINAL_ENV``).
  1704. TERMINAL_CONFIG_ENV_MAP = {
  1705. "backend": "TERMINAL_ENV",
  1706. **{
  1707. key: f"TERMINAL_{key.upper()}"
  1708. for key in (
  1709. "modal_mode", "degraded_mode", "cwd", "temp_dir", "timeout", "lifetime_seconds",
  1710. "docker_image", "docker_forward_env", "modal_image",
  1711. "daytona_image", "vercel_runtime", "vercel_image", "ssh_host", "ssh_user", "ssh_port", "ssh_key",
  1712. "container_cpu", "container_memory", "container_disk", "container_persistent",
  1713. "docker_volumes", "docker_env", "docker_mount_cwd_to_workspace", "docker_network",
  1714. "docker_extra_args", "docker_shm_size", "docker_run_as_host_user", "docker_snap_compat",
  1715. "docker_persist_across_processes", "docker_shared_container_key",
  1716. "docker_orphan_reaper", "sandbox_dir", "persistent_shell")}}
  1717. def _terminal_env_value(value: Any) -> str:
  1718. return json.dumps(value) if isinstance(value, (list, dict)) else str(value)
  1719. def _terminal_config_value_is_bridgeable(key: str, value: Any) -> bool:
  1720. """Return whether a terminal config value owns its mirrored env var."""
  1721. return not (key == "cwd" and str(value or "").strip() in {".", "auto", "cwd"})
  1722. def terminal_config_owned_env_vars(terminal_config: Any) -> set[str]:
  1723. """Return env vars explicitly owned by a raw ``terminal`` config section."""
  1724. if not isinstance(terminal_config, dict):
  1725. return set()
  1726. return {
  1727. env_var
  1728. for key, env_var in TERMINAL_CONFIG_ENV_MAP.items()
  1729. if key in terminal_config
  1730. and _terminal_config_value_is_bridgeable(key, terminal_config[key])}
  1731. def terminal_config_env_var_for_key(key: str) -> Optional[str]:
  1732. """Return the env var mirrored by a ``terminal.*`` config key."""
  1733. return TERMINAL_CONFIG_ENV_MAP.get(key[len("terminal."):]) if key.startswith("terminal.") else None
  1734. def _is_ssh_remote_tilde_cwd(backend: str, cwd: str) -> bool:
  1735. """Whether the remote SSH shell must expand *cwd* itself: ``~`` expanded on the Hermes host
  1736. would name the host/container home instead of the SSH user's."""
  1737. return (backend or "").strip().lower() == "ssh" and (cwd == "~" or cwd.startswith("~/"))
  1738. def apply_terminal_config_to_env(
  1739. *, env: Optional[dict[str, str]] = None, config: Optional[dict[str, Any]] = None,
  1740. override: Optional[bool] = None) -> dict[str, str]:
  1741. """Bridge ``terminal.*`` config into the env vars terminal tools read.
  1742. ``tools.terminal_tool`` is environment-driven because it also runs in child processes (TUI,
  1743. dashboard PTY, gateway workers); this gives those launch paths the same bridge as the CLI
  1744. without importing ``cli.py``. Explicit keys in the user's raw ``terminal`` section override
  1745. matching env values; merged defaults only backfill missing env vars."""
  1746. target = os.environ if env is None else env
  1747. raw_terminal_cfg = read_raw_config().get("terminal")
  1748. file_has_terminal_config = isinstance(raw_terminal_cfg, dict)
  1749. raw_terminal_cfg = raw_terminal_cfg if file_has_terminal_config else {}
  1750. should_override = file_has_terminal_config if override is None else override
  1751. cfg = config if config is not None else load_config_readonly()
  1752. terminal_cfg = cfg.get("terminal", {}) if isinstance(cfg, dict) else {}
  1753. if not isinstance(terminal_cfg, dict):
  1754. return target
  1755. # A caller-supplied config is its own source of explicit keys; otherwise only keys present
  1756. # in raw config.yaml may override existing env values (DEFAULT_CONFIG keys are backfill-only).
  1757. explicit_keys = terminal_cfg.keys() if config is not None else raw_terminal_cfg.keys()
  1758. backend_sources = (terminal_cfg.get("backend"), target.get("TERMINAL_ENV"))
  1759. if not (config is not None or "backend" in raw_terminal_cfg):
  1760. backend_sources = backend_sources[::-1] # env wins when the file did not set backend
  1761. terminal_backend = str(backend_sources[0] or backend_sources[1] or "")
  1762. # Whether docker_image is the user's choice (config.yaml key, or TERMINAL_DOCKER_IMAGE set before
  1763. # any bridge ran) or the shipped default. DockerEnvironment recreates a persisted container on
  1764. # image mismatch only for a pinned image; a default flip keeps the user's sandbox and asks.
  1765. # Children inherit both vars, so a launcher's verdict is kept unless the file pins it.
  1766. if should_override and "docker_image" in explicit_keys:
  1767. target["TERMINAL_DOCKER_IMAGE_PINNED"] = "1"
  1768. elif "TERMINAL_DOCKER_IMAGE_PINNED" not in target:
  1769. target["TERMINAL_DOCKER_IMAGE_PINNED"] = "1" if "TERMINAL_DOCKER_IMAGE" in target else "0"
  1770. for cfg_key, env_var in TERMINAL_CONFIG_ENV_MAP.items():
  1771. if cfg_key not in terminal_cfg:
  1772. continue
  1773. value = terminal_cfg[cfg_key]
  1774. if not _terminal_config_value_is_bridgeable(cfg_key, value):
  1775. continue
  1776. if cfg_key == "cwd":
  1777. raw_cwd = str(value or "").strip()
  1778. if isinstance(value, str) and not _is_ssh_remote_tilde_cwd(terminal_backend, raw_cwd):
  1779. value = os.path.expanduser(value)
  1780. if (should_override and cfg_key in explicit_keys) or env_var not in target:
  1781. target[env_var] = _terminal_env_value(value)
  1782. return target
  1783. def _load_config_cache_sig(config_path: Path) -> tuple[Optional[tuple[Any, ...]], Optional[tuple[Any, ...]]]:
  1784. """Return ``(user_sig, cache_sig)`` for ``_LOAD_CONFIG_CACHE`` (racy-clean guarded, see ``config_cache_version``).
  1785. The managed config file's signature is folded in (zeros = none) so editing it invalidates
  1786. the merged result. ``cache_sig`` is None only when neither file exists (nothing to cache on)."""
  1787. try:
  1788. user_sig: Optional[tuple[Any, ...]] = config_cache_version(config_path)
  1789. except FileNotFoundError:
  1790. user_sig = None
  1791. managed_dir = managed_scope.get_managed_dir()
  1792. try:
  1793. managed_sig = file_cache_version(managed_dir / "config.yaml") if managed_dir else (0, 0, 0, 0, "") # config-reader: ok — managed overlay
  1794. except OSError:
  1795. managed_sig = (0, 0, 0, 0, "")
  1796. if user_sig is None and managed_sig == (0, 0, 0, 0, ""):
  1797. return None, None
  1798. return user_sig, (*(user_sig or (0, 0, 0, 0, "")), *managed_sig)
  1799. def _last_known_good_fallback(config_path: Path, path_key: str, cache_sig, exc: Exception) -> Optional[dict[str, Any]]:
  1800. """Warn about a parse failure and return the last-known-good config, or None (-> defaults).
  1801. A parse failure must not silently replace the effective config with defaults — that drops
  1802. EVERY user override, including security-critical ``approvals.deny`` rules, when a gateway
  1803. user mid-edits config.yaml into broken YAML. Keep serving the last good config until fixed."""
  1804. # Falling through to DEFAULT_CONFIG here drops EVERY user override — including security-critical
  1805. # ``approvals.deny`` rules, which are supposed to block commands even under yolo. Within a running
  1806. # process we still have the last successfully loaded config — keep serving it until the file is fixed.
  1807. # See #31188.
  1808. lkg = _LAST_EXPANDED_CONFIG_BY_PATH.get(path_key)
  1809. fallback = "last-known-good"
  1810. if lkg is None:
  1811. # Fresh process (CLI restart, `hermes config get`): nothing loaded yet in this process, so
  1812. # fall back to the newest byte-exact copy the last successful parse left in backups/config/.
  1813. # It holds the raw file (``${VAR}`` templates intact), so it goes through the same
  1814. # canonicalize -> expand -> managed-overlay pipeline as a normal load.
  1815. from hermes_cli.config_backups import load_newest_good_backup
  1816. from hermes_cli.moa_config import apply_user_moa_presets
  1817. raw_good = load_newest_good_backup(config_path)
  1818. if raw_good is not None:
  1819. merged_good = _deep_merge(copy.deepcopy(DEFAULT_CONFIG), raw_good)
  1820. apply_user_moa_presets(merged_good, raw_good)
  1821. normalized = _canonicalize_config(merged_good)
  1822. expanded_good: dict[str, Any] = _expand_env_vars(normalized) # type: ignore[assignment]
  1823. lkg, _ = _merge_managed_overlay(expanded_good)
  1824. fallback = "last-known-good-backup"
  1825. _warn_config_parse_failure(
  1826. config_path, exc, fallback=fallback if lkg is not None else "defaults")
  1827. if lkg is None:
  1828. return None
  1829. # save_config() stores the pre-expansion dict (templates preserved); the load path stores the
  1830. # expanded one. Expand defensively — idempotent when already expanded.
  1831. lkg_copy = FailedConfigRead(_expand_env_vars(copy.deepcopy(lkg)), error=exc)
  1832. if cache_sig is not None:
  1833. # Cache under the failed file's signature (empty env snapshot: always valid) so repeated
  1834. # loads don't re-parse the fallback; fixing the file changes the signature and reloads
  1835. # normally, and a read error is re-probed on every hit (_load_config_cache_hit).
  1836. _LOAD_CONFIG_CACHE[path_key] = (*cache_sig, lkg_copy, {})
  1837. return lkg_copy
  1838. def _merge_managed_overlay(expanded: dict[str, Any]) -> tuple[dict[str, Any], Any]:
  1839. """Apply the managed-scope overlay; returns ``(merged, managed_config_or_falsy)``.
  1840. Managed wins at the leaf and is applied AFTER user expansion so a user ``${VAR}`` cannot shadow
  1841. a managed literal: managed values expand only against the process environment. This
  1842. deliberately inverts the usual env-over-config precedence for the keys the managed layer pins
  1843. (docs/design/managed-scope.md §4.1)."""
  1844. managed_config = managed_scope.load_managed_config()
  1845. if not managed_config:
  1846. return expanded, managed_config
  1847. # Same canonicalization as the user config BEFORE merging (parity with
  1848. # managed_scope.apply_managed_overlay) so the merged result never exposes a nested dict.
  1849. managed_normalized = _normalize_root_model_keys(managed_config)
  1850. if isinstance(managed_normalized.get("model"), str):
  1851. managed_normalized = dict(managed_normalized)
  1852. managed_normalized["model"] = {"default": managed_normalized["model"]}
  1853. return _deep_merge(expanded, _expand_env_vars(managed_normalized)), managed_config
  1854. def _load_config_cache_hit(path_key: str, cache_sig: Any) -> Optional[dict[str, Any]]:
  1855. """Lookup: the cached expanded config for ``path_key`` if its signature equals
  1856. ``cache_sig`` AND every ``${VAR}`` it was expanded against still has the same value, else
  1857. ``None``. Signatures matching is not enough: a load before load_hermes_dotenv() would otherwise
  1858. pin unexpanded literals (e.g. auxiliary.<task>.api_key) for the process lifetime (#58514).
  1859. Shared by the lock-free fast path and the locked re-check of ``_load_config_impl``."""
  1860. cached = _LOAD_CONFIG_CACHE.get(path_key)
  1861. if cached is None or cache_sig is None:
  1862. return None
  1863. n = len(cache_sig) # the backend's version tuple + the managed file's signature
  1864. if cached[:n] != cache_sig:
  1865. return None
  1866. hit = cached[n]
  1867. if isinstance(hit, FailedConfigRead) and isinstance(hit.read_error, OSError):
  1868. # A read error (EMFILE/EIO/sharing violation) can clear without touching the file's
  1869. # signature: serve the fallback only while the file still cannot be read.
  1870. try:
  1871. probe_config_readable(path_key)
  1872. except OSError:
  1873. return hit
  1874. return None
  1875. env_snapshot = cached[n + 1] if len(cached) > n + 1 else {}
  1876. if all(_env_ref_lookup(k) == v for k, v in env_snapshot.items()):
  1877. return hit
  1878. return None
  1879. def _load_config_impl(*, want_deepcopy: bool) -> dict[str, Any]:
  1880. snapshot = _worker_config_snapshot()
  1881. if snapshot is not None:
  1882. return _deep_merge(copy.deepcopy(DEFAULT_CONFIG), snapshot)
  1883. # Lock-free fast path for cache hits — same publication contract as `_read_raw_config_impl`
  1884. # above (whole-tuple replace, `_CONFIG_LOCK` only serializes rebuilds and writers). A hit costs
  1885. # ~0.024ms; behind a lock held by `save_config()` the same read measured 10010ms, and on a
  1886. # gateway that stalls every inbound message's hook path. A lost race falls through to the lock.
  1887. try:
  1888. config_path = get_config_path()
  1889. path_key = str(config_path)
  1890. if path_key in _LOAD_CONFIG_CACHE:
  1891. _, fast_sig = _load_config_cache_sig(config_path)
  1892. hit = _load_config_cache_hit(path_key, fast_sig)
  1893. if hit is not None:
  1894. return copy.deepcopy(hit) if want_deepcopy else hit
  1895. except Exception:
  1896. # Any surprise here falls through to the locked path, which is the
  1897. # original fully-defensive implementation.
  1898. pass
  1899. with _CONFIG_LOCK:
  1900. ensure_hermes_home()
  1901. config_path = get_config_path()
  1902. path_key = str(config_path)
  1903. user_sig, cache_sig = _load_config_cache_sig(config_path)
  1904. hit = _load_config_cache_hit(path_key, cache_sig)
  1905. if hit is not None:
  1906. return copy.deepcopy(hit) if want_deepcopy else hit
  1907. config = copy.deepcopy(DEFAULT_CONFIG)
  1908. if user_sig is not None:
  1909. try:
  1910. user_config = read_config_doc(config_path) or {}
  1911. _CONFIG_PARSE_FAILURES.pop(path_key, None) # the file reads now (a transient error left the record)
  1912. if "max_turns" in user_config:
  1913. agent_user_config = dict(user_config.get("agent") or {})
  1914. if agent_user_config.get("max_turns") is None:
  1915. agent_user_config["max_turns"] = user_config["max_turns"]
  1916. user_config["agent"] = agent_user_config
  1917. user_config.pop("max_turns", None)
  1918. config = _deep_merge(config, user_config)
  1919. from hermes_cli.moa_config import apply_user_moa_presets
  1920. apply_user_moa_presets(config, user_config)
  1921. # A copy of the file that just parsed is what a FRESH process falls back to when the
  1922. # next edit breaks the YAML (see _last_known_good_fallback). backup_config() skips
  1923. # byte-identical repeats and keeps a bounded count, so steady-state loads cost one stat.
  1924. from hermes_cli.config_backups import backup_config
  1925. backup_config(config_path, "good")
  1926. except Exception as e:
  1927. lkg_copy = _last_known_good_fallback(config_path, path_key, cache_sig, e)
  1928. if lkg_copy is not None:
  1929. return copy.deepcopy(lkg_copy) if want_deepcopy else lkg_copy
  1930. # Defaults stand in for the unreadable file: never the next last-known-good,
  1931. # never saveable, and cached like the LKG path.
  1932. fallback = FailedConfigRead(
  1933. _merge_managed_overlay(_expand_env_vars(_canonicalize_config(config)))[0], error=e)
  1934. if cache_sig is not None:
  1935. _LOAD_CONFIG_CACHE[path_key] = (*cache_sig, fallback, {})
  1936. return copy.deepcopy(fallback) if want_deepcopy else fallback
  1937. normalized = _canonicalize_config(config)
  1938. expanded, managed_config = _merge_managed_overlay(_expand_env_vars(normalized))
  1939. _LAST_EXPANDED_CONFIG_BY_PATH[path_key] = copy.deepcopy(expanded)
  1940. _note_policy("note_config_policy", (expanded.get("security") or {}).get("redact_secrets"))
  1941. if cache_sig is not None:
  1942. # The cache stores its own deepcopy so load_config() callers can mutate freely while
  1943. # load_config_readonly() callers all see the same stable object. The env snapshot
  1944. # records the values this expansion was made against so later loads detect drift.
  1945. cached_copy = copy.deepcopy(expanded)
  1946. env_snapshot = _env_ref_snapshot(normalized)
  1947. if managed_config:
  1948. _env_ref_snapshot(managed_config, env_snapshot)
  1949. _LOAD_CONFIG_CACHE[path_key] = (*cache_sig, cached_copy, env_snapshot)
  1950. # Readonly path returns the same object later calls will see (identity invariant).
  1951. if not want_deepcopy:
  1952. return cached_copy
  1953. else:
  1954. _LOAD_CONFIG_CACHE.pop(path_key, None)
  1955. # First-load result is a fresh dict (not aliased to the cache); safe to return directly.
  1956. return expanded
  1957. _SECURITY_COMMENT = """
  1958. # ── Security ──────────────────────────────────────────────────────────
  1959. # Secret redaction is ON by default — strings that look like API keys,
  1960. # tokens, and passwords are masked in tool output, logs, and chat
  1961. # responses before the model or user ever sees them. Set redact_secrets
  1962. # to false to disable (e.g. when developing the redactor itself).
  1963. #
  1964. # security:
  1965. # redact_secrets: true
  1966. """
  1967. _FALLBACK_COMMENT = """
  1968. # ── Fallback Model ────────────────────────────────────────────────────
  1969. # Automatic provider failover when primary is unavailable.
  1970. # Uncomment and configure to enable. Triggers on rate limits (429),
  1971. # overload (529), service errors (503), or connection failures.
  1972. #
  1973. # Supported providers:
  1974. # openrouter (OPENROUTER_API_KEY) — routes to any model
  1975. # openai-codex (OAuth — hermes auth) — OpenAI Codex
  1976. # nous (OAuth — hermes auth) — Nous Portal
  1977. # zai (ZAI_API_KEY) — Z.AI / GLM
  1978. # kimi-coding (KIMI_API_KEY) — Kimi / Moonshot
  1979. # kimi-coding-cn (KIMI_CN_API_KEY) — Kimi / Moonshot (China)
  1980. # minimax (MINIMAX_API_KEY) — MiniMax
  1981. # minimax-cn (MINIMAX_CN_API_KEY) — MiniMax (China)
  1982. # bedrock (AWS IAM / boto3) — AWS Bedrock (Converse API)
  1983. #
  1984. # For custom OpenAI-compatible endpoints, add base_url and key_env.
  1985. #
  1986. # fallback_model:
  1987. # provider: openrouter
  1988. # model: anthropic/claude-sonnet-4
  1989. """
  1990. def _strip_managed_keys_for_save(config: dict[str, Any]) -> dict[str, Any]:
  1991. """Drop every leaf the managed layer pins (bulk safety net; single-key ``config set``
  1992. hard-rejects) and tell the user what was not saved."""
  1993. managed_keys = managed_scope.managed_config_keys()
  1994. if not managed_keys:
  1995. return config
  1996. config, _stripped = _strip_dotted_keys(copy.deepcopy(config), managed_keys)
  1997. if _stripped:
  1998. print(
  1999. f"Note: {len(_stripped)} managed setting(s) were not saved "
  2000. f"(managed by your administrator): {', '.join(sorted(_stripped))}", file=sys.stderr)
  2001. return config
  2002. def _commented_sections_for_save(normalized: dict[str, Any]) -> Optional[str]:
  2003. """Commented-out example blocks for features that are off/unconfigured."""
  2004. parts = []
  2005. if (normalized.get("security") or {}).get("redact_secrets") is None:
  2006. parts.append(_SECURITY_COMMENT)
  2007. fb = normalized.get("fallback_model", {})
  2008. fb_entries = fb if isinstance(fb, list) else [fb]
  2009. if not any(isinstance(e, dict) and e.get("provider") and e.get("model") for e in fb_entries):
  2010. parts.append(_FALLBACK_COMMENT)
  2011. return "".join(parts) or None
  2012. def save_config(
  2013. config: dict[str, Any], *, strip_defaults: bool = True,
  2014. preserve_keys: Optional[set[tuple[str, ...]]] = None, merge_existing: bool = False,
  2015. mcp_literal_paths: Optional[set[tuple[str, ...]]] = None):
  2016. """Save configuration to ~/.hermes/config.yaml.
  2017. Schema defaults are not written unless the user explicitly set them (the path exists in the
  2018. raw config before normalisation), so config.yaml is never contaminated with defaults that
  2019. would hide future default changes. ``merge_existing`` deep-merges the on-disk raw config
  2020. under *config* so partial callers cannot drop sections they omitted.
  2021. ``mcp_literal_paths`` explicitly replaces env/header leaves in ONE MCP server rather than
  2022. restoring their previous env templates. All other paths retain the normal protection."""
  2023. with _CONFIG_LOCK:
  2024. literal_paths = set(mcp_literal_paths or ())
  2025. server_names = set()
  2026. for path in literal_paths:
  2027. if (not isinstance(path, tuple) or len(path) != 4
  2028. or not all(isinstance(part, str) and part for part in path)
  2029. or path[0] != "mcp_servers" or path[2] not in ("headers", "env")):
  2030. raise ValueError("Literal paths must target env/headers in one MCP server")
  2031. server_names.add(path[1])
  2032. value = config
  2033. for part in path:
  2034. value = value.get(part) if isinstance(value, dict) else None
  2035. if not isinstance(value, str):
  2036. raise ValueError("MCP literal paths must identify existing string values")
  2037. if len(server_names) > 1:
  2038. raise ValueError("Literal paths must target only one MCP server")
  2039. if is_managed():
  2040. managed_error("save configuration")
  2041. return
  2042. config_path = get_config_path()
  2043. _refuse_failed_read(config_path, config)
  2044. config = _strip_managed_keys_for_save(config)
  2045. ensure_hermes_home()
  2046. # Explicit user paths come from the RAW dict BEFORE normalisation (which may inject
  2047. # agent.max_turns) so _strip_default_values keeps exactly what the user set. The
  2048. # fail-closed read is the single authority here: ``read_raw_config()`` is cached and
  2049. # swallows transient stat/open errors into ``{}``, and a ``{}`` at this point makes the
  2050. # strip pass drop every user section whose value matches a default (#113301).
  2051. from hermes_cli.config_backend import keeping_read_base
  2052. _raw_for_paths = keeping_read_base(lambda: require_readable_config_before_write(config_path))
  2053. from hermes_cli.config_worker_save import rebase_for_save # frozen-worker writes + merge_existing
  2054. config = rebase_for_save(config, _raw_for_paths, merge_existing)
  2055. normalized = current_normalized = _canonicalize_config(config)
  2056. if _raw_for_paths:
  2057. normalized = _preserve_env_ref_templates(
  2058. normalized, _canonicalize_config(_raw_for_paths),
  2059. _LAST_EXPANDED_CONFIG_BY_PATH.get(str(config_path)))
  2060. for _, name, field, key in literal_paths:
  2061. normalized["mcp_servers"][name][field][key] = current_normalized["mcp_servers"][name][field][key]
  2062. if strip_defaults:
  2063. # ``_strip_default_values`` always preserves ``_config_version`` itself.
  2064. effective_preserve_keys = _explicit_config_paths(_raw_for_paths) | set(preserve_keys or ())
  2065. normalized = _strip_default_values(normalized, DEFAULT_CONFIG, preserve_keys=effective_preserve_keys)
  2066. note_first_stamp(config_path.parent, _raw_for_paths, normalized)
  2067. atomic_config_replace(config_path, normalized, extra_content_on_create=_commented_sections_for_save(normalized))
  2068. _secure_file(config_path)
  2069. _RAW_CONFIG_CACHE.pop(str(config_path), None)
  2070. _LAST_EXPANDED_CONFIG_BY_PATH[str(config_path)] = copy.deepcopy(current_normalized)
  2071. from hermes_cli.observability.shared_metrics_disabled import record_config_saved
  2072. record_config_saved(_raw_for_paths, current_normalized)
  2073. def load_env() -> dict[str, str]:
  2074. """Load ~/.hermes/.env as a dict. Memoised inside ``load_env_file`` (``get_env_value()`` runs
  2075. hundreds of times per interactive menu render). Each assignment's value is opaque data for
  2076. boundary discovery."""
  2077. # A frozen-policy worker never opens the profile's files; its secrets arrive
  2078. # through the owner-installed scope, so the .env layer is empty here.
  2079. if _worker_config_snapshot() is not None:
  2080. return {}
  2081. from agent.secret_scope import load_env_file # the one .env tokenizer; also installs profile scopes
  2082. env = load_env_file(get_env_path())
  2083. _note_policy("note_env_policy", env.get("HERMES_REDACT_SECRETS"))
  2084. return env
  2085. def _note_policy(setter: str, raw: Any) -> None:
  2086. """Record the loaded profile's redaction policy for the log formatter, which never reads config."""
  2087. note = getattr(sys.modules.get("agent.redact"), setter, None)
  2088. if note is not None:
  2089. from hermes_constants import hermes_home_key
  2090. note(hermes_home_key(), raw)
  2091. def _parse_env_value(raw_value: str) -> str:
  2092. """Frozen compat surface name (tests/compat/old_updater_surface.json).
  2093. Pre-PM updaters lazy-import ``hermes_cli.config._parse_env_value`` after the
  2094. checkout swap. The tokenizer moved to ``agent.secret_scope._parse_env_value``
  2095. (c849bc383a), so this forwards there — behavior-preserving by construction.
  2096. """
  2097. from agent.secret_scope import _parse_env_value as _parse
  2098. return _parse(raw_value)
  2099. def invalidate_env_cache() -> None:
  2100. """Drop the ``.env`` memo so the next ``load_env()`` sees a write even on coarse-mtime filesystems
  2101. (save_env_value / remove_env_value / sanitize_env_file call this)."""
  2102. from agent.secret_scope import invalidate_env_file_cache
  2103. invalidate_env_file_cache()
  2104. def _sanitize_env_lines(lines: list) -> list:
  2105. """Normalize .env line endings/whitespace without changing assignment semantics.
  2106. Content after the first ``=`` is opaque value data: a known variable name embedded in a value
  2107. must never be reinterpreted as another assignment, so concatenated lines stay on one line."""
  2108. sanitized: list[str] = []
  2109. for line in lines:
  2110. raw = line.rstrip("\r\n")
  2111. stripped = raw.strip()
  2112. # Blank lines and comments are preserved verbatim.
  2113. sanitized.append((raw if not stripped or stripped.startswith("#") else stripped) + "\n")
  2114. return sanitized
  2115. def sanitize_env_file() -> int:
  2116. """Rewrite ~/.hermes/.env with normalized line formatting; returns the number of changed lines."""
  2117. env_path = get_env_path()
  2118. if not env_path.exists():
  2119. return 0
  2120. with _env_write_lock(env_path):
  2121. with open(env_path, encoding="utf-8-sig", errors="replace") as f:
  2122. original_lines = f.readlines()
  2123. sanitized = _sanitize_env_lines(original_lines)
  2124. if sanitized == original_lines:
  2125. return 0
  2126. fixes = abs(len(sanitized) - len(original_lines)) or sum(
  2127. 1 for a, b in zip(original_lines, sanitized) if a != b)
  2128. _write_env_lines(env_path, sanitized, preserve_mode=False)
  2129. invalidate_env_cache()
  2130. return fixes
  2131. def _read_env_lines(env_path: Path) -> list:
  2132. """Read ``.env`` lines, normalized. Explicit UTF-8 (Windows defaults to cp1252) with BOM
  2133. tolerance (Notepad adds one)."""
  2134. with open(env_path, encoding="utf-8-sig", errors="replace") as f:
  2135. return _sanitize_env_lines(f.readlines())
  2136. _ENV_WRITE_LOCK_HOLDERS: dict[str, Any] = {}
  2137. _ENV_WRITE_LOCK_HOLDERS_GUARD = threading.Lock()
  2138. def _env_write_lock_holder(env_path: Path) -> Any:
  2139. """Reentrancy tracker for one canonical ``.env`` path (mirrors auth's
  2140. ``_auth_lock_holder_for``): multiplexed profiles each get their own tracker."""
  2141. key = str(env_path)
  2142. with _ENV_WRITE_LOCK_HOLDERS_GUARD:
  2143. return _ENV_WRITE_LOCK_HOLDERS.setdefault(key, threading.local())
  2144. @contextmanager
  2145. def _env_write_lock(env_path: Path):
  2146. """Serialize a whole ``.env`` read-modify-write cycle (#77187).
  2147. ``save_env_value`` / ``remove_env_value`` / ``sanitize_env_file`` read the file,
  2148. rewrite it in memory, then atomically replace it. Without a lock, two
  2149. concurrent writers (setup wizard + dashboard save, gateway + CLI) both
  2150. snapshot the pre-write file and the loser's replace silently drops the
  2151. winner's key. ``_CONFIG_LOCK`` cannot help: it guards in-memory config only.
  2152. Reuses ``hermes_cli.auth._file_lock`` (fcntl flock / msvcrt byte lock,
  2153. cross-process, reentrant per thread) rather than growing a second kernel-lock
  2154. implementation. The import is call-time: ``hermes_cli.auth`` imports this
  2155. module at import time, so a module-level import would be circular. Nothing
  2156. under this lock takes other locks, and the only nesting direction that exists
  2157. (credential_lifecycle takes ``_auth_store_lock`` around its own auth-store
  2158. writes, NOT around ``save_env_value``) keeps a single ordering — no cycle.
  2159. On a filesystem without flock the helper degrades to a depth-only guard
  2160. (same behavior as auth's locks), never to a crash.
  2161. """
  2162. from hermes_cli.auth import _file_lock
  2163. with _file_lock(
  2164. env_path.with_name(env_path.name + ".lock"),
  2165. _env_write_lock_holder(env_path),
  2166. 15.0,
  2167. f"Timed out waiting for the environment file lock ({env_path})",
  2168. ):
  2169. yield
  2170. def _write_env_lines(env_path: Path, lines: list, *, preserve_mode: bool) -> None:
  2171. """Atomically replace ``.env`` (tmp file + fsync + rename).
  2172. ``preserve_mode`` keeps the original file mode (e.g. 0640 for Docker volume mounts) instead of
  2173. letting ``_secure_file`` tighten to 0600; a new file is always secured."""
  2174. original_mode = None
  2175. try:
  2176. original_mode = stat.S_IMODE(env_path.stat().st_mode) if preserve_mode else None
  2177. except OSError:
  2178. pass
  2179. fd, tmp_path = mkstemp_beside(env_path, suffix=".tmp", prefix=".env_")
  2180. try:
  2181. with os.fdopen(fd, "w", encoding="utf-8") as f:
  2182. f.writelines(lines)
  2183. f.flush()
  2184. os.fsync(f.fileno())
  2185. atomic_replace(tmp_path, env_path)
  2186. except BaseException:
  2187. try:
  2188. os.unlink(tmp_path)
  2189. except OSError:
  2190. pass
  2191. raise
  2192. if original_mode is not None:
  2193. try:
  2194. os.chmod(env_path, original_mode)
  2195. except OSError:
  2196. pass
  2197. else:
  2198. _secure_file(env_path)
  2199. def _check_non_ascii_credential(key: str, value: str) -> str:
  2200. """Strip non-ASCII characters from a credential (HTTP header values must be ASCII) and warn.
  2201. Lookalike glyphs typically come from copy-pasting out of a PDF or rich-text editor."""
  2202. if value.isascii():
  2203. return value
  2204. bad_chars = [f" position {i}: {ch!r} (U+{ord(ch):04X})" for i, ch in enumerate(value) if ord(ch) > 127]
  2205. sanitized = value.encode("ascii", errors="ignore").decode("ascii")
  2206. print(
  2207. f"\n Warning: {key} contains non-ASCII characters that will break API requests.\n"
  2208. f" This usually happens when copy-pasting from a PDF, rich-text editor,\n"
  2209. f" or web page that substitutes lookalike Unicode glyphs for ASCII letters.\n\n"
  2210. + "\n".join(f" {line}" for line in bad_chars[:5])
  2211. + ("\n ... and more" if len(bad_chars) > 5 else "")
  2212. + "\n\n The non-ASCII characters have been stripped automatically.\n"
  2213. " If authentication fails, re-copy the key from the provider's dashboard.\n",
  2214. file=sys.stderr)
  2215. return sanitized
  2216. def _quote_env_value(value: str) -> str:
  2217. """Quote .env values containing characters with special dotenv meaning. Any whitespace
  2218. (including internal runs) is quoted so ``set -a; . file`` word-splitting keeps paths intact."""
  2219. if value == "":
  2220. return value
  2221. if not ("#" in value or '"' in value or "'" in value or any(c.isspace() for c in value)):
  2222. return value
  2223. escaped = value.replace("\\", "\\\\").replace('"', '\\"')
  2224. return f'"{escaped}"'
  2225. def _env_line_defines_key(line: str, key: str, *, is_windows: Optional[bool] = None) -> bool:
  2226. """True when a .env line assigns ``key`` — plain, ``export``-prefixed, or ``KEY = value``.
  2227. Must match exactly the shapes ``load_env()`` parses; otherwise a hand-added line is invisible
  2228. to save (duplicate appended) and remove (line survives -> the value resurrects on next load).
  2229. ``load_env()`` accepts the bash-compatible ``export KEY=value`` form (#6659), so the writers must
  2230. recognise the same shape.
  2231. """
  2232. stripped = line.strip()
  2233. if stripped.startswith("export "):
  2234. stripped = stripped[7:].lstrip()
  2235. assigned_key, separator, _value = stripped.partition("=")
  2236. if not separator:
  2237. return False
  2238. # load_env() strips whitespace around the parsed name, so `KEY = value` IS a live assignment. The
  2239. # writers must match the same shape, or a hand-edited spaced line is invisible to save (duplicate
  2240. # appended) and remove (line survives -> value resurrects on next load). #67488.
  2241. return _env_var_policy_name(
  2242. assigned_key.strip(), is_windows=is_windows
  2243. ) == _env_var_policy_name(key, is_windows=is_windows)
  2244. def _publish_env_value(key: str, value: Optional[str]) -> None:
  2245. """Publish a just-persisted ``.env`` change to the live process.
  2246. Under a multiplexed gateway a routed profile's write must not land in the SHARED
  2247. ``os.environ`` where every profile sees it; the installed scope mapping is updated instead so
  2248. same-turn reads see the change. All other callers keep the legacy ``os.environ`` publish.
  2249. ``save_env_value`` / ``remove_env_value`` already target the right file (``get_env_path()`` honors the
  2250. profile-home override), but the in-process mirror historically went straight to ``os.environ``. See
  2251. #77490, #88441.
  2252. """
  2253. try:
  2254. from agent.secret_scope import current_secret_scope, serves_routed_profile
  2255. scope, routed = current_secret_scope(), serves_routed_profile()
  2256. except Exception:
  2257. scope, routed = None, False
  2258. # The launch profile's own body runs under a scope snapshot even single-profile (the TUI /
  2259. # dashboard launch scope), so a same-request read after the write must see it there too; a
  2260. # routed profile's value never reaches the shared process env.
  2261. targets = [scope] if isinstance(scope, dict) else []
  2262. if not routed and (scope is None or isinstance(scope, dict)):
  2263. targets.append(os.environ)
  2264. for target in targets:
  2265. if value is None:
  2266. target.pop(key, None)
  2267. else:
  2268. target[key] = value
  2269. def env_write_refusal(key: str, action: str) -> Optional[str]:
  2270. """The ``.env`` write-lock refusal for ``key``, or None when the write is allowed.
  2271. Two distinct locks: ``is_managed()`` (package-manager install) and the managed *scope*
  2272. (administrator-pinned env key — the managed .env wins at load anyway)."""
  2273. if is_managed():
  2274. return format_managed_message(f"{action} {key}")
  2275. if managed_scope.is_env_managed(key):
  2276. return (
  2277. f"Cannot {action} {key}: it is managed by your administrator ({_managed_source('.env')}) "
  2278. "and cannot be changed.")
  2279. return None
  2280. def _env_write_blocked(key: str, action: str) -> bool:
  2281. """Shared write-lock check for ``.env`` writers; prints the refusal and returns True when blocked."""
  2282. refusal = env_write_refusal(key, action)
  2283. if refusal:
  2284. print(refusal, file=sys.stderr)
  2285. return refusal is not None
  2286. def require_env_writable(key: str, action: str) -> None:
  2287. """Raise ``ValueError`` with the refusal when the ``.env`` write lock forbids ``key``.
  2288. ``save_env_value`` / ``remove_env_value`` refuse by returning, which their caller cannot tell
  2289. from success, so a writer that also touches config.yaml or the credential pool must ask first."""
  2290. refusal = env_write_refusal(key, action)
  2291. if refusal:
  2292. raise ValueError(refusal)
  2293. def _managed_source(filename: str):
  2294. """``<managed dir>/<filename>`` for refusal messages, or a generic label without a managed dir."""
  2295. managed_dir = managed_scope.get_managed_dir()
  2296. return (managed_dir / filename) if managed_dir else "the managed scope"
  2297. def save_env_value(key: str, value: str):
  2298. """Save or update a value in ~/.hermes/.env (also matching ``export KEY=`` lines, so a save
  2299. never appends a second line that a later delete would resurrect)."""
  2300. if _env_write_blocked(key, "set"):
  2301. return
  2302. validate_env_var_name_for_write(key)
  2303. value = value.replace("\n", "").replace("\r", "")
  2304. value = _check_non_ascii_credential(key, value)
  2305. ensure_hermes_home()
  2306. env_path = get_env_path()
  2307. with _env_write_lock(env_path):
  2308. lines = _read_env_lines(env_path) if env_path.exists() else []
  2309. serialized_value = _quote_env_value(value)
  2310. idx = next((i for i, line in enumerate(lines) if _env_line_defines_key(line, key)), None)
  2311. if idx is not None:
  2312. lines[idx] = f"{key}={serialized_value}\n"
  2313. else:
  2314. if lines and not lines[-1].endswith("\n"):
  2315. lines[-1] += "\n"
  2316. lines.append(f"{key}={serialized_value}\n")
  2317. _write_env_lines(env_path, lines, preserve_mode=env_path.exists())
  2318. _publish_env_value(key, value)
  2319. invalidate_env_cache()
  2320. def custom_endpoint_key_env(identity: str) -> str:
  2321. """Env var name holding a custom endpoint's API key.
  2322. ``identity`` is the endpoint's own id (Desktop endpoint id, or ``host:port`` for CLI setup),
  2323. so two endpoints on one host get separate slots. The fixed ``HERMES_CUSTOM_`` prefix keeps the
  2324. name POSIX-valid when the slug starts with a digit (``save_env_value`` rejects those)."""
  2325. slug = re.sub(r"[^A-Z0-9]+", "_", str(identity or "").upper()).strip("_")
  2326. return f"HERMES_CUSTOM_{slug}_API_KEY" if slug else "HERMES_CUSTOM_API_KEY"
  2327. def remove_env_value(key: str) -> bool:
  2328. """Remove a key from ~/.hermes/.env and os.environ; True if it was found and removed."""
  2329. if _env_write_blocked(key, "remove"):
  2330. return False
  2331. if not _ENV_VAR_NAME_RE.match(key):
  2332. raise ValueError(f"Invalid environment variable name: {key!r}")
  2333. env_path = get_env_path()
  2334. if not env_path.exists():
  2335. _publish_env_value(key, None)
  2336. return False
  2337. with _env_write_lock(env_path):
  2338. lines = _read_env_lines(env_path)
  2339. new_lines = [line for line in lines if not _env_line_defines_key(line, key)]
  2340. found = len(new_lines) < len(lines)
  2341. if found:
  2342. _write_env_lines(env_path, new_lines, preserve_mode=True)
  2343. _publish_env_value(key, None)
  2344. invalidate_env_cache()
  2345. return found
  2346. def _write_anthropic_slots(token: str, api_key: str, save_fn=None, *, token_first: bool = True):
  2347. """Write both Anthropic credential slots (one holds the value, the other is cleared)."""
  2348. writer = save_fn or save_env_value
  2349. order = (("ANTHROPIC_TOKEN", token), ("ANTHROPIC_API_KEY", api_key))
  2350. for name, value in order if token_first else reversed(order):
  2351. writer(name, value)
  2352. def save_anthropic_oauth_token(value: str, save_fn=None):
  2353. """Persist an Anthropic OAuth/setup token and clear the API-key slot."""
  2354. _write_anthropic_slots(value, "", save_fn)
  2355. def use_anthropic_claude_code_credentials(save_fn=None):
  2356. """Use Claude Code's own credential files instead of persisting env tokens."""
  2357. _write_anthropic_slots("", "", save_fn)
  2358. def save_anthropic_api_key(value: str, save_fn=None):
  2359. """Persist an Anthropic API key and clear the OAuth/setup-token slot."""
  2360. _write_anthropic_slots("", value, save_fn, token_first=False)
  2361. def save_env_value_secure(key: str, value: str) -> dict[str, Any]:
  2362. """Save via the unified credential lifecycle (also refreshes any config.yaml mirror of the old
  2363. value and lifts a prior env-source suppression)."""
  2364. from hermes_cli.credential_lifecycle import save_provider_env_credential
  2365. # Route through the unified credential lifecycle so a rotation via the secret-capture path also
  2366. # refreshes any config.yaml mirror of the old value and lifts a prior env-source suppression (#62269 fix
  2367. # family).
  2368. save_provider_env_credential(key, value)
  2369. return {"success": True, "stored_as": key, "validated": False}
  2370. def reload_env() -> int:
  2371. """Re-read ~/.hermes/.env into os.environ; returns count of vars changed. Removes deleted vars only when
  2372. known to Hermes (OPTIONAL_ENV_VARS and _EXTRA_ENV_KEYS), and none while the .env exists but is unreadable."""
  2373. from hermes_cli.env_loader import dotenv_unreadable
  2374. env_vars = load_env()
  2375. count = 0
  2376. for key, value in env_vars.items():
  2377. if os.environ.get(key) != value:
  2378. os.environ[key] = value
  2379. count += 1
  2380. known = set() if dotenv_unreadable(get_env_path()) else set(OPTIONAL_ENV_VARS) | _EXTRA_ENV_KEYS
  2381. for key in known - set(env_vars):
  2382. if os.environ.pop(key, None) is not None:
  2383. count += 1
  2384. return count
  2385. def _scoped_environ_get(key: str) -> Optional[str]:
  2386. """Read ``key`` from ``os.environ`` through ``agent.secret_scope.get_secret`` so an active
  2387. profile scope (multiplexed gateway turn) never leaks another profile's raw value. Falls back to
  2388. a plain environ read when the scope module is unavailable; ``UnscopedSecretError`` and scope
  2389. failures propagate -- a failed scoped read must never borrow the ambient env."""
  2390. try:
  2391. from agent.secret_scope import get_secret as _get_secret
  2392. except Exception:
  2393. return os.environ.get(key)
  2394. return _get_secret(key)
  2395. def get_env_value(key: str) -> Optional[str]:
  2396. """Get a value from ``os.environ`` (scope-aware) or ``~/.hermes/.env``.
  2397. The ``os.environ`` read routes through ``agent.secret_scope.get_secret`` so that, under an active
  2398. profile scope (multiplexed gateway turn), this is scope-checked rather than leaking another profile's
  2399. raw ``os.environ`` value. ``get_secret`` encodes the whole policy: global vars pass through; scope is
  2400. authoritative under multiplexing (miss -> None, no environ fallthrough); when multiplexing is off it
  2401. behaves exactly like the legacy ``os.environ`` read. Its siblings ``get_env_value_prefer_dotenv`` and
  2402. ``gateway.config._getenv`` already work this way — this was the last scope-blind reader of the trio
  2403. (#67027).
  2404. """
  2405. val = _scoped_environ_get(key)
  2406. return load_env().get(key) if val is None else val
  2407. def get_env_value_prefer_dotenv(key: str) -> Optional[str]:
  2408. """Resolve a Hermes-managed credential preferring ``~/.hermes/.env`` over ``os.environ``, so a
  2409. deliberate .env edit beats a stale value inherited from the parent shell.
  2410. An unresolved ``op://`` reference left in .env yields to the already-resolved value from the
  2411. active secret scope (set by the 1Password secret source) — otherwise a provider auth attempt
  2412. would receive a URL instead of a key. Same carve-out as
  2413. ``agent.credential_pool.get_env_prefer_dotenv``."""
  2414. raw = load_env().get(key) or ""
  2415. if str(raw).lstrip().startswith("op://"):
  2416. scoped = _scoped_environ_get(key)
  2417. if scoped:
  2418. return scoped
  2419. return raw or _scoped_environ_get(key)
  2420. # ---- Config display ----
  2421. def redact_key(key: str) -> str:
  2422. """Redact an API key for display."""
  2423. from agent.redact import mask_secret
  2424. return mask_secret(key, empty=color("(not set)", Colors.DIM))
  2425. # Key names (case-insensitive, exact match) whose VALUE is a credential and must be masked
  2426. # before printing any config dict. Exact-match so ``token_count`` / ``secret_santa`` stay visible.
  2427. # Bare ``auth`` is deliberately absent: ``mcp_servers.<s>.auth: oauth`` is a documented mode enum.
  2428. _SECRET_CONFIG_KEYS = frozenset({
  2429. "api_key", "apikey", "key", "token", "access_token", "refresh_token", "id_token",
  2430. "secret", "client_secret", "password", "passwd", "authorization",
  2431. "private_key", "bearer", "jwt"})
  2432. # Env-map shapes (``mcp_servers.<s>.env.FOO_API_KEY``, ``FAL_KEY``, ``AWS_SECRET_ACCESS_KEY``) and
  2433. # the suffixes ``_is_env_config_key`` routes to .env. Suffix-only so ``token_count`` stays visible.
  2434. _SECRET_CONFIG_KEY_SUFFIXES = ("_api_key", "_token", "_secret", "_password", "_key", "_access_key")
  2435. # .env-routed keys are credentials by default; these suffixes name the non-secret exceptions
  2436. # (``TERMINAL_SSH_HOST``, ``TOOL_GATEWAY_URL``, ``BROWSERBASE_PROJECT_ID``).
  2437. _NON_SECRET_KEY_SUFFIXES = ("_url", "_host", "_user", "_id", "_domain", "_scheme")
  2438. _ENV_PLACEHOLDER_RE = re.compile(r"^\$\{[A-Za-z_][A-Za-z0-9_]*\}$")
  2439. def _is_secret_config_key(key: str) -> bool:
  2440. """Whether the LAST segment of a config key names a credential value. Header names
  2441. (``mcp_servers.<s>.headers.X-API-Key``) are folded to snake_case before matching."""
  2442. leaf = key.rsplit(".", 1)[-1].lower().replace("-", "_")
  2443. if _is_env_config_key(key):
  2444. return not leaf.endswith(_NON_SECRET_KEY_SUFFIXES)
  2445. return leaf in _SECRET_CONFIG_KEYS or leaf.endswith(_SECRET_CONFIG_KEY_SUFFIXES)
  2446. def redact_config_value(value: Any, _depth: int = 0) -> Any:
  2447. """Copy of ``value`` with credential-shaped keys masked. ``print`` bypasses the logging
  2448. redactor and opaque tokens miss the vendor-prefix regexes, so structural masking is required."""
  2449. from agent.redact import mask_secret
  2450. if _depth > 20: # bound recursion for pathological/cyclic configs
  2451. return value
  2452. if isinstance(value, dict):
  2453. return {
  2454. k: mask_secret(v)
  2455. if isinstance(k, str) and _is_secret_config_key(k) and isinstance(v, str) and v
  2456. and not _ENV_PLACEHOLDER_RE.match(v)
  2457. else redact_config_value(v, _depth + 1)
  2458. for k, v in value.items()}
  2459. if isinstance(value, list):
  2460. return [redact_config_value(v, _depth + 1) for v in value]
  2461. return value
  2462. def edit_config():
  2463. """Open config file in user's editor."""
  2464. if is_managed():
  2465. managed_error("edit configuration")
  2466. return
  2467. if not supports_file_tooling():
  2468. # Exits 1 (unlike the managed refusal above, which every managed_error caller shares):
  2469. # a script must not read this refusal as a successful edit.
  2470. _exit_invalid("`hermes config edit` opens the local config file, and this config backend has none. "
  2471. "Use `hermes config set <key> <value>` instead.")
  2472. config_path = get_config_path()
  2473. if not config_path.exists(): # config-reader: ok — file tooling, gated on supports_file_tooling()
  2474. seed_config_file(config_path)
  2475. print(f"Created {config_path}")
  2476. # Windows lands on notepad even without Git Bash/nano; POSIX prefers nano/vim, which headless
  2477. # servers are more likely to have.
  2478. candidates = (['notepad', 'code', 'vim', 'vi', 'nano'] if sys.platform == "win32"
  2479. else ['nano', 'vim', 'vi', 'code', 'notepad'])
  2480. editor = os.getenv('EDITOR') or os.getenv('VISUAL') or next(
  2481. (cmd for cmd in candidates if shutil.which(cmd)), None)
  2482. if not editor:
  2483. print("No editor found. Config file is at:")
  2484. print(f" {config_path}")
  2485. return
  2486. print(f"Opening {config_path} in {editor}...")
  2487. subprocess.run([editor, str(config_path)], check=False)
  2488. def _default_value_for_key(dotted_key: str):
  2489. """Return the leaf value declared for *dotted_key* in ``DEFAULT_CONFIG`` (None for dicts/misses)."""
  2490. node = cfg_get(DEFAULT_CONFIG, *_split_key_path(dotted_key))
  2491. return None if isinstance(node, dict) else node
  2492. # Top-level keys that accept arbitrary user-supplied child keys (schema declares the dict, the
  2493. # user populates it): any path below is accepted without deep checking.
  2494. _OPEN_DICT_TOP_LEVEL_KEYS = frozenset({
  2495. "providers", "credential_pool_strategies", "mcp_servers", "hooks", "quick_commands",
  2496. "personalities", "command_allowlist", "model_catalog", "channel_prompts", "server_actions",
  2497. "secrets", "goals", "loops"})
  2498. # Top-level keys whose sub-keys are partially schema-defined (e.g. a PlatformConfig dataclass) but
  2499. # where users may add fields DEFAULT_CONFIG doesn't enumerate: validate the FIRST segment only.
  2500. _SCHEMA_DEFINED_DICT_KEYS = frozenset({
  2501. # Platform configs — PlatformConfig dataclass + dynamic extras
  2502. "discord", "telegram", "slack", "whatsapp", "signal", "mattermost",
  2503. "matrix", "feishu", "wecom", "weixin", "bluebubbles", "qqbot", "yuanbao",
  2504. "email", "sms", "dingtalk",
  2505. # MCP server template / dynamic auth dicts
  2506. "sessions", "checkpoints",
  2507. # Plugin enable/disable lists + per-plugin entries; absent from DEFAULT_CONFIG.
  2508. "plugins"})
  2509. # Top-level keys that can be ANY user-supplied name.
  2510. _DYNAMIC_TOP_LEVEL_KEYS = frozenset({
  2511. "custom_providers", # list-shaped, but indexed by position
  2512. })
  2513. # Containers whose immediate child IS a user-supplied platform name (``platforms.<name>.<field>``),
  2514. # both top-level and under ``gateway``; anything below the name is accepted (open ``extra``).
  2515. _PLATFORM_CONTAINER_KEYS = frozenset({"platforms"})
  2516. # Top-level keys whose sub-keys are accepted without deep checking.
  2517. _OPEN_SUBKEY_TOP_LEVEL_KEYS = _OPEN_DICT_TOP_LEVEL_KEYS | _DYNAMIC_TOP_LEVEL_KEYS | _SCHEMA_DEFINED_DICT_KEYS
  2518. def _known_top_level_keys() -> set[str]:
  2519. """Return the union of known top-level config keys for validation.
  2520. ``_EXTRA_KNOWN_ROOT_KEYS`` are roots the runtime reads but DEFAULT_CONFIG deliberately
  2521. omits (``platform_toolsets``, ``smart_model_routing``, ...); without them every path under
  2522. such a root was flagged "not a recognized config key" with a difflib near-miss suggestion.
  2523. """
  2524. return set(DEFAULT_CONFIG) | _EXTRA_KNOWN_ROOT_KEYS | _OPEN_SUBKEY_TOP_LEVEL_KEYS
  2525. def _suggest_closest_key(key: str, candidates: set[str], cutoff: float = 0.6) -> Optional[str]:
  2526. """Closest candidate key name for a typo'd ``key``, or None."""
  2527. return next(iter(difflib.get_close_matches(key, sorted(candidates), n=1, cutoff=cutoff)), None)
  2528. def _validate_config_key(key: str) -> tuple[bool, Optional[str]]:
  2529. """CLI-syntax key (``\\.`` escapes a dot) -> ``(is_known, suggestion)``: the schema walk, then (only for a
  2530. refused key) the runtime-read keys DEFAULT_CONFIG leaves unseeded (config_runtime_keys)."""
  2531. known, suggestion = _validate_schema_key(key)
  2532. if known or not key:
  2533. return known, suggestion
  2534. from hermes_cli.config_runtime_keys import is_runtime_read_key
  2535. return (True, None) if is_runtime_read_key(_split_key_path(key)) else (False, suggestion)
  2536. def _validate_schema_key(key: str) -> tuple[bool, Optional[str]]:
  2537. """#34067: ``gateway.discord.gateway_restart_notification`` was silently written; the correct path is
  2538. ``discord.gateway_restart_notification`` (platform configs live at the top level)."""
  2539. if not key:
  2540. return False, None
  2541. segments = _split_key_path(key)
  2542. top = segments[0]
  2543. # A leading ``_`` on the FIRST segment only marks an internal key (``agent._max_turns`` is caught).
  2544. from hermes_cli.left_core_migration import LEFT_CORE_TERMINAL_KEYS
  2545. if top.startswith("_") or top in _PLATFORM_CONTAINER_KEYS or key in LEFT_CORE_TERMINAL_KEYS:
  2546. return True, None
  2547. known = _known_top_level_keys()
  2548. if top not in known:
  2549. suggestion = _suggest_closest_key(top, known)
  2550. if suggestion is None:
  2551. return False, None
  2552. rest = ".".join(segments[1:])
  2553. return False, f"{suggestion}.{rest}" if rest else suggestion
  2554. if top in _OPEN_SUBKEY_TOP_LEVEL_KEYS:
  2555. return True, None
  2556. # Walk DEFAULT_CONFIG: a nested ``platforms`` container, a scalar leaf, or an EMPTY dict hit
  2557. # before the path is consumed all accept. An empty dict is a free-form mapping section
  2558. # (``compression.model_thresholds.<model>``, ``terminal.docker_env.<VAR>``,
  2559. # ``lsp.servers.<lang>``): its keys are user-chosen, so nothing under it can be a typo. An
  2560. # unknown sub-key of a populated section fails with a same-level "did you mean" suggestion.
  2561. node: Any = DEFAULT_CONFIG.get(top)
  2562. consumed = [top]
  2563. for seg in segments[1:]:
  2564. if seg in _PLATFORM_CONTAINER_KEYS or not isinstance(node, dict) or not node:
  2565. return True, None
  2566. if seg not in node:
  2567. # ``gateway.discord.<field>``: the path minus its wrong prefix is itself a known key.
  2568. # Checked BEFORE the fuzzy sibling: a structural match is proof, a fuzzy match is a
  2569. # guess, and ``agent.gateway.strict`` must be refused as ``gateway.strict`` rather
  2570. # than written with a misleading ``agent.gateway_timeout`` did-you-mean.
  2571. # Only DEFAULT_CONFIG / open-subkey roots qualify as the stripped prefix:
  2572. # ``_EXTRA_KNOWN_ROOT_KEYS`` also holds the top-level FORMS of nested gateway
  2573. # settings (``filter_silence_narration``, ``reset_triggers``, ...), and
  2574. # ``gateway.filter_silence_narration`` is a runtime-read path, not a wrong prefix.
  2575. rest = ".".join(segments[len(consumed):])
  2576. if (
  2577. _split_key_path(rest)[0] in set(DEFAULT_CONFIG) | _OPEN_SUBKEY_TOP_LEVEL_KEYS
  2578. and _validate_config_key(rest)[0]
  2579. ):
  2580. return False, rest
  2581. sibling = _suggest_closest_key(seg, set(node.keys()))
  2582. if sibling is not None:
  2583. return False, ".".join(consumed + [sibling])
  2584. return False, None
  2585. consumed.append(seg)
  2586. node = node[seg]
  2587. return True, None
  2588. def _is_wrong_prefix_suggestion(key: str, suggestion: Optional[str]) -> bool:
  2589. """Whether *suggestion* proves that *key* has only an extra prefix.
  2590. ``DEFAULT_CONFIG`` is not a complete registry of runtime-read settings, so a
  2591. sibling spelling suggestion alone cannot prove an unseeded path is a typo.
  2592. A known suffix, such as ``gateway.discord.gateway_restart_notification``
  2593. -> ``discord.gateway_restart_notification``, is the narrow case where the
  2594. pre-write refusal is safe.
  2595. """
  2596. if not suggestion:
  2597. return False
  2598. key_segments = _split_key_path(key)
  2599. suggestion_segments = _split_key_path(suggestion)
  2600. return (
  2601. len(suggestion_segments) < len(key_segments)
  2602. and key_segments[-len(suggestion_segments):] == suggestion_segments
  2603. and _validate_config_key(suggestion)[0]
  2604. )
  2605. def _looks_structured_value(value: str) -> bool:
  2606. """True when *value* plausibly encodes a YAML/JSON list or mapping. Deliberately conservative:
  2607. a bare leading ``-`` is not a trigger (``-5``, ``--flag`` must stay strings)."""
  2608. stripped = value.lstrip()
  2609. if stripped[:1] in ('[', '{'):
  2610. return True
  2611. if '\n' not in value:
  2612. return False
  2613. for line in value.splitlines():
  2614. item = line.strip()
  2615. if item == '-' or item.startswith('- '):
  2616. return True
  2617. # ``key: value`` / ``key:`` mapping-entry shape (no whitespace in the key).
  2618. head, sep, _rest = item.partition(': ')
  2619. if sep and head and ' ' not in head and not head.startswith('#'):
  2620. return True
  2621. if item.endswith(':') and ' ' not in item[:-1] and item[:-1]:
  2622. return True
  2623. return False
  2624. def _coerce_int(value: str):
  2625. """int(value) for a clean integer literal (signs/whitespace/underscores OK), else None."""
  2626. try:
  2627. return int(value)
  2628. except (TypeError, ValueError):
  2629. return None
  2630. def _coerce_float(value: str):
  2631. """``float(value)`` only when the conversion preserves its decimal value; NaN/inf rejected.
  2632. Decimal-looking identifiers more precise than a binary float must stay strings."""
  2633. try:
  2634. f = float(value)
  2635. if f != f or f in (float("inf"), float("-inf")) or Decimal(value) != Decimal(str(f)):
  2636. return None
  2637. except (TypeError, ValueError, InvalidOperation):
  2638. return None
  2639. return f
  2640. _SCALAR_WORDS = {
  2641. 'true': True, 'yes': True, 'on': True,
  2642. 'false': False, 'no': False, 'off': False,
  2643. # YAML null. Many DEFAULT_CONFIG leaves are "null/absent = off"; without this,
  2644. # ``config set X null`` stored the truthy string "null" and the feature could never be cleared.
  2645. 'null': None, 'none': None, '~': None}
  2646. def _coerce_config_set_value(key: str, value: str) -> Any:
  2647. """Auto-coerce a ``hermes config set`` string to bool/None/int/float/list/dict.
  2648. String-typed settings (per ``DEFAULT_CONFIG``) are preserved verbatim so enum members such as
  2649. ``approvals.mode="off"`` never become booleans. List/mapping literals are parsed so
  2650. isinstance-gated readers see real structures; the trigger is conservative.
  2651. Bare ``model`` is the exception: its string default is the model-id shorthand, so a structured
  2652. literal there is parsed for the section guard to gate instead of riding into model.default
  2653. as a bogus id (#131435)."""
  2654. if isinstance(_default_value_for_key(key), str) and not (
  2655. key == "model" and _looks_structured_value(value)):
  2656. return value
  2657. stripped = value.strip()
  2658. lower = stripped.lower()
  2659. if lower in _SCALAR_WORDS:
  2660. return _SCALAR_WORDS[lower]
  2661. for coerce in (_coerce_int, _coerce_float):
  2662. coerced = coerce(stripped)
  2663. if coerced is not None:
  2664. return coerced
  2665. if not _looks_structured_value(value):
  2666. return value
  2667. try:
  2668. parsed = yaml.safe_load(value)
  2669. except yaml.YAMLError as exc:
  2670. # Storing the text as a string here used to be a warning; every isinstance-gated reader
  2671. # then ignored the value while `config get` echoed it back (#114471). Refuse instead.
  2672. detail = str(getattr(exc, "problem", None) or exc).splitlines()[0]
  2673. _exit_invalid(
  2674. f"✗ Value for '{key}' looks like a list/mapping but is not valid YAML/JSON "
  2675. f"({detail}) — nothing was written.\n"
  2676. " Fix the literal, or quote it (e.g. \"'[text'\") to store a plain string.")
  2677. if isinstance(parsed, (list, dict)):
  2678. return parsed
  2679. # A quoted literal ("'[text'") parses to a scalar: that is the deliberate way to store one.
  2680. return value
  2681. # Container roots absent from DEFAULT_CONFIG whose shape is nonetheless fixed by their readers,
  2682. # so the guardrail holds before anything is on disk (#114471: `model.aliases notamap`).
  2683. _KNOWN_CONTAINER_TYPES = {
  2684. "custom_providers": "list",
  2685. "providers": "mapping",
  2686. "model.aliases": "mapping",
  2687. "model_aliases": "mapping",
  2688. # Omitted from DEFAULT_CONFIG on purpose (an empty default would clobber a user allow-list),
  2689. # so without these rows `config set plugins.enabled foo` stored a string every reader ignored.
  2690. "plugins.enabled": "list",
  2691. "plugins.disabled": "list",
  2692. "model_catalog.excluded_providers": "list",
  2693. }
  2694. # List slots whose readers go through ``parse_config_string_list``: a bare name is one entry.
  2695. _SCALAR_AS_ONE_ITEM_LIST_KEYS = frozenset({"agent.disabled_toolsets", "skills.disabled"})
  2696. def _expected_container_type(key: str, user_config: dict[str, Any]) -> Optional[str]:
  2697. """``"list"`` / ``"mapping"`` when the schema (``DEFAULT_CONFIG``, the known-container table,
  2698. or the value already on disk) fixes *key* to a container; ``None`` for scalars and open paths.
  2699. A single-segment key that is a mapping *section* in the schema skips the lookup: replacing a
  2700. whole section is ``_guard_section_overwrite``'s call (``--force``, the bare ``model`` shorthand)."""
  2701. parts = _split_key_path(key)
  2702. schema_node = cfg_get(DEFAULT_CONFIG, *parts)
  2703. if len(parts) == 1 and isinstance(schema_node, dict):
  2704. schema_node = None
  2705. existing = _get_nested(user_config, key)
  2706. for node in (schema_node, _KNOWN_CONTAINER_TYPES.get(key), existing):
  2707. if isinstance(node, dict) or node == "mapping":
  2708. return "mapping"
  2709. if isinstance(node, list) or node == "list":
  2710. return "list"
  2711. return None
  2712. def _refuse_container_type_mismatch(key: str, value: Any, user_config: dict[str, Any], force: bool) -> Any:
  2713. """Hard guardrail: never store a value of the wrong shape where the schema wants a list or a
  2714. mapping — every reader would ignore it while ``config get`` echoed it back. ``--force`` keeps
  2715. its documented meaning (replace a whole mapping section); a non-list in a list slot is never
  2716. readable, so it has no override. Returns the value to store: a bare name for a
  2717. ``parse_config_string_list``-read slot becomes a one-item list."""
  2718. expected = _expected_container_type(key, user_config)
  2719. if expected is None:
  2720. return value
  2721. if expected == "list" and isinstance(value, str) and key in _SCALAR_AS_ONE_ITEM_LIST_KEYS:
  2722. return [value]
  2723. ok = isinstance(value, list) if expected == "list" else isinstance(value, dict)
  2724. if ok or (expected == "mapping" and force):
  2725. return value
  2726. got = type(value).__name__ if not isinstance(value, str) else "string"
  2727. literal = "[item, ...]" if expected == "list" else "{key: value}"
  2728. _exit_invalid(
  2729. f"✗ Cannot set '{key}': it must be a {expected}, got a {got} — nothing was written.\n"
  2730. f" Pass a YAML/JSON literal, e.g.:\n hermes config set {key} '{literal}'\n"
  2731. " or edit config.yaml directly.")
  2732. def _redirect_platform_display_key(key: str) -> tuple[str, Optional[str]]:
  2733. """Canonicalize ``platforms.<name>.<display_setting>`` -> ``display.platforms.<name>.<setting>``.
  2734. The gateway resolves per-platform display settings (streaming, show_reasoning, ...) from
  2735. ``display.platforms``; the top-level ``platforms.<name>`` block holds only connection config.
  2736. Only known display settings (``OVERRIDEABLE_KEYS``) are redirected. Returns ``(key, note)``;
  2737. the gateway import is guarded so the CLI works where the gateway package is unavailable.
  2738. Before #71047 a write such as ``hermes config set platforms.telegram.streaming false`` landed on a key
  2739. the gateway never reads: ``config get`` echoed the new value back while the runtime kept the old
  2740. ``display.platforms`` one — a silent no-op that looks like a duplicated key to the user.
  2741. ``gateway.platforms.<name>.<field>`` is canonicalized to the top-level ``platforms.<name>.<field>``
  2742. first (#115212): ``merge_platform_sections`` reads both blocks but the top-level one wins on
  2743. shared keys, so a nested write beside an existing top-level value printed ``✓ Set`` while the
  2744. gateway kept the old value.
  2745. """
  2746. segs = _split_key_path(key)
  2747. note = None
  2748. if len(segs) >= 3 and segs[0] == "gateway" and segs[1] == "platforms":
  2749. segs = segs[1:]
  2750. key = ".".join(segs)
  2751. note = f" (note: the top-level platforms.{segs[1]} block outranks gateway.platforms — saved as {key})"
  2752. if len(segs) != 3 or segs[0] != "platforms":
  2753. return key, note
  2754. try:
  2755. from gateway.display_config import OVERRIDEABLE_KEYS as _display_keys
  2756. except Exception:
  2757. return key, note
  2758. if segs[2] not in _display_keys:
  2759. return key, note
  2760. canonical = f"display.platforms.{segs[1]}.{segs[2]}"
  2761. return canonical, f" (note: per-platform display setting — saved as {canonical})"
  2762. def _legacy_gateway_platforms_key(requested_key: str) -> Optional[str]:
  2763. """The ``gateway.platforms.<name>.<field>`` spelling the user typed, when that is what they typed.
  2764. ``merge_platform_sections`` still honours a value that lives only there, so ``get`` must fall
  2765. back to it and ``unset``/``set`` must clear it, or the CLI reports "not set" / writes a value
  2766. while the gateway keeps reading the nested one."""
  2767. segs = _split_key_path(requested_key)
  2768. if len(segs) >= 3 and segs[0] == "gateway" and segs[1] == "platforms":
  2769. return ".".join(segs)
  2770. return None
  2771. def _exit_if_key_managed(key: str, action: str) -> None:
  2772. """A key pinned by the managed layer cannot be set/unset (the next load would reinstate it):
  2773. hard-reject and name the source. Distinct from ``is_managed()``; env-shaped keys route to the
  2774. .env writers, which carry their own guard."""
  2775. if managed_scope.is_key_managed(key):
  2776. print(
  2777. f"Cannot {action} '{key}': it is managed by your administrator ({_managed_source('config.yaml')}) "
  2778. f"and cannot be changed. Contact your administrator to modify it.", file=sys.stderr)
  2779. sys.exit(1)
  2780. level = get_config_backend().locked(get_config_path().parent, key) # remote locks, prefix-aware (D7)
  2781. if level:
  2782. print(f"Cannot {action} '{key}': it is locked by the {level} level of Remote Config and cannot be "
  2783. "changed from this agent.", file=sys.stderr)
  2784. sys.exit(1)
  2785. def _touch_skin_file(key: str, value: Any) -> None:
  2786. """``display.skin`` set means "apply NOW": bump the skin file's mtime so the gateway watcher's
  2787. (name, mtime) signature moves even when the name is unchanged. Best-effort."""
  2788. if key == "display.skin" and isinstance(value, str) and value:
  2789. try:
  2790. skin_file = get_hermes_home() / "skins" / f"{value}.yaml"
  2791. if skin_file.exists():
  2792. skin_file.touch()
  2793. except Exception:
  2794. pass
  2795. def _exit_invalid(msg: str) -> None:
  2796. print(msg, file=sys.stderr)
  2797. sys.exit(1)
  2798. def _write_user_config(config_path: Path, user_config: dict[str, Any]) -> None:
  2799. """Write only the user's raw config back (never the merged defaults)."""
  2800. ensure_hermes_home()
  2801. from hermes_cli.observability.shared_metrics_disabled import recording_raw_config_write
  2802. recording_raw_config_write(config_path, user_config, atomic_config_replace)
  2803. def _print_unknown_key_notice(key: str, suggestion: Optional[str]) -> None:
  2804. print(color(
  2805. f"⚠ '{key}' is not a recognized config key — it was saved anyway, "
  2806. "but Hermes may not read it.", Colors.YELLOW))
  2807. if suggestion:
  2808. print(color(f" Did you mean: {suggestion}", Colors.YELLOW))
  2809. # The env bridge covers custom TOP-LEVEL keys only; an unseeded nested path (``stt.provider``)
  2810. # is written but not bridged, so the footer would be a false promise there.
  2811. if len(_split_key_path(key)) == 1:
  2812. print(color(
  2813. " (Custom top-level keys are supported and bridged to the "
  2814. "environment for skills/external tools. Use --force to skip "
  2815. "this notice.)", Colors.DIM))
  2816. else:
  2817. print(color(" (Use --force to skip this notice.)", Colors.DIM))
  2818. def set_config_value(key: str, value: str, force: bool = False):
  2819. """Set a configuration value at a dotted ``key``; ``value`` is auto-coerced to bool/int/float.
  2820. ``force`` writes a known key given under the wrong prefix (``gateway.discord.foo`` where
  2821. ``discord.foo`` is known; otherwise refused — any other unknown path under a known section
  2822. is written with a did-you-mean notice), skips the unknown-top-level-key notice AND
  2823. authorizes replacing a mapping section with a scalar. Without it, scalar writes over mappings are refused and bare ``model`` is redirected
  2824. to ``model.default``."""
  2825. if is_managed():
  2826. managed_error("set configuration values")
  2827. return
  2828. # Empty segments (``"agent."``) would write config["agent"][""] into a live schema section.
  2829. if key != key.strip() or not key.strip():
  2830. _exit_invalid(f"✗ Invalid config key: {key!r} (empty or surrounding whitespace).")
  2831. if "" in _split_key_path(key):
  2832. _exit_invalid(
  2833. f"✗ Invalid config key: {key!r} — contains an empty path segment "
  2834. "(leading, trailing, or doubled '.').")
  2835. _exit_if_key_managed(key, "set")
  2836. if _is_env_config_key(key):
  2837. from hermes_cli.credential_lifecycle import save_provider_env_credential
  2838. # Unified lifecycle: also rotates any config.yaml mirror of the old value so a stale
  2839. # higher-precedence copy can't win (#62269).
  2840. try:
  2841. save_provider_env_credential(key.upper(), value)
  2842. except ValueError as exc:
  2843. _exit_invalid(f"✗ {exc}")
  2844. print(f"✓ Set {key} in {get_env_path()}")
  2845. return
  2846. from hermes_cli.config_env_routing import is_env_setting_key, save_env_setting
  2847. if is_env_setting_key(key):
  2848. # Every UPPER_SNAKE name is an environment setting: same file the platform setup flows and
  2849. # /sethome write, and the only one os.getenv readers see. config.yaml never gets one from
  2850. # here, --force included (#111848). The env writer's denylist (HERMES_YOLO_MODE, PATH, ...)
  2851. # therefore also refuses the config.yaml detour that used to bridge those into os.environ.
  2852. try:
  2853. save_env_setting(key, value)
  2854. except ValueError as exc:
  2855. _exit_invalid(f"✗ {exc}")
  2856. print(f"✓ Set {key.upper()} in {get_env_path()}")
  2857. return
  2858. # Canonicalize per-platform display keys BEFORE validation/coercion so both see the path the
  2859. # runtime reads.
  2860. legacy_key = _legacy_gateway_platforms_key(key)
  2861. key, _redirect_note = _redirect_platform_display_key(key)
  2862. if _redirect_note:
  2863. print(_redirect_note)
  2864. is_known, suggestion = _validate_config_key(key)
  2865. # DEFAULT_CONFIG is an incomplete schema: runtime-read settings may deliberately have no
  2866. # seeded default. Refuse only the positive wrong-prefix case from #112003; other unknown
  2867. # paths keep the post-write warning so valid runtime settings remain configurable.
  2868. if not is_known and not force and _is_wrong_prefix_suggestion(key, suggestion):
  2869. from hermes_cli.config_key_notices import unknown_subkey_refusal
  2870. _exit_invalid(unknown_subkey_refusal(key, suggestion))
  2871. if key == "display.language":
  2872. from hermes_cli.config_language import display_language_error
  2873. language_error = display_language_error(value)
  2874. if language_error:
  2875. _exit_invalid(language_error)
  2876. # Read the RAW user config (not merged) so defaults are never dumped back; fail-closed.
  2877. config_path = get_config_path()
  2878. user_config = require_readable_config_before_write(config_path)
  2879. value = _coerce_config_set_value(key, value)
  2880. # A scalar ``model`` shorthand must become a dict before writing sub-keys, or _set_nested
  2881. # replaces it with an empty dict and the model id is lost.
  2882. _model_val = user_config.get("model")
  2883. if key.strip().lower().startswith("model.") and isinstance(_model_val, str) and _model_val:
  2884. user_config["model"] = {"default": _model_val}
  2885. from hermes_cli.config_section_guard import _guard_section_overwrite
  2886. key = _guard_section_overwrite(key, value, user_config, force)
  2887. value = _refuse_container_type_mismatch(key, value, user_config, force)
  2888. _old_provider = _model_val.get("provider") if isinstance(_model_val, dict) else None
  2889. try:
  2890. _set_nested(user_config, key, value)
  2891. except ValueError as e:
  2892. _exit_invalid(f"✗ {e}")
  2893. if legacy_key and _unset_nested(user_config, legacy_key):
  2894. print(f" (removed the shadowed {legacy_key} duplicate)")
  2895. # A provider switch re-points ``model:`` at a new route; ``base_url``/``api_mode`` are route
  2896. # state of the OLD provider, and the runtime honours them for whatever provider the block now
  2897. # names — the new provider's key would be posted to the old endpoint (#113719, #40862). Sync
  2898. # them the way a persisted ``/model`` switch does: the previous route goes unless it is the
  2899. # new provider's own endpoint.
  2900. _route_notice = ""
  2901. _old_provider = str(_old_provider or "").strip() or "the previous provider"
  2902. if key == "model.provider" and _old_provider.lower() != str(value).strip().lower():
  2903. from hermes_cli.route_identity import drop_stale_model_route
  2904. _popped, _unverified = drop_stale_model_route(user_config.get("model"), value, user_config)
  2905. if _popped:
  2906. _route_notice = (
  2907. " Cleared " + ", ".join(f"model.{k} ({v})" for k, v in _popped.items())
  2908. + f" — that route belonged to {_old_provider}, not {value}. {value}'s endpoint resolves "
  2909. "automatically; set model.base_url again if you meant a custom endpoint.")
  2910. elif _unverified:
  2911. _route_notice = color(
  2912. f"⚠ model.base_url ({user_config['model'].get('base_url')}) was set under {_old_provider} and "
  2913. f"still applies to {value} — requests go there. If it is not {value}'s endpoint: "
  2914. "`hermes config unset model.base_url` (and model.api_mode).", Colors.YELLOW)
  2915. # api_base -> base_url alias at set-time too (mirrors _normalize_root_model_keys).
  2916. if key.strip().lower() in ("model.api_base", "api_base"):
  2917. # Normalize the api_base → base_url alias at set-time too (issue #8919), so a fresh `hermes config
  2918. # set model.api_base ...` lands on the canonical key the runtime resolver actually reads, instead of
  2919. # being silently ignored.
  2920. user_config = _normalize_root_model_keys(user_config)
  2921. key = "model.base_url"
  2922. print(" (note: 'api_base' is an alias — saved as model.base_url)")
  2923. from hermes_cli.config_backend import pinning_keys
  2924. with pinning_keys(key): # an explicit set is stored even when it equals the inherited value
  2925. _write_user_config(config_path, user_config)
  2926. # Keep .env in sync: terminal_tool reads TERMINAL_ENV etc. directly from env vars.
  2927. env_var = terminal_config_env_var_for_key(key)
  2928. if env_var and key != "terminal.cwd":
  2929. save_env_value(env_var, _terminal_env_value(value))
  2930. _touch_skin_file(key, value)
  2931. if key == "display.language":
  2932. from agent.i18n import reset_language_cache
  2933. reset_language_cache()
  2934. # Mask the echoed value when the (possibly nested) key is credential-shaped, e.g.
  2935. # ``model.api_key`` (lowercase, so it misses the .env routing above).
  2936. _display_value = value
  2937. if _is_secret_config_key(key) and isinstance(value, str) and value:
  2938. from agent.redact import mask_secret
  2939. _display_value = mask_secret(value)
  2940. print(f"✓ Set {key} = {_display_value} in {config_destination(config_path)}")
  2941. if _route_notice:
  2942. print(_route_notice)
  2943. # Post-write unknown-key notice (#34067): value IS saved, but tell the user the runtime may never read
  2944. # it and suggest the likely-intended path.
  2945. if not is_known and not force:
  2946. _print_unknown_key_notice(key, suggestion)
  2947. def get_config_value(key: str, *, as_json: bool = False, raw: bool = False):
  2948. """Print a resolved configuration value. Credentials are masked unless ``--raw`` or
  2949. ``security.redact_secrets: false``: ``print`` bypasses the log redactor, and the agent runs
  2950. this command from sessions whose transcripts persist (#84106, #110758)."""
  2951. from hermes_cli.config_env_routing import is_env_setting_key, read_env_setting
  2952. if _is_env_config_key(key):
  2953. env_value = get_env_value(key.upper())
  2954. value = _MISSING if env_value is None else env_value
  2955. elif is_env_setting_key(key):
  2956. env_value = read_env_setting(key)
  2957. value = _MISSING if env_value is None else env_value
  2958. else:
  2959. # Mirror set_config_value: read the canonical display.platforms path.
  2960. # See #71047.
  2961. legacy_key = _legacy_gateway_platforms_key(key)
  2962. key, _ = _redirect_platform_display_key(key)
  2963. config = load_config()
  2964. value = _get_nested(config, key)
  2965. if value is _MISSING and legacy_key:
  2966. value = _get_nested(config, legacy_key)
  2967. if value is _MISSING:
  2968. _exit_invalid(f"Config key not set: {key}")
  2969. from agent.redact import _redact_enabled, mask_secret
  2970. if not raw and _redact_enabled():
  2971. if isinstance(value, str):
  2972. if _is_secret_config_key(key) and not _ENV_PLACEHOLDER_RE.match(value):
  2973. value = mask_secret(value)
  2974. else:
  2975. value = redact_config_value(value)
  2976. print(_format_config_get_value(value, as_json=as_json), flush=True)
  2977. # Phantom-key notice (#112348): a nested path under a KNOWN section that the schema does not
  2978. # define (``compression.compressor.enabled``) is echoed straight from the user's file and is
  2979. # usually read by nothing, so it must not look like a live setting. Unseeded live keys pass via
  2980. # config_runtime_keys; the wording still hedges like the set-path notice. Custom top-level keys
  2981. # stay exempt (bridged into os.environ for skills) and ``_validate_config_key`` already accepts
  2982. # open-subkey sections. stderr keeps stdout/--json parseable; the exit code stays 0.
  2983. if _split_key_path(key)[0] in _known_top_level_keys():
  2984. is_known, suggestion = _validate_config_key(key)
  2985. if not is_known:
  2986. print(color(
  2987. f"⚠ '{key}' is not a recognized config key — Hermes may not read it; the value "
  2988. "printed above comes from your config file.", Colors.YELLOW), file=sys.stderr)
  2989. if suggestion:
  2990. print(color(f" Did you mean: {suggestion}", Colors.YELLOW), file=sys.stderr)
  2991. def unset_config_value(key: str):
  2992. """Remove a user-set configuration or .env value."""
  2993. if is_managed():
  2994. managed_error("unset configuration values")
  2995. return
  2996. _exit_if_key_managed(key, "unset")
  2997. if _is_env_config_key(key):
  2998. # Unified lifecycle: also prunes env-seeded credential_pool entries and model-cache rows so
  2999. # the provider is fully removed instead of left resurrectable (#51071).
  3000. from hermes_cli.credential_lifecycle import remove_provider_env_credential
  3001. try:
  3002. found = remove_provider_env_credential(key.upper()).get("found")
  3003. except ValueError as exc:
  3004. _exit_invalid(f"✗ {exc}")
  3005. if not found:
  3006. _exit_invalid(f"Config key not set: {key}")
  3007. print(f"✓ Unset {key} from {get_env_path()}")
  3008. return
  3009. from hermes_cli.config_env_routing import is_env_setting_key, remove_env_setting
  3010. if is_env_setting_key(key):
  3011. # Also drops a stale top-level config.yaml copy left by older `config set` runs (#111848).
  3012. try:
  3013. found = remove_env_setting(key)
  3014. except ValueError as exc:
  3015. _exit_invalid(f"✗ {exc}")
  3016. if not found:
  3017. _exit_invalid(f"Config key not set: {key}")
  3018. print(f"✓ Unset {key} from {get_env_path()}")
  3019. return
  3020. config_path = get_config_path()
  3021. user_config = require_readable_config_before_write(config_path)
  3022. legacy_key = _legacy_gateway_platforms_key(key)
  3023. key, _redirect_note = _redirect_platform_display_key(key)
  3024. if _redirect_note:
  3025. # Mirror set_config_value's display.platforms canonicalization (#71047).
  3026. print(_redirect_note.replace("saved as", "resolved as"))
  3027. removed = _unset_nested(user_config, key)
  3028. if legacy_key:
  3029. removed = _unset_nested(user_config, legacy_key) or removed
  3030. from hermes_cli.left_core_migration import LEFT_CORE_TERMINAL_KEYS
  3031. env_var = terminal_config_env_var_for_key(key) or LEFT_CORE_TERMINAL_KEYS.get(key)
  3032. if env_var and key != "terminal.cwd":
  3033. removed = remove_env_value(env_var) or removed
  3034. if not removed:
  3035. _exit_invalid(f"Config key not set: {key}")
  3036. _write_user_config(config_path, user_config)
  3037. print(f"✓ Unset {key} from {config_destination(config_path)}")
  3038. # ---- Command handler ----
  3039. def _usage_exit(usage: str, examples: list[str], extra: Optional[list[str]] = None) -> None:
  3040. print(usage)
  3041. print()
  3042. print("Examples:")
  3043. for line in examples:
  3044. print(f" {line}")
  3045. for line in extra or ():
  3046. print(line)
  3047. sys.exit(1)
  3048. def _run_write_command(fn, *args) -> None:
  3049. """Run a config writer, surfacing the fail-closed write guard's RuntimeError as a clean CLI
  3050. error instead of a traceback."""
  3051. try:
  3052. fn(*args)
  3053. except RuntimeError as exc:
  3054. _exit_invalid(f"✗ {exc}")
  3055. _USAGE_GET = ("Usage: hermes config get <key> [--json] [--raw]", [
  3056. "hermes config get model", "hermes config get terminal.backend",
  3057. "hermes config get skills.config --json"], None)
  3058. _USAGE_SET = ("Usage: hermes config set [--force] <key> <value>", [
  3059. "hermes config set model anthropic/claude-sonnet-4", "hermes config set terminal.backend docker",
  3060. "hermes config set OPENROUTER_API_KEY sk-or-..."], [
  3061. "", " --force: skip the unknown-key notice for unrecognized keys,",
  3062. " and allow a scalar to replace a whole mapping section"])
  3063. _USAGE_UNSET = ("Usage: hermes config unset <key>", [
  3064. "hermes config unset model", "hermes config unset terminal.backend",
  3065. "hermes config unset OPENROUTER_API_KEY"], None)
  3066. def _cmd_config_get(args):
  3067. key = getattr(args, 'key', None)
  3068. if not key:
  3069. _usage_exit(*_USAGE_GET)
  3070. get_config_value(key, as_json=getattr(args, 'json', False), raw=bool(getattr(args, 'raw', False)))
  3071. def _cmd_config_set(args):
  3072. key = getattr(args, 'key', None)
  3073. value = getattr(args, 'value', None)
  3074. if not key or value is None:
  3075. _usage_exit(*_USAGE_SET)
  3076. _run_write_command(set_config_value, key, value, bool(getattr(args, 'force', False)))
  3077. def _cmd_config_unset(args):
  3078. key = getattr(args, 'key', None)
  3079. if not key:
  3080. _usage_exit(*_USAGE_UNSET)
  3081. _run_write_command(unset_config_value, key)
  3082. def _tools_suffix(info: dict[str, Any], fmt: str) -> str:
  3083. tools = info.get("tools", [])
  3084. return fmt.format(", ".join(tools[:2])) if tools else ""
  3085. def _print_banner(text: str) -> None:
  3086. print()
  3087. print(color(text, Colors.CYAN, Colors.BOLD))
  3088. print()
  3089. def _cmd_config_migrate(args):
  3090. _print_banner("🔄 Checking configuration for updates...")
  3091. missing_env = get_missing_env_vars(required_only=False)
  3092. missing_config = get_missing_config_fields()
  3093. current_ver, latest_ver = check_config_version(raise_on_parse_error=True)
  3094. if not missing_env and not missing_config and current_ver >= latest_ver:
  3095. print(color("✓ Configuration is up to date!", Colors.GREEN))
  3096. print()
  3097. return
  3098. if current_ver < latest_ver:
  3099. print(f" Config version: {current_ver} → {latest_ver}")
  3100. if missing_config:
  3101. print(f"\n {len(missing_config)} new config option(s) will be added with defaults")
  3102. required_missing = [v for v in missing_env if v.get("is_required")]
  3103. optional_missing = [v for v in missing_env if not v.get("is_required") and not v.get("advanced")]
  3104. for heading, group, suffix in (
  3105. ("⚠️ {} required API key(s) missing:", required_missing, ""),
  3106. ("ℹ️ {} optional API key(s) not configured:", optional_missing, " (enables: {})")):
  3107. if group:
  3108. print(f"\n {heading.format(len(group))}")
  3109. for var in group:
  3110. print(f" • {var['name']}{_tools_suffix(var, suffix) if suffix else ''}")
  3111. print()
  3112. results = migrate_config(interactive=True, quiet=False)
  3113. print()
  3114. if results["env_added"] or results["config_added"]:
  3115. print(color("✓ Configuration updated!", Colors.GREEN))
  3116. if results["warnings"]:
  3117. print()
  3118. for warning in results["warnings"]:
  3119. print(color(f" ⚠️ {warning}", Colors.YELLOW))
  3120. print()
  3121. def _cmd_config_check(args):
  3122. """Non-interactive report of missing and stale configuration."""
  3123. _print_banner("📋 Configuration Status")
  3124. current_ver, latest_ver = check_config_version(raise_on_parse_error=True)
  3125. if current_ver >= latest_ver:
  3126. print(f" Config version: {current_ver} ✓")
  3127. else:
  3128. print(color(f" Config version: {current_ver} → {latest_ver} (update available)", Colors.YELLOW))
  3129. groups = (
  3130. ("Required", REQUIRED_ENV_VARS, lambda n, i: color(f" ✗ {n} (missing)", Colors.RED)),
  3131. ("Optional", OPTIONAL_ENV_VARS,
  3132. lambda n, i: color(f" ○ {n}{_tools_suffix(i, ' → {}')}", Colors.DIM)))
  3133. for title, table, missing_line in groups:
  3134. print()
  3135. print(color(f" {title}:", Colors.BOLD))
  3136. for var_name, info in table.items():
  3137. print(f" ✓ {var_name}" if get_env_value(var_name) else missing_line(var_name, info))
  3138. missing_config = get_missing_config_fields()
  3139. if missing_config:
  3140. print()
  3141. print(color(f" {len(missing_config)} new config option(s) available", Colors.YELLOW))
  3142. print(" Run 'hermes config migrate' to add them")
  3143. from hermes_cli.config_check_diagnostics import config_check_diagnostics
  3144. diagnostics = config_check_diagnostics(read_raw_config_readonly(), get_env_value)
  3145. if diagnostics:
  3146. print()
  3147. print(color(" Saved configuration:", Colors.BOLD))
  3148. for diagnostic in diagnostics:
  3149. print(color(f" ⚠ {diagnostic}", Colors.YELLOW))
  3150. print()
  3151. def _cmd_config_show() -> None:
  3152. from hermes_cli.config_show import show_config
  3153. show_config()
  3154. _CONFIG_SUBCOMMANDS = {
  3155. None: lambda args: _cmd_config_show(),
  3156. "show": lambda args: _cmd_config_show(),
  3157. "edit": lambda args: edit_config(),
  3158. "get": _cmd_config_get,
  3159. "set": _cmd_config_set,
  3160. "unset": _cmd_config_unset,
  3161. "path": lambda args: print(get_config_path()),
  3162. "env-path": lambda args: print(get_env_path()),
  3163. "migrate": _cmd_config_migrate,
  3164. "check": _cmd_config_check}
  3165. _CONFIG_USAGE = """Available commands:
  3166. hermes config Show current configuration
  3167. hermes config edit Open config in editor
  3168. hermes config get <key> Print a resolved config value
  3169. hermes config set <key> <value> Set a config value
  3170. hermes config unset <key> Remove a config value
  3171. hermes config check Check for missing, outdated, or inactive config
  3172. hermes config migrate Update config with new options
  3173. hermes config path Show config file path
  3174. hermes config env-path Show .env file path"""
  3175. def config_command(args):
  3176. """Handle config subcommands."""
  3177. subcmd = getattr(args, 'config_command', None)
  3178. handler = _CONFIG_SUBCOMMANDS.get(subcmd)
  3179. if handler is not None:
  3180. try:
  3181. handler(args)
  3182. except ConfigWriteError as exc: # a backend refusal (a remote lock, a secret literal): nothing changed
  3183. print(f"Error: {exc}", file=sys.stderr)
  3184. sys.exit(1)
  3185. return
  3186. print(f"Unknown config command: {subcmd}")
  3187. print()
  3188. print(_CONFIG_USAGE)
  3189. sys.exit(1)
  3190. # ---- OPTIONAL_ENV_VARS: platform plugin entries at import; provider entries on first read ----
  3191. PlatformManifestSource = Literal["all", "bundled", "user"]
  3192. def _is_plugin_dir_name(name: str) -> bool:
  3193. # Same rule as plugins_discovery.scan_directory: __pycache__-style dunders aren't plugins; a dot
  3194. # dir can be, so its secrets are declared too.
  3195. return not (name.startswith("__") and name.endswith("__"))
  3196. def _platform_manifest_paths(home: Optional[Path] = None, source: PlatformManifestSource = "all"):
  3197. """Yield ``(dir_name, manifest_path, require_kind, stat)`` for every platform plugin manifest.
  3198. ``source`` is ``"bundled"`` (shipped ``plugins/platforms/*``), ``"user"`` (``<home>/plugins/
  3199. platforms/*`` plus flat ``<home>/plugins/*`` installs, which must declare ``kind: platform``,
  3200. #46600) or ``"all"``. ``home`` defaults to the bound Hermes home. A directory that cannot be
  3201. listed or searched yields ``(name, None, require_kind, error)``: a plugin there can't load
  3202. either, so callers skip it. One ``scandir`` per root and one ``stat`` per candidate, because
  3203. the child-env scrub stamps these on every spawn."""
  3204. roots = []
  3205. if source in ("all", "bundled"):
  3206. roots.append((get_project_root() / "plugins" / "platforms", False))
  3207. if source in ("all", "user"):
  3208. user_plugins = (home if home is not None else get_hermes_home()) / "plugins"
  3209. roots += [(user_plugins / "platforms", False), (user_plugins, True)]
  3210. for root, require_kind in roots:
  3211. try:
  3212. with os.scandir(root) as it:
  3213. entries = [e for e in it if _is_plugin_dir_name(e.name)]
  3214. except (FileNotFoundError, NotADirectoryError):
  3215. continue
  3216. except OSError as exc:
  3217. yield str(root), None, require_kind, exc
  3218. continue
  3219. for entry in entries:
  3220. try:
  3221. if not entry.is_dir():
  3222. continue
  3223. except OSError:
  3224. continue
  3225. for file_name in ("plugin.yaml", "plugin.yml"):
  3226. path = Path(entry.path) / file_name
  3227. try:
  3228. st = os.stat(path)
  3229. except PermissionError as exc: # the dir itself is not searchable
  3230. yield entry.name, None, require_kind, exc
  3231. break
  3232. except OSError: # missing, a symlink loop: discovery's exists() is False too
  3233. continue
  3234. if not stat.S_ISREG(st.st_mode):
  3235. continue
  3236. yield entry.name, path, require_kind, st
  3237. break
  3238. def platform_manifest_stamp(home: Optional[Path] = None) -> tuple:
  3239. """Change-detection key over every user platform plugin manifest of ``home`` (path plus
  3240. :func:`utils.file_signature`): it changes when one is added, removed, replaced or edited in
  3241. place, so a cache keyed on it never serves a stale declaration."""
  3242. return tuple((name, str(path), file_signature(st) if path is not None else type(st).__name__)
  3243. for name, path, _kind, st in _platform_manifest_paths(home, "user"))
  3244. def _platform_plugin_manifests(home: Optional[Path] = None, source: PlatformManifestSource = "all", *,
  3245. strict: bool = False, skipped: list | None = None):
  3246. """Yield ``(dir_name, manifest_dict)`` for every platform plugin manifest (see
  3247. :func:`_platform_manifest_paths`). ``strict`` raises when a manifest cannot be read instead of
  3248. skipping it: the child-env scrub must not lose a declared secret to an I/O error. Only a
  3249. manifest known to be a platform's counts (the bundled and ``plugins/platforms/`` dirs); a
  3250. flat ``plugins/*`` manifest proves it is one only by its content, so an unreadable one is
  3251. skipped with a warning, as is an unsearchable plugin directory. A manifest that does not
  3252. parse declares nothing (its adapter cannot load either) and is skipped. Every skip is appended
  3253. to ``skipped``, so a caller can tell a complete scan from a partial one. A safe worker reads
  3254. no plugin manifest at all."""
  3255. from agent.safe_worker_policy import safe_worker_enabled
  3256. if safe_worker_enabled():
  3257. return
  3258. for dir_name, manifest_path, require_kind, st in _platform_manifest_paths(home, source):
  3259. if manifest_path is None:
  3260. logger.warning("Skipping unreadable plugin directory %s: %s", dir_name, st)
  3261. if skipped is not None:
  3262. skipped.append(dir_name)
  3263. continue
  3264. try:
  3265. with open(manifest_path, "r", encoding="utf-8-sig") as f:
  3266. manifest = fast_safe_load(f) or {}
  3267. except OSError as exc:
  3268. if strict and not require_kind:
  3269. raise
  3270. logger.warning("Skipping unreadable plugin manifest %s: %s", manifest_path, exc)
  3271. if skipped is not None:
  3272. skipped.append(str(manifest_path))
  3273. continue
  3274. except Exception:
  3275. if skipped is not None:
  3276. skipped.append(str(manifest_path))
  3277. continue
  3278. if not isinstance(manifest, dict) or (require_kind and manifest.get("kind") != "platform"):
  3279. continue
  3280. yield dir_name, manifest
  3281. # Env-name suffixes that make a platform variable a secret unless its declaration says otherwise.
  3282. PLATFORM_SECRET_ENV_SUFFIXES = ("_TOKEN", "_SECRET", "_KEY", "_PASSWORD", "_JSON")
  3283. def _platform_manifest_env_entries(manifest: dict, *, optional: bool = True):
  3284. """Yield ``(name, is_secret, meta)`` for a manifest's ``requires_env`` (and, unless
  3285. ``optional=False``, ``optional_env``) entries (a bare name or a dict with ``name`` plus optional
  3286. ``description``/``url``/``password``/``prompt``/``category``). A name ending in
  3287. PLATFORM_SECRET_ENV_SUFFIXES is a password field unless the entry says ``password: false``."""
  3288. for entry in [*(manifest.get("requires_env") or []), *((manifest.get("optional_env") or []) if optional else [])]:
  3289. meta = {"name": entry} if isinstance(entry, str) else entry if isinstance(entry, dict) else {}
  3290. name = meta.get("name")
  3291. if not name or not isinstance(name, str):
  3292. continue
  3293. is_secret = bool(meta.get("password") or meta.get("secret"))
  3294. if not is_secret and not meta.get("password") is False:
  3295. is_secret = name.upper().endswith(PLATFORM_SECRET_ENV_SUFFIXES)
  3296. yield name, is_secret, meta
  3297. def _manifest_secret_envs(manifests, core: Optional[frozenset[str]] = None) -> frozenset[str]:
  3298. """Upper-cased secret messaging env names the given manifests declare, minus core-declared
  3299. names: a manifest never reclassifies a core variable such as OPENAI_API_KEY."""
  3300. names = {name.upper() for _dir, manifest in manifests
  3301. for name, is_secret, meta in _platform_manifest_env_entries(manifest)
  3302. if is_secret and (meta.get("category") or "messaging") == "messaging"}
  3303. return frozenset(names - {n.upper() for n in (core if core is not None else core_declared_env_names())})
  3304. def platform_manifest_secret_envs(home: Optional[Path] = None, source: PlatformManifestSource = "user", *,
  3305. strict: bool = False) -> frozenset[str]:
  3306. """Secret env names declared by one source's platform plugin manifests: ``"user"`` reads only
  3307. ``home``'s user-installed plugins, which belong to that profile alone; ``"bundled"`` returns
  3308. the set read once at import (re-read strictly if that read hit an I/O error)."""
  3309. if source == "bundled" and BUNDLED_PLATFORM_SECRET_ENVS is not None: # minus provider names, known only now
  3310. return frozenset(BUNDLED_PLATFORM_SECRET_ENVS - {n.upper() for n in core_declared_env_names()})
  3311. return _manifest_secret_envs(_platform_plugin_manifests(home, source, strict=strict))
  3312. def platform_manifest_secret_scan(home: Optional[Path] = None) -> tuple[frozenset[str], bool]:
  3313. """``home``'s user-installed platform plugin secrets, strictly read, and whether the scan was
  3314. complete: False when a plugin dir or flat manifest could not be read or parsed, so the caller
  3315. keeps the denials it already knew instead of releasing them on a failed discovery."""
  3316. skipped: list = []
  3317. names = _manifest_secret_envs(_platform_plugin_manifests(home, "user", strict=True, skipped=skipped))
  3318. return names, not skipped
  3319. def _inject_platform_plugin_env_vars() -> frozenset[str] | None:
  3320. """Populate OPTIONAL_ENV_VARS from platform plugin manifests (bundled AND user-installed) so
  3321. Teams / IRC / Google Chat and third-party platforms are configurable in the ``hermes config`` /
  3322. Desktop Gateway form without the core knowing they exist. Failures are swallowed so a
  3323. malformed plugin.yaml can't break CLI import. Returns the bundled manifests' secret names, or
  3324. None when a bundled manifest could not be read (the policy then re-reads strictly).
  3325. """
  3326. bundled: list | None = []
  3327. try:
  3328. bundled = list(_platform_plugin_manifests(source="bundled", strict=True))
  3329. except OSError:
  3330. bundled = None
  3331. manifests = list(bundled or [])
  3332. for source in ("bundled", "user") if bundled is None else ("user",):
  3333. try:
  3334. manifests += list(_platform_plugin_manifests(source=source))
  3335. except Exception:
  3336. pass
  3337. for dir_name, manifest in manifests:
  3338. label = manifest.get("label") or manifest.get("name") or dir_name
  3339. for name, is_secret, meta in _platform_manifest_env_entries(manifest):
  3340. if name in OPTIONAL_ENV_VARS:
  3341. continue # hardcoded entry wins (back-compat)
  3342. OPTIONAL_ENV_VARS[name] = {
  3343. "description": meta.get("description") or f"{label} configuration",
  3344. "prompt": meta.get("prompt") or name,
  3345. "url": meta.get("url") or None,
  3346. "password": is_secret,
  3347. "category": meta.get("category") or "messaging"}
  3348. return _manifest_secret_envs(bundled, _STATIC_CORE_ENV_NAMES) if bundled is not None else None
  3349. # Names declared in core, before any platform manifest is read. A manifest never reclassifies
  3350. # one: the config form keeps the core entry, and the child-env scrub keeps a plugin that lists
  3351. # OPENAI_API_KEY from turning a provider key into an adapter secret. CORE_DECLARED_ENV_NAMES adds
  3352. # the provider profiles' names on first use (module __getattr__): listing them reads config.
  3353. _STATIC_CORE_ENV_NAMES: frozenset[str] = frozenset(dict.keys(OPTIONAL_ENV_VARS))
  3354. BUNDLED_PLATFORM_SECRET_ENVS: frozenset[str] | None = _inject_platform_plugin_env_vars()
  3355. _config_provider_env.arm(OPTIONAL_ENV_VARS, _STATIC_CORE_ENV_NAMES)
  3356. def __getattr__(name: str) -> Any:
  3357. if name == "CORE_DECLARED_ENV_NAMES":
  3358. return core_declared_env_names()
  3359. raise AttributeError(f"module {__name__!r} has no attribute {name!r}")