config_migrations.py 45 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931
  1. """Table-driven config migration registry.
  2. Each step is ``_migrate_to_N(results, quiet)`` (a large topical step lives in a
  3. ``config_migrations_<topic>.py`` sibling, registered here); the version gate and strict ascending
  4. order live in :func:`run_migrations`. Every write goes through ``hermes_cli.config._persist_migration`` so a
  5. step may only persist values that differ from the schema default (plus removals/renames).
  6. """
  7. from __future__ import annotations
  8. import contextvars
  9. import copy
  10. import functools
  11. import logging
  12. import re
  13. from typing import Any, Callable, Dict, List, Optional, Tuple
  14. from urllib.parse import urlparse
  15. from hermes_cli.config_migrations_browser import migrate_to_52
  16. logger = logging.getLogger(__name__)
  17. #: Auto-migration support floor. Configs whose on-disk ``_config_version`` is below this are NOT
  18. #: auto-migrated (v12 predates ~two years of releases; carrying the sub-v12 steps and the env
  19. #: bridges they consumed forever is not worth it). Below-floor configs are left byte-for-byte
  20. #: untouched — the process continues with defaults deep-merged at read time, matching the
  21. #: non-fatal posture for unparseable configs — and a message tells the user how to proceed.
  22. SUPPORT_FLOOR_VERSION = 12
  23. #: True while :func:`run_migrations` runs with ``config_only=True``: the remote config backend's
  24. #: in-memory migrations (D12) and its write-validation simulation. Such a run transforms the config
  25. #: document and nothing else: steps that also touch local files (``.env``, profile ``SOUL.md``,
  26. #: ``logs/``) skip that part, so reading a profile's remote config, or a refused write's check, never
  27. #: changes a file on disk — a sibling profile's least of all.
  28. _CONFIG_ONLY: contextvars.ContextVar[bool] = contextvars.ContextVar("config_migrations_config_only", default=False)
  29. def _local_files_allowed() -> bool:
  30. """Whether the running step may change files other than the config document itself."""
  31. return not _CONFIG_ONLY.get()
  32. def support_floor_message() -> str:
  33. """Human-facing explanation shown when a config is below the floor."""
  34. from hermes_constants import display_hermes_home
  35. return (
  36. f"This config predates version {SUPPORT_FLOOR_VERSION} (~2 years old) "
  37. "and can no longer be auto-migrated. Back up "
  38. f"{display_hermes_home()}/config.yaml and run `hermes setup` to "
  39. f"regenerate, or manually set _config_version: {SUPPORT_FLOOR_VERSION} "
  40. "after reviewing the changelog.")
  41. def _cfg():
  42. """Return the live ``hermes_cli.config`` module (lazy, cycle-free, monkeypatch-friendly)."""
  43. from hermes_cli import config
  44. return config
  45. def read_raw_config():
  46. return _cfg().read_raw_config()
  47. def _persist_migration(config):
  48. _cfg()._persist_migration(config)
  49. def _dict_at(config: dict[str, Any], key: str) -> dict[str, Any]:
  50. """``config[key]`` when it is a mapping (same object, so writes alias), else a fresh ``{}``."""
  51. value = config.get(key)
  52. return value if isinstance(value, dict) else {}
  53. def _commit(
  54. config: dict[str, Any],
  55. results: dict[str, Any],
  56. quiet: bool,
  57. added: Optional[str],
  58. message: Optional[str]) -> None:
  59. """Persist *config*, record *added* under ``config_added`` and print *message* unless quiet."""
  60. _persist_migration(config)
  61. if added:
  62. results["config_added"].append(added)
  63. if message and not quiet:
  64. print(message)
  65. def _rewrite_key(
  66. results: dict[str, Any],
  67. quiet: bool,
  68. *,
  69. section: str,
  70. key: str,
  71. match: Callable[[Any], bool],
  72. new: Any,
  73. added: str,
  74. message: str,
  75. extra_guard: Callable[[dict[str, Any]], bool] = lambda _m: True,
  76. create_section: bool = False) -> None:
  77. """Rewrite ``<section>.<key>`` to *new* (None = delete) when ``match(current)`` holds; a
  78. missing section is skipped unless *create_section*."""
  79. config = read_raw_config()
  80. raw = config.get(section)
  81. if not isinstance(raw, dict):
  82. if not create_section:
  83. return
  84. raw = {}
  85. if match(raw.get(key)) and extra_guard(raw):
  86. if new is None:
  87. del raw[key]
  88. else:
  89. raw[key] = new
  90. config[section] = raw
  91. _commit(config, results, quiet, added, message)
  92. def _rewrite_stale_default(*, old: Any, **kw: Any) -> Callable[[dict[str, Any], bool], None]:
  93. """Step rewriting a key only while it still equals the OLD default — never clobbers a value
  94. the user customized; unset keys inherit the new default at read time."""
  95. return functools.partial(_rewrite_key, match=lambda cur: cur == old, **kw)
  96. def _lower_is(word: str) -> Callable[[Any], bool]:
  97. return lambda cur: isinstance(cur, str) and cur.strip().lower() == word
  98. def _migrate_to_12(results: dict[str, Any], quiet: bool) -> None:
  99. # 11 → 12: custom_providers list → providers dict.
  100. _custom_provider_entry_to_provider_config = _cfg()._custom_provider_entry_to_provider_config
  101. config = read_raw_config()
  102. custom_list = config.get("custom_providers")
  103. if not (isinstance(custom_list, list) and custom_list):
  104. return
  105. providers_dict = _dict_at(config, "providers")
  106. migrated_count = 0
  107. for entry in custom_list:
  108. if not isinstance(entry, dict):
  109. continue
  110. old_name = entry.get("name", "")
  111. if not isinstance(old_name, str): # hand-edited name: 5 must not crash .strip()
  112. old_name = ""
  113. old_url = entry.get("base_url", "") or entry.get("url", "") or entry.get("api", "") or ""
  114. if not old_url:
  115. continue
  116. # kebab-case key from the display name; fall back to the URL hostname.
  117. key = old_name.strip().lower().replace(" ", "-").replace("(", "").replace(")", "")
  118. key = re.sub(r"-{2,}", "-", key).strip("-")
  119. if not key:
  120. try:
  121. key = (urlparse(old_url).hostname or "endpoint").replace(".", "-")
  122. except Exception:
  123. key = f"endpoint-{migrated_count}"
  124. # Don't overwrite existing entries
  125. base_key = key
  126. suffix = migrated_count
  127. while key in providers_dict:
  128. key = f"{base_key}-{suffix}"
  129. suffix += 1
  130. new_entry = _custom_provider_entry_to_provider_config(entry, provider_key=key)
  131. if new_entry is None:
  132. continue
  133. if not old_name:
  134. new_entry.pop("name", None)
  135. if new_entry.get("api_key") in {"no-key", "no-key-required", ""}:
  136. new_entry.pop("api_key", None)
  137. providers_dict[key] = new_entry
  138. migrated_count += 1
  139. if migrated_count > 0:
  140. config["providers"] = providers_dict
  141. # Runtime reads the list view via get_compatible_custom_providers().
  142. config.pop("custom_providers", None)
  143. _persist_migration(config)
  144. if not quiet:
  145. print(f" ✓ Migrated {migrated_count} custom provider(s) to providers: section")
  146. for key in list(providers_dict.keys())[-migrated_count:]:
  147. print(f" → {key}: {providers_dict[key].get('api', '')}")
  148. def _migrate_to_13(results: dict[str, Any], quiet: bool) -> None:
  149. # 12 → 13: clear dead LLM_MODEL / OPENAI_MODEL from .env (written by the old setup wizard;
  150. # nothing reads them — config.yaml is the sole source of truth).
  151. if not _local_files_allowed():
  152. return # .env only
  153. _c = _cfg()
  154. for dead_var in ("LLM_MODEL", "OPENAI_MODEL"):
  155. try:
  156. if _c.get_env_value(dead_var):
  157. _c.save_env_value(dead_var, "")
  158. if not quiet:
  159. print(f" ✓ Cleared {dead_var} from .env (no longer used — config.yaml is source of truth)")
  160. except Exception:
  161. pass
  162. _LOCAL_WHISPER_MODELS = frozenset({
  163. "tiny.en", "tiny", "base.en", "base", "small.en", "small",
  164. "medium.en", "medium", "large-v1", "large-v2", "large-v3",
  165. "large", "distil-large-v2", "distil-medium.en",
  166. "distil-small.en", "distil-large-v3", "distil-large-v3.5",
  167. "large-v3-turbo", "turbo"})
  168. def _migrate_to_14(results: dict[str, Any], quiet: bool) -> None:
  169. # 13 → 14: legacy flat stt.model → provider section. A provider-agnostic `stt.model` fed
  170. # OpenAI names to faster-whisper ("Invalid model size"). Only the raw (user-written) config
  171. # decides; a nested model the user already set is never overwritten.
  172. raw_stt = read_raw_config().get("stt", {})
  173. if not (isinstance(raw_stt, dict) and "model" in raw_stt):
  174. return
  175. legacy_model = raw_stt["model"]
  176. provider = raw_stt.get("provider", "local")
  177. if not isinstance(provider, str): # a mapping/int provider has no valid target section
  178. provider = "local"
  179. config = read_raw_config()
  180. stt = config.get("stt", {})
  181. stt.pop("model", None)
  182. def _place(section: str) -> None:
  183. existing = raw_stt.get(section, {})
  184. if not isinstance(existing, dict) or "model" not in existing:
  185. target = stt.get(section)
  186. if not isinstance(target, dict): # stt.<section>: 5 — replace, don't index a scalar
  187. target = stt[section] = {}
  188. target["model"] = legacy_model
  189. if provider in {"local", "local_command"}:
  190. # An OpenAI model name is dropped; the local section already defaults to "base".
  191. if isinstance(legacy_model, str) and legacy_model in _LOCAL_WHISPER_MODELS:
  192. _place("local")
  193. else:
  194. _place(provider)
  195. config["stt"] = stt
  196. _commit(
  197. config, results, quiet, None, " ✓ Migrated legacy stt.model to provider-specific config")
  198. def _migrate_to_16(results: dict[str, Any], quiet: bool) -> None:
  199. # 15 → 16: display.tool_progress_overrides → display.platforms.<plat>.tool_progress.
  200. config = read_raw_config()
  201. display = _dict_at(config, "display")
  202. old_overrides = display.get("tool_progress_overrides")
  203. if not (isinstance(old_overrides, dict) and old_overrides):
  204. return
  205. platforms = _dict_at(display, "platforms")
  206. for plat, mode in old_overrides.items():
  207. target = platforms.get(plat)
  208. if not isinstance(target, dict): # platforms.<plat>: 5 — replace, don't index a scalar
  209. target = platforms[plat] = {}
  210. if "tool_progress" not in target:
  211. target["tool_progress"] = mode
  212. display["platforms"] = platforms
  213. config["display"] = display
  214. migrated = ", ".join(f"{p}={m}" for p, m in old_overrides.items())
  215. _commit(
  216. config, results, quiet,
  217. "display.platforms (migrated from tool_progress_overrides)",
  218. f" ✓ Migrated tool_progress_overrides → display.platforms: {migrated}")
  219. def _migrate_to_17(results: dict[str, Any], quiet: bool) -> None:
  220. # 16 → 17: remove legacy compression.summary_* keys; non-empty, non-default values move to
  221. # auxiliary.compression without overriding an explicit (non-"auto") aux value.
  222. config = read_raw_config()
  223. comp = config.get("compression", {})
  224. if not isinstance(comp, dict):
  225. return
  226. legacy = {k: comp.pop(f"summary_{k}", None) for k in ("model", "provider", "base_url")}
  227. migrated_keys = []
  228. for k, raw in legacy.items():
  229. val = str(raw).strip() if raw else ""
  230. if not val or (k == "provider" and val == "auto"):
  231. continue
  232. aux = config.get("auxiliary")
  233. if not isinstance(aux, dict): # auxiliary: 5 — setdefault would index a scalar
  234. aux = config["auxiliary"] = {}
  235. aux_comp = aux.get("compression")
  236. if not isinstance(aux_comp, dict):
  237. aux_comp = aux["compression"] = {}
  238. cur = aux_comp.get(k)
  239. if not cur or (k == "provider" and cur == "auto"):
  240. aux_comp[k] = val
  241. migrated_keys.append(f"{k}={raw}")
  242. if migrated_keys or any(v is not None for v in legacy.values()):
  243. config["compression"] = comp
  244. message = (
  245. " ✓ Migrated compression.summary_* → auxiliary.compression: "
  246. f"{', '.join(migrated_keys)}"
  247. if migrated_keys else " ✓ Removed unused compression.summary_* keys")
  248. _commit(config, results, quiet, None, message)
  249. def _installed_user_plugins(disabled: set) -> list[str]:
  250. """Names of plugins under ``$HERMES_HOME/plugins/`` with a manifest, minus *disabled*."""
  251. _c = _cfg()
  252. found: list[str] = []
  253. try:
  254. user_plugins_dir = _c.get_hermes_home() / "plugins"
  255. if user_plugins_dir.is_dir():
  256. for child in sorted(user_plugins_dir.iterdir()):
  257. if not child.is_dir():
  258. continue
  259. manifest_file = child / "plugin.yaml"
  260. if not manifest_file.exists():
  261. manifest_file = child / "plugin.yml"
  262. if not manifest_file.exists():
  263. continue
  264. try:
  265. with open(manifest_file, encoding="utf-8-sig") as _mf:
  266. manifest = _c.fast_safe_load(_mf) or {}
  267. except Exception:
  268. manifest = {}
  269. name = manifest.get("name") or child.name
  270. if name not in disabled:
  271. found.append(name)
  272. except Exception:
  273. return []
  274. return found
  275. def _migrate_to_21(results: dict[str, Any], quiet: bool) -> None:
  276. # 20 → 21: plugins are now opt-in (loader requires ``plugins.enabled``). Grandfather installed
  277. # user plugins not already disabled; bundled plugins ship off and need explicit opt-in.
  278. config = read_raw_config()
  279. plugins_cfg = _dict_at(config, "plugins")
  280. if "enabled" in plugins_cfg:
  281. return
  282. disabled = plugins_cfg.get("disabled", []) or []
  283. grandfathered = _installed_user_plugins(set(disabled) if isinstance(disabled, list) else set())
  284. plugins_cfg["enabled"] = grandfathered
  285. config["plugins"] = plugins_cfg
  286. message = (
  287. f" ✓ Plugins now opt-in: grandfathered "
  288. f"{len(grandfathered)} existing plugin(s) into plugins.enabled"
  289. if grandfathered else
  290. " ✓ Plugins now opt-in: no existing plugins to grandfather. "
  291. "Use `hermes plugins enable <name>` to activate.")
  292. _commit(
  293. config, results, quiet,
  294. f"plugins.enabled (opt-in allow-list, {len(grandfathered)} grandfathered)", message)
  295. def _migrate_to_23(results: dict[str, Any], quiet: bool) -> None:
  296. # 22 → 23: seed curator defaults + create logs/curator/. Older configs never wrote the curator
  297. # section; deep-merge made it work but users could not see/edit it and `hermes curator status`
  298. # had no stable logs dir. Only keys the user hasn't set are written.
  299. _c = _cfg()
  300. DEFAULT_CONFIG = _c.DEFAULT_CONFIG
  301. if _local_files_allowed():
  302. try:
  303. curator_dir = _c.get_hermes_home() / "logs" / "curator"
  304. curator_dir.mkdir(parents=True, exist_ok=True)
  305. except Exception as e:
  306. results["warnings"].append(f"Could not create {curator_dir}: {e}")
  307. config = read_raw_config()
  308. def _seed_missing(section: dict[str, Any], defaults: dict[str, Any]) -> list[str]:
  309. added = [k for k in defaults if k not in section]
  310. for k in added:
  311. section[k] = copy.deepcopy(defaults[k])
  312. return added
  313. raw_curator = _dict_at(config, "curator")
  314. added_curator = _seed_missing(raw_curator, DEFAULT_CONFIG.get("curator", {}))
  315. if added_curator:
  316. config["curator"] = raw_curator
  317. raw_aux = _dict_at(config, "auxiliary")
  318. raw_aux_curator = _dict_at(raw_aux, "curator")
  319. added_aux = _seed_missing(
  320. raw_aux_curator, DEFAULT_CONFIG.get("auxiliary", {}).get("curator", {}))
  321. if added_aux:
  322. raw_aux["curator"] = raw_aux_curator
  323. config["auxiliary"] = raw_aux
  324. if added_curator or added_aux:
  325. _persist_migration(config)
  326. for label, added in (("curator", added_curator), ("auxiliary.curator", added_aux)):
  327. if not added:
  328. continue
  329. results["config_added"].append(f"{label} ({len(added)} default key(s))")
  330. if not quiet:
  331. print(
  332. f" ✓ {'Curator' if label == 'curator' else label} settings now available "
  333. f"({', '.join(added)}) — edit via `hermes config set`")
  334. def _migrate_to_29(results: dict[str, Any], quiet: bool) -> None:
  335. # 28 → 29: memory/skills tri-state write_mode (on|off|approve) → boolean write_approval.
  336. # Only "approve" carried gating intent → true; the old "off = block writes" mode is dropped
  337. # (memory_enabled: false disables memory). Only a persisted key is rewritten.
  338. config = read_raw_config()
  339. touched = False
  340. for subsystem in ("memory", "skills"):
  341. sub = config.get(subsystem)
  342. if not isinstance(sub, dict) or "write_mode" not in sub:
  343. continue
  344. old = sub.pop("write_mode")
  345. old_norm = old.strip().lower() if isinstance(old, str) else old
  346. sub["write_approval"] = (old_norm == "approve")
  347. config[subsystem] = sub
  348. touched = True
  349. results["config_added"].append(
  350. f"{subsystem}.write_mode → write_approval={sub['write_approval']}")
  351. if touched:
  352. _commit(config, results, quiet, None,
  353. " ✓ Renamed write_mode → write_approval (boolean gate)")
  354. # 29 → 30 (curator.consolidate defaults to false) is schema-default-only: deep-merge supplies it
  355. # at read time and persisting a default would only bloat a lean config. No registry entry.
  356. def _migrate_to_33(results: dict[str, Any], quiet: bool) -> None:
  357. # 32 → 33: max_async_children is deprecated; fold a raised value into max_concurrent_children
  358. # (take the max so nobody loses headroom), then drop it.
  359. config = read_raw_config()
  360. raw_deleg = config.get("delegation")
  361. if not (isinstance(raw_deleg, dict) and "max_async_children" in raw_deleg):
  362. return
  363. old_async = raw_deleg.pop("max_async_children")
  364. try:
  365. old_async_i = int(old_async)
  366. except (TypeError, ValueError):
  367. old_async_i = None
  368. if old_async_i is not None and old_async_i > 3:
  369. try:
  370. cur_children = int(raw_deleg.get("max_concurrent_children", 3))
  371. except (TypeError, ValueError):
  372. cur_children = 3
  373. if old_async_i > cur_children:
  374. raw_deleg["max_concurrent_children"] = old_async_i
  375. results["config_added"].append(
  376. f"delegation.max_concurrent_children={old_async_i} "
  377. f"(folded from deprecated max_async_children)")
  378. config["delegation"] = raw_deleg
  379. _commit(
  380. config, results, quiet, None,
  381. " ✓ Removed deprecated delegation.max_async_children — "
  382. "delegation.max_concurrent_children now caps background "
  383. "delegations too.")
  384. def _migrate_to_34(results: dict[str, Any], quiet: bool) -> None:
  385. # 33 → 34: one-time personality reset. Persistence used to be split (TUI/desktop wrote the
  386. # NAME to display.personality, CLI/gateway wrote rendered TEXT to agent.system_prompt), so
  387. # once display.personality became authoritative, stale names resurrected personalities users
  388. # had turned off. Reset display.personality → "" and scrub agent.system_prompt ONLY when it
  389. # verbatim-equals a known personality's rendered text; any other text is user-owned.
  390. from hermes_cli.personality import (
  391. available_personalities, normalize_personality_name, prompt_text, render_personality_prompt)
  392. config = read_raw_config()
  393. touched = False
  394. raw_display = config.get("display")
  395. old_name = ""
  396. if isinstance(raw_display, dict):
  397. old_name = normalize_personality_name(raw_display.get("personality", ""))
  398. if old_name:
  399. raw_display["personality"] = ""
  400. config["display"] = raw_display
  401. touched = True
  402. raw_agent = config.get("agent")
  403. scrubbed_text = False
  404. if isinstance(raw_agent, dict):
  405. manual = prompt_text(raw_agent.get("system_prompt", ""))
  406. if manual:
  407. rendered = {
  408. render_personality_prompt(defn) for defn in available_personalities(config).values()
  409. }
  410. if manual in rendered:
  411. raw_agent["system_prompt"] = ""
  412. config["agent"] = raw_agent
  413. touched = True
  414. scrubbed_text = True
  415. if not touched:
  416. return
  417. _commit(config, results, quiet, "display.personality=none (one-time reset)", None)
  418. if quiet:
  419. return
  420. if old_name:
  421. print(
  422. f" ✓ Personality reset to none (was '{old_name}'). Personality "
  423. "state was previously saved inconsistently across surfaces and "
  424. "could re-enable a personality you had turned off. "
  425. f"Run /personality {old_name} to turn it back on.")
  426. if scrubbed_text:
  427. print(
  428. " ✓ Removed personality text from agent.system_prompt (written "
  429. "by an older /personality). That field is now reserved for "
  430. "manual system prompts; personalities live in display.personality.")
  431. def _migrate_to_38(results: dict[str, Any], quiet: bool) -> None:
  432. # 37 → 38: the bundled observability/nemo_relay plugin was removed (Relay lifecycle moved
  433. # into the agent core); drop it from plugins.enabled.
  434. from hermes_cli.relay_plugin_cutover import legacy_relay_plugin_keys
  435. config = read_raw_config()
  436. plugins = config.get("plugins")
  437. if not isinstance(plugins, dict):
  438. return
  439. enabled = plugins.get("enabled")
  440. removed = legacy_relay_plugin_keys(enabled)
  441. if not removed or not isinstance(enabled, list):
  442. return
  443. plugins["enabled"] = [value for value in enabled if value not in removed]
  444. config["plugins"] = plugins
  445. _persist_migration(config)
  446. message = (
  447. "Removed legacy Relay plugin from plugins.enabled: "
  448. f"{', '.join(removed)}. Configure a standard user or system Relay plugins.toml, or use "
  449. "HERMES_NEMO_RELAY_PLUGINS_TOML for an explicit user-file override.")
  450. results["warnings"].append(message)
  451. if not quiet:
  452. print(f" ⚠ {message}")
  453. def _migrate_to_39(results: dict[str, Any], quiet: bool) -> None:
  454. # 38 → 39: strip the retired `bfl` toolset wherever a backfill/picker save wrote it, so stale
  455. # config can't resurrect an unknown toolset.
  456. config = read_raw_config()
  457. changed = False
  458. for section in ("platform_toolsets", "known_builtin_toolsets"):
  459. mapping = config.get(section)
  460. if not isinstance(mapping, dict):
  461. continue
  462. for platform, toolsets in mapping.items():
  463. if isinstance(toolsets, list) and "bfl" in toolsets:
  464. mapping[platform] = [ts for ts in toolsets if ts != "bfl"]
  465. changed = True
  466. if changed:
  467. config[section] = mapping
  468. if changed:
  469. _commit(
  470. config, results, quiet,
  471. "removed retired 'bfl' toolset from saved toolset lists",
  472. " ✓ Removed the retired BFL FLUX 3 toolset from saved toolset "
  473. "lists — video generation now lives under `hermes tools` → "
  474. "Video Generation (Nous Subscription or FAL).")
  475. def _migrate_to_41(results: dict[str, Any], quiet: bool) -> None:
  476. # 40 → 41: drop the plugin-era "## Messaging other agents" append from every SOUL.md. The
  477. # server injects the live Bot Mode section in Bot Chat sessions; the frozen SOUL copy taxed
  478. # every other session (~600 tok) and shadowed the live roster in Bot Chat itself.
  479. if not _local_files_allowed():
  480. return # SOUL.md files only, across the whole roster
  481. from hermes_constants import get_hermes_home
  482. from tools.bot_mode_probe import _PROTOCOL_HEADING, _hermes_root, _roster, strip_legacy_protocol
  483. cleaned: list[str] = []
  484. for name, profile_dir in _roster(_hermes_root(get_hermes_home())):
  485. soul = profile_dir / "SOUL.md"
  486. try:
  487. text = soul.read_text(encoding="utf-8-sig") if soul.is_file() else ""
  488. if _PROTOCOL_HEADING in text:
  489. soul.write_text(strip_legacy_protocol(text), encoding="utf-8")
  490. cleaned.append(name)
  491. except OSError:
  492. continue
  493. if cleaned:
  494. results["config_added"].append(f"removed legacy Bot Mode section from SOUL.md ({', '.join(cleaned)})")
  495. if not quiet:
  496. print(f" ✓ Removed the plugin-era 'Messaging other agents' section from SOUL.md "
  497. f"({', '.join(cleaned)}) — Bot Chat sessions now get the live roster instead.")
  498. def _migrate_to_45(results: dict[str, Any], quiet: bool) -> None:
  499. # 44 → 45: append `connections` to every saved `platform_toolsets` list that predates it
  500. # (an explicit list treats absence as unchecked). Skipped when `known_builtin_toolsets`
  501. # already records `connections` (a decline) or `agent.disabled_toolsets` names it (the
  502. # resolver subtracts that list last, so the append would have no effect).
  503. from agent.skill_utils import parse_config_string_list
  504. from hermes_cli.tools_config import _configurable_keys, _get_plugin_toolset_keys
  505. from hermes_cli.toolset_scope import toolset_allowed_for_platform
  506. config = read_raw_config()
  507. saved = config.get("platform_toolsets")
  508. if not isinstance(saved, dict):
  509. return
  510. if "connections" in parse_config_string_list(_dict_at(config, "agent").get("disabled_toolsets")):
  511. return
  512. known = _dict_at(config, "known_builtin_toolsets")
  513. # Same predicate the resolver uses to pick its explicit branch: any configurable or plugin key.
  514. explicit_keys = _configurable_keys() | _get_plugin_toolset_keys()
  515. enabled_for: list[str] = []
  516. for platform, toolsets in saved.items():
  517. if not isinstance(toolsets, list) or "connections" in toolsets:
  518. continue
  519. if not toolset_allowed_for_platform("connections", platform):
  520. continue
  521. # A composite like [hermes-cli] already inherits every core tool at read time.
  522. if not any(str(ts) in explicit_keys for ts in toolsets):
  523. continue
  524. offered = known.get(platform)
  525. if isinstance(offered, list) and "connections" in offered:
  526. continue
  527. saved[platform] = sorted({*map(str, toolsets), "connections"})
  528. if isinstance(offered, list):
  529. known[platform] = sorted({*map(str, offered), "connections"})
  530. enabled_for.append(str(platform))
  531. if not enabled_for:
  532. return
  533. config["platform_toolsets"] = saved
  534. if known:
  535. config["known_builtin_toolsets"] = known
  536. platforms = ", ".join(sorted(enabled_for))
  537. _commit(
  538. config, results, quiet,
  539. f"enabled the connections toolset for {platforms}",
  540. f" ✓ Enabled the Connections toolset (Gmail, Linear, Notion, local MCP servers) for {platforms}. "
  541. "Uncheck Connections in `hermes tools` to turn it off.")
  542. def _migrate_to_46(results: dict[str, Any], quiet: bool) -> None:
  543. # 45 → 46: the profile editor used to switch an MCP server off with `disabled: true`, a key no
  544. # runtime reader consults, so the server kept running. Carry that choice over to `enabled:
  545. # false` (the key every reader uses) and drop `disabled`, so the editor and runtime agree.
  546. # `disabled: true` wins over an explicit `enabled: true`: `hermes mcp add` writes that, and the
  547. # old editor only added `disabled`, so letting `enabled` win would skip nearly every server.
  548. from hermes_cli.tools_config import _parse_enabled_flag
  549. config = read_raw_config()
  550. servers = config.get("mcp_servers")
  551. if not isinstance(servers, dict):
  552. return
  553. legacy = {n: e for n, e in servers.items() if isinstance(e, dict) and "disabled" in e}
  554. turned_off = sorted((n for n, e in legacy.items() if _parse_enabled_flag(e["disabled"], default=False)), key=str)
  555. if not turned_off:
  556. return # a falsy `disabled` is inert; the runtime never read it
  557. for name in turned_off:
  558. del legacy[name]["disabled"]
  559. legacy[name]["enabled"] = False
  560. names = ", ".join(map(str, turned_off))
  561. _commit(
  562. config, results, quiet,
  563. f"mcp_servers: disabled → enabled: false ({names})",
  564. f" ✓ Turned off MCP servers the profile editor had marked disabled: {names}.")
  565. def _migrate_to_48(results: dict[str, Any], quiet: bool) -> None:
  566. # 47 → 48: the container sandbox default gains a display stack (nousresearch/hermes-sandbox:
  567. # desktop) so Bot Screen / computer_use / the browser run inside the sandbox. A saved value
  568. # still equal to the OLD default is the template copied, not a choice: the key is DROPPED so
  569. # the file follows the default. It is not rewritten to the new image, because a written image
  570. # is a pin and a pin recreates a persisted Docker container without asking; unpinned, the
  571. # runtime keeps an existing sandbox and the CLI / Screen pane ask first. A pinned image stays.
  572. from hermes_cli.config_defaults import DEFAULT_SANDBOX_IMAGE, LEGACY_SANDBOX_IMAGES
  573. for legacy in LEGACY_SANDBOX_IMAGES:
  574. for key, old in (
  575. ("docker_image", legacy),
  576. ("modal_image", legacy),
  577. ("daytona_image", legacy),
  578. ("singularity_image", f"docker://{legacy}"),
  579. ):
  580. _rewrite_stale_default(
  581. section="terminal", key=key, old=old, new=None,
  582. added=f"terminal.{key} unset (follows the default, {DEFAULT_SANDBOX_IMAGE})",
  583. message=f" ✓ terminal.{key}: was the old default; now follows the default sandbox image "
  584. f"({DEFAULT_SANDBOX_IMAGE})",
  585. )(results, quiet)
  586. #: Registry of (target_version, step), strictly ascending; simple default-flip steps are
  587. #: declared inline via _rewrite_stale_default / _rewrite_key partials. Later steps observe
  588. #: earlier steps' writes via read_raw_config() (filesystem state). v12 is the support floor:
  589. #: configs already AT v12 still get every step below; only configs BELOW 12 are refused by the
  590. #: floor gate in run_migrations()'s caller. Versions absent here (15, 18-20, 22, 24, 26-28, 30)
  591. #: only added a schema default that runtime merging supplies without a write. When adding a step,
  592. #: decide whether it belongs in LEGACY_KEY_STEPS below (the only steps an unversioned file gets).
  593. def _migrate_to_49(results: dict[str, Any], quiet: bool) -> None:
  594. # 48 → 49: Vercel deprecated sandbox runtimes in favour of images; the default moves from the
  595. # `node24` runtime to `vercel/sandbox/universal:latest`. A saved runtime still equal to the old
  596. # seeded default (config.yaml AND the .env mirror the setup wizard wrote) is the template copied,
  597. # not a choice, so both are dropped and fresh sandboxes follow terminal.vercel_image. A runtime
  598. # the user chose (node22, python3.13) stays and keeps overriding the image, as before. Persisted
  599. # sandboxes are unaffected either way: a snapshot restore never sends a runtime or an image.
  600. from hermes_cli.config_defaults import DEFAULT_VERCEL_IMAGE, LEGACY_VERCEL_RUNTIME
  601. _rewrite_stale_default(
  602. section="terminal", key="vercel_runtime", old=LEGACY_VERCEL_RUNTIME, new=None,
  603. added=f"terminal.vercel_runtime unset (fresh sandboxes use terminal.vercel_image, {DEFAULT_VERCEL_IMAGE})",
  604. message=f" ✓ terminal.vercel_runtime: was the old default; fresh sandboxes now use the managed image "
  605. f"({DEFAULT_VERCEL_IMAGE})",
  606. )(results, quiet)
  607. _c = _cfg()
  608. if not _local_files_allowed():
  609. return # the .env mirror is a local file
  610. if (_c.get_env_value_prefer_dotenv("TERMINAL_VERCEL_RUNTIME") or "").strip() == LEGACY_VERCEL_RUNTIME:
  611. _c.remove_env_value("TERMINAL_VERCEL_RUNTIME")
  612. if not quiet:
  613. print(" ✓ Cleared TERMINAL_VERCEL_RUNTIME from .env (was the old default; the image is used instead)")
  614. _RETIRED_TIRITH_KEYS = ("tirith_enabled", "tirith_path", "tirith_timeout", "tirith_fail_open")
  615. def _migrate_to_50(results: dict[str, Any], quiet: bool) -> None:
  616. # 49 → 50: the bundled tirith scanner left Hermes. Nothing reads its keys now, so they are
  617. # dropped; nothing replaces them.
  618. config = read_raw_config()
  619. security = config.get("security")
  620. if not isinstance(security, dict):
  621. return
  622. present = [key for key in _RETIRED_TIRITH_KEYS if key in security]
  623. if not present:
  624. return
  625. for key in present:
  626. del security[key]
  627. _commit(config, results, quiet, "removed security.tirith_* (scanner no longer bundled)",
  628. " ✓ Removed security.tirith_* — the tirith scanner is no longer bundled with Hermes.")
  629. MIGRATIONS: tuple[tuple[int, Callable[[dict[str, Any], bool], None]], ...] = (
  630. (12, _migrate_to_12),
  631. (13, _migrate_to_13),
  632. (14, _migrate_to_14),
  633. (16, _migrate_to_16),
  634. (17, _migrate_to_17),
  635. (21, _migrate_to_21),
  636. (23, _migrate_to_23),
  637. # 24 → 25: model_catalog TTL 24h → 1h (only the OLD default 24).
  638. (25, _rewrite_stale_default(
  639. section="model_catalog", key="ttl_hours", old=24, new=1,
  640. added="model_catalog.ttl_hours 24→1",
  641. message=" ✓ Lowered model_catalog.ttl_hours to 1 (hourly picker refresh)")),
  642. (29, _migrate_to_29),
  643. # 30 → 31: verify_on_stop OFF (one-time). The "auto" sentinel was more noise than signal.
  644. # Rewrite only when missing or still "auto" — an explicit user true/false is preserved.
  645. (31, functools.partial(
  646. _rewrite_key, section="agent", key="verify_on_stop", new=False, create_section=True,
  647. match=lambda cur: cur is None or _lower_is("auto")(cur),
  648. added="agent.verify_on_stop=false",
  649. message=(
  650. " ✓ Turned off verify-on-stop (agent.verify_on_stop: false). "
  651. "Set it to true to re-enable, or \"auto\" for the legacy "
  652. "surface-aware behavior."))),
  653. # 31 → 32: flip the BAKED-IN literal true to OFF (one-time). v30 defaulted verify_on_stop to a
  654. # literal True and migrate_config persisted defaults, so installs that updated through v30 have
  655. # `verify_on_stop: true` written literally — never a user choice (no off-switch existed until
  656. # v31). A true set AFTER v32 is never touched.
  657. (32, _rewrite_stale_default(
  658. section="agent", key="verify_on_stop", old=True, new=False,
  659. added="agent.verify_on_stop=false",
  660. message=(
  661. " ✓ Turned off verify-on-stop (agent.verify_on_stop: false) — "
  662. "the old default was written into your config as a literal "
  663. "true. Set it to true again to re-enable, or \"auto\" for the "
  664. "legacy surface-aware behavior."),
  665. extra_guard=lambda raw: raw.get("verify_on_stop") is True)),
  666. (33, _migrate_to_33),
  667. (34, _migrate_to_34),
  668. # 34 → 35: background_process_notifications 'all' (old implicit default, rarely chosen on
  669. # purpose) → 'concise'. Explicit result/error/off choices are preserved.
  670. (35, functools.partial(
  671. _rewrite_key, section="display", key="background_process_notifications",
  672. match=_lower_is("all"), new="concise",
  673. added="display.background_process_notifications=concise (was: all)",
  674. message=(
  675. " ✓ Background process notifications switched from 'all' to "
  676. "'concise' — completions now show a one-line status message "
  677. "instead of the raw output dump. Set "
  678. "display.background_process_notifications: all to restore "
  679. "the old behavior."))),
  680. # 35 → 36: subagent iteration cap 50 → 250 (50 truncated substantial delegated work).
  681. (36, _rewrite_stale_default(
  682. section="delegation", key="max_iterations", old=50, new=250,
  683. added="delegation.max_iterations=250 (was: 50)",
  684. message=(
  685. " ✓ Raised delegation.max_iterations from 50 to 250 — subagents "
  686. "now get a larger per-child tool-call budget so delegated work "
  687. "finishes instead of truncating. Set delegation.max_iterations "
  688. "back to 50 to restore the old cap."))),
  689. # 36 → 37: delegation concurrency 3 → 10 (stays at/below the high-cost warning threshold).
  690. (37, _rewrite_stale_default(
  691. section="delegation", key="max_concurrent_children", old=3, new=10,
  692. added="delegation.max_concurrent_children=10 (was: 3)",
  693. message=(
  694. " ✓ Raised delegation.max_concurrent_children from 3 to 10 — "
  695. "independent delegated children now fan out wider in parallel. "
  696. "Each child consumes API tokens independently; set "
  697. "delegation.max_concurrent_children back to 3 to restore the old cap."))),
  698. (38, _migrate_to_38),
  699. (39, _migrate_to_39),
  700. # 39 → 40: model_catalog.ttl_hours → ttl_minutes (default 20). Only the OLD default
  701. # (ttl_hours: 1, written by v25) is dropped; any other explicit ttl_hours is still honoured.
  702. (40, _rewrite_stale_default(
  703. section="model_catalog", key="ttl_hours", old=1, new=None,
  704. added="model_catalog.ttl_hours 1 → ttl_minutes 20 (default)",
  705. message=" ✓ Model catalog now refreshes every 20 minutes (model_catalog.ttl_minutes)",
  706. extra_guard=lambda raw: "ttl_minutes" not in raw)),
  707. (41, _migrate_to_41),
  708. # 41 → 42: cron.model_drift_guard is gone. Unpinned jobs now run on their creation snapshot
  709. # instead of failing closed when the global model changes, so the toggle has nothing to gate.
  710. (42, functools.partial(
  711. _rewrite_key, section="cron", key="model_drift_guard", new=None,
  712. match=lambda cur: cur is not None,
  713. added="removed cron.model_drift_guard",
  714. message=(
  715. " ✓ Removed cron.model_drift_guard — unpinned cron jobs now keep running on the "
  716. "model/provider they were created under when the global default changes, instead "
  717. "of being skipped. Pin a job or set cron.model to move it."))),
  718. # 42 → 43: gateway.multiplex_profile_allowlist is gone. A multiplexing default gateway serves
  719. # every live profile under profiles/; a profile that must not be served is archived or deleted.
  720. (43, functools.partial(
  721. _rewrite_key, section="gateway", key="multiplex_profile_allowlist", new=None,
  722. match=lambda _cur: True,
  723. added="removed gateway.multiplex_profile_allowlist",
  724. message=(
  725. " ✓ Removed gateway.multiplex_profile_allowlist — the multiplexing gateway now serves "
  726. "every profile under profiles/. Delete or archive a profile you do not want served."),
  727. extra_guard=lambda raw: "multiplex_profile_allowlist" in raw)),
  728. # 43 → 44: curator prunes faster — stale 30→14 days, archive 90→30 days. A skill nobody has
  729. # touched in a month is prompt weight, not knowledge; archival is recoverable. Only the OLD
  730. # defaults are rewritten; an explicit user value is preserved.
  731. (44, _rewrite_stale_default(
  732. section="curator", key="stale_after_days", old=30, new=14,
  733. added="curator.stale_after_days=14 (was: 30)",
  734. message=" ✓ curator.stale_after_days 30→14 — unused skills are flagged stale after two weeks.")),
  735. (44, _rewrite_stale_default(
  736. section="curator", key="archive_after_days", old=90, new=30,
  737. added="curator.archive_after_days=30 (was: 90)",
  738. message=(
  739. " ✓ curator.archive_after_days 90→30 — skills unused for a month are archived to "
  740. "skills/.archive/ (recoverable with `hermes curator restore`). Set it back to 90 to keep the old window."))),
  741. # 44 → 45: saved platform_toolsets lists predate the connections toolset (see _migrate_to_45).
  742. (45, _migrate_to_45),
  743. # 45 → 46: legacy editor `disabled: true` on MCP servers becomes `enabled: false` (see _migrate_to_46).
  744. (46, _migrate_to_46),
  745. # 46 → 47: compression.threshold_tokens defaults back to null (ratio-only). The briefly shipped
  746. # 256000 default was copied into config.yaml by the template seeder and `doctor --fix`, where it
  747. # reads as a user choice and keeps capping 1M-window models at 256K. Drop only that exact value;
  748. # any other explicit cap, and an explicit null, are preserved.
  749. (47, _rewrite_stale_default(
  750. section="compression", key="threshold_tokens", old=256000, new=None,
  751. added="removed compression.threshold_tokens: 256000 (the old default)",
  752. message=(
  753. " ✓ Removed compression.threshold_tokens: 256000 — the old default. Compaction "
  754. "follows compression.threshold (50% of the window) again. Set threshold_tokens "
  755. "to a token count to cap it on purpose."))),
  756. # 47 → 48: a saved old-default sandbox image is dropped so the file follows the new default (see _migrate_to_48).
  757. (48, _migrate_to_48),
  758. # 48 → 49: the seeded Vercel runtime pin is dropped so fresh sandboxes use the managed image (see _migrate_to_49).
  759. (49, _migrate_to_49),
  760. # 49 → 50: security.tirith_* dropped; the bundled scanner is gone (see _migrate_to_50).
  761. (50, _migrate_to_50),
  762. # 50 → 51: cron.bot_chat_delivery_timeout_seconds is gone with the local `hermes chat`
  763. # fallback lane it bounded. Bot Chat deliveries are admitted to the running gateway and
  764. # settle on its durable receipt; there is no cron-side turn left to time out.
  765. (51, functools.partial(
  766. _rewrite_key, section="cron", key="bot_chat_delivery_timeout_seconds", new=None,
  767. match=lambda _cur: True,
  768. added="removed cron.bot_chat_delivery_timeout_seconds",
  769. message=(
  770. " ✓ Removed cron.bot_chat_delivery_timeout_seconds — bot-chat deliveries are now "
  771. "admitted to the target profile's running gateway and tracked by receipt, so cron no "
  772. "longer runs (or times out) a Bot Chat turn of its own."),
  773. extra_guard=lambda raw: "bot_chat_delivery_timeout_seconds" in raw)),
  774. # 51 -> 52: browser.backend + browser.extension_control dropped, AGENT_BROWSER_* .env settings ->
  775. # browser.* (see config_migrations_browser.migrate_to_52).
  776. (52, migrate_to_52),
  777. )
  778. #: Steps triggered by a legacy key or identifier (a renamed or retired key, a removed plugin or
  779. #: toolset, the plugin-era SOUL.md section): they carry its setting to where the runtime reads it
  780. #: or drop what nothing reads, which is right however old the file is. A config.yaml with no
  781. #: ``_config_version`` is current-schema content that was never stamped (installers seed it from
  782. #: cli-config.yaml.example; targeted writers never stamp), so it gets only these: every other step
  783. #: decides by a value or an absence that, in such a file, is the user's own choice. v13 is left
  784. #: out: it clears OPENAI_MODEL from .env, a generic name Hermes never reads but the user's tools may.
  785. #: v41 is left out too: it rewrites profile SOUL.md on a heading match, an artifact whose
  786. #: provenance the config stamp says nothing about.
  787. LEGACY_KEY_STEPS = frozenset({12, 14, 16, 17, 29, 33, 38, 39, 42, 43, 46, 50, 51, 52})
  788. #: Legacy-key steps that run on every migration pass whatever the stamp says, because a stamp at
  789. #: or past their version does not prove they ran: unreleased builds of the gateway-runtime branch
  790. #: put their retired-cron-key step at 44, 45, 46, 47 and 50 before it landed at 51, so a home one
  791. #: of them stamped skipped main's step of that number. Only a step triggered by a key NO runtime
  792. #: reads qualifies (re-running it is a no-op once the key is gone, and it never overrides a value
  793. #: something consumes). The value-based steps such a home also skipped (44 curator defaults, 45
  794. #: connections, 47 threshold_tokens) are NOT re-run: past the stamp, their trigger value may be
  795. #: the user's own choice.
  796. STAMP_INDEPENDENT_STEPS = frozenset({46, 50})
  797. def run_migrations(
  798. current_ver: int, results: dict[str, Any], quiet: bool, *, unversioned: bool = False,
  799. config_only: bool = False) -> None:
  800. """Apply every registered migration whose target version exceeds *current_ver* (plus
  801. :data:`STAMP_INDEPENDENT_STEPS`); a config with no ``_config_version`` (*unversioned*) gets
  802. only :data:`LEGACY_KEY_STEPS`.
  803. *current_ver* is the on-disk schema version captured ONCE before any step runs and does not
  804. advance between steps — each step is gated on the same initial value.
  805. *config_only* transforms the config document alone (see :data:`_CONFIG_ONLY`).
  806. """
  807. token = _CONFIG_ONLY.set(config_only)
  808. try:
  809. for target_ver, migration_fn in MIGRATIONS:
  810. due = current_ver < target_ver or target_ver in STAMP_INDEPENDENT_STEPS
  811. if due and (target_ver in LEGACY_KEY_STEPS or not unversioned):
  812. try:
  813. migration_fn(results, quiet)
  814. except Exception as exc:
  815. # A malformed nested value in one step must not abort the rest of the
  816. # ladder (config loading itself fails otherwise). Loud, not silent.
  817. warning = f"config migration to v{target_ver} failed and was skipped: {exc}"
  818. results.setdefault("warnings", []).append(warning)
  819. # Quiet callers (profile creation, unattended update) discard ``results`` and
  820. # migrate_config still stamps the latest version, so without a log line the
  821. # skipped step vanishes for good.
  822. logger.warning("%s", warning)
  823. if not quiet:
  824. print(f" ⚠ {warning}")
  825. finally:
  826. _CONFIG_ONLY.reset(token)