left_core_migration.py 66 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194
  1. """Move a home onto the catalog plugin of a feature that left core.
  2. A feature (gateway platform, toolset, bundled plugin) that moves from core into a standalone catalog
  3. plugin keeps its names, config keys and env vars, so migrating is only "install the plugin". Each row of
  4. :data:`LEFT_CORE` names the catalog plugin and a read-only predicate "does this home use it". The
  5. contract is the one memory providers established (``memory_provider_migration``, whose helpers this
  6. reuses; memory is not a row because its plugin name comes from ``memory.provider``, not a table):
  7. * ``hermes update`` installs the plugin for every profile home sharing the venv that uses the feature.
  8. * Agent start and gateway start retry once per process for the active home (Desktop users update
  9. through the app and never run ``hermes update``), honouring ``security.allow_lazy_installs``.
  10. * After a failed attempt (catalog miss or unreachable, failed install) starts skip the row for
  11. an hour, doubling with each further failure up to a week, so an offline
  12. machine pays the network round trip once, not on every ``hermes chat``, and a home whose install
  13. cannot succeed stops failing every hour; ``hermes update`` always retries.
  14. * A home gets the plugin automatically at most once (``_left_core_installed`` in its config.yaml):
  15. ``hermes plugins remove`` afterwards is the user's choice and sticks.
  16. Installs go through the normal catalog install path at the reviewed pin (kill list, dependency
  17. constraints, enable). Unattended dependency consent covers only these rows: the feature shipped in
  18. core, so its users already accepted its dependencies. Agent/gateway start always installs with it
  19. (nothing can answer a prompt there); ``hermes update`` in a terminal still asks. Every outcome
  20. reaches the user (terminal, Desktop, chat); an outcome no terminal shows waits in the home for its next
  21. turn someone sees (:func:`claim_kept_notices`).
  22. """
  23. from __future__ import annotations
  24. import logging
  25. import os
  26. import sys
  27. from contextlib import contextmanager
  28. from contextvars import ContextVar
  29. from dataclasses import dataclass
  30. from pathlib import Path
  31. from typing import Callable, Optional
  32. from hermes_cli.memory_provider_migration import (
  33. _failed_recently, _home_consent, _home_label, _install_command, _interactive,
  34. _note_failure, _unattended_consent,
  35. )
  36. logger = logging.getLogger(__name__)
  37. # ``terminal.*`` keys a left-core plugin still reads -> the ``.env`` copy core's ``hermes config set`` also
  38. # wrote. Not in DEFAULT_CONFIG (a seeded default would hide the plugin's env fallback), so ``config
  39. # set/get`` recognise them here, and ``config unset`` removes that copy too: the plugin falls back to it,
  40. # and the old value would return instead of the default.
  41. LEFT_CORE_TERMINAL_KEYS = {"terminal.singularity_image": "TERMINAL_SINGULARITY_IMAGE"}
  42. def _read_config(home: Path) -> dict:
  43. from hermes_cli.config_backend import read_config_doc
  44. try:
  45. data = read_config_doc(home / "config.yaml")
  46. except Exception: # missing/unreadable/invalid YAML: nothing we can see is in use
  47. return {}
  48. return data if isinstance(data, dict) else {}
  49. def platform_configured_on(home: Path, name: str) -> bool:
  50. """Platform *name* is on in *home*'s config files as the gateway loader reads them: legacy
  51. ``gateway.json`` base layer, then config.yaml's ``gateway.platforms`` / ``platforms`` /
  52. ``gateway.<name>`` blocks merged in the loader's order (managed overlay and ``${VAR}`` applied),
  53. so the last explicit ``enabled`` wins. A stored token with no ``enabled`` anywhere counts too.
  54. Env credentials are the caller's to check. Read-only; works before the platform's plugin loads."""
  55. from gateway import config_loader
  56. from gateway.config import PlatformConfig
  57. gw_data = config_loader.load_legacy_gateway_json(home)
  58. gw_data = gw_data if isinstance(gw_data, dict) else {}
  59. try:
  60. yaml_cfg = config_loader.read_yaml_layers(home)
  61. except Exception: # malformed config.yaml: the gateway falls back to gateway.json alone too
  62. yaml_cfg = {}
  63. yaml_cfg = yaml_cfg if isinstance(yaml_cfg, dict) else {}
  64. block = config_loader.merge_platform_sections(
  65. yaml_cfg, yaml_cfg.get("gateway"), gw_data, also=frozenset({name})).get(name)
  66. if not isinstance(block, dict):
  67. return False
  68. platform = PlatformConfig.from_dict(block)
  69. return platform.enabled or ("enabled" not in block and bool(str(platform.token or "").strip()))
  70. def _toolset_listed(config: dict, names: frozenset[str], *, own_platform: str = "") -> bool:
  71. """A toolset in *names* is selected in ``platform_toolsets`` or the top-level ``toolsets`` list.
  72. *own_platform*'s row is skipped: it scopes that platform's own sessions, which only exist once the
  73. platform is on (:func:`platform_configured_on`). The installers copy cli-config.yaml.example into
  74. config.yaml, and it carried ``homeassistant: [hermes-homeassistant]`` until Home Assistant left core,
  75. so that row alone is not use."""
  76. rows = config.get("platform_toolsets")
  77. selections = [sel for platform, sel in rows.items() if platform != own_platform] if isinstance(rows, dict) else []
  78. selections.append(config.get("toolsets"))
  79. return any(isinstance(sel, list) and any(str(item) in names for item in sel) for sel in selections)
  80. def homeassistant_in_use(home: Path, *, process_env: bool = False) -> bool:
  81. """What made core run Home Assistant for *home*: ``HASS_TOKEN`` in its ``.env`` (it enabled both
  82. the gateway platform and the tools), the platform on in its gateway config
  83. (:func:`platform_configured_on`), or the ``homeassistant`` / ``hermes-homeassistant`` toolset selected for
  84. another platform or in the top-level ``toolsets`` list. *process_env* (the active home at startup only)
  85. also counts a ``HASS_TOKEN`` the process received from its environment (systemd unit, Docker, shell export)."""
  86. from agent.secret_scope import load_env_file
  87. if (load_env_file(home / ".env").get("HASS_TOKEN") or "").strip():
  88. return True
  89. if process_env:
  90. try:
  91. from agent.secret_scope import get_secret
  92. if (get_secret("HASS_TOKEN", "") or "").strip():
  93. return True
  94. except Exception:
  95. pass
  96. if platform_configured_on(home, "homeassistant"):
  97. return True
  98. return _toolset_listed(
  99. _read_config(home), frozenset({"homeassistant", "hermes-homeassistant"}), own_platform="homeassistant")
  100. def _auth_store(home: Path) -> dict:
  101. """*home*'s ``auth.json``; ``{}`` when missing, unreadable or invalid (no login we can see)."""
  102. import json
  103. try:
  104. store = json.loads((home / "auth.json").read_text(encoding="utf-8-sig"))
  105. except (OSError, ValueError):
  106. return {}
  107. return store if isinstance(store, dict) else {}
  108. def spotify_in_use(home: Path, *, process_env: bool = False) -> bool:
  109. """What made core's Spotify tools usable for *home*: a login stored in its ``auth.json``
  110. (``providers.spotify``, written by ``hermes auth spotify``) or the ``spotify`` toolset selected
  111. for a platform. The tools were opt-in and login-gated, so a client id alone is not use."""
  112. providers = _auth_store(home).get("providers")
  113. state = providers.get("spotify") if isinstance(providers, dict) else None
  114. if isinstance(state, dict) and (state.get("access_token") or state.get("refresh_token")):
  115. return True
  116. return _toolset_listed(_read_config(home), frozenset({"spotify"}))
  117. def _plugin_lists(home: Path, plugin: str) -> tuple[bool, bool]:
  118. """Whether *plugin*'s key or name is in *home*'s ``plugins.enabled`` / ``plugins.disabled``, read with the
  119. managed overlay applied like the loader's config, so an administrator's pinned list counts."""
  120. from gateway import config_loader
  121. feature = next(f for f in LEFT_CORE if f.plugin == plugin)
  122. try:
  123. plugins = config_loader.read_yaml_layers(home).get("plugins")
  124. except Exception: # malformed config.yaml: the loader enables nothing from it either
  125. logger.debug("left-core: unreadable config for %s", home, exc_info=True)
  126. return False, False
  127. plugins = plugins if isinstance(plugins, dict) else {}
  128. def listed(key: str) -> bool:
  129. names = plugins.get(key)
  130. return isinstance(names, list) and any(str(n) in (feature.plugin_key, feature.plugin) for n in names)
  131. return listed("enabled"), listed("disabled")
  132. def _bundled_plugin_selected(home: Path, plugin: str) -> bool:
  133. """*plugin*'s bundled copy was on for *home*: in ``plugins.enabled`` and not in ``plugins.disabled``
  134. (which wins, as in the loader)."""
  135. enabled, disabled = _plugin_lists(home, plugin)
  136. return enabled and not disabled
  137. def langfuse_in_use(home: Path, *, process_env: bool = False) -> bool:
  138. """What made core trace to Langfuse for *home*: the bundled ``observability/langfuse`` selected
  139. (:func:`_bundled_plugin_selected`). The plugin was opt-in, so keys in ``.env`` alone are not use."""
  140. return _bundled_plugin_selected(home, "langfuse")
  141. def singularity_in_use(home: Path, *, process_env: bool = False) -> bool:
  142. """What made core run its Singularity backend for *home*: ``terminal.backend`` (or the legacy
  143. ``terminal.env_type``) set to ``singularity`` in its config (managed overlay applied, as the bridge
  144. reads it), else ``TERMINAL_ENV=singularity`` from its dotenv layers as ``load_hermes_dotenv`` resolves
  145. them (the home's ``.env``, then the administrator-managed ``.env`` with override, ``${VAR}``
  146. references expanded: :func:`~hermes_cli.env_loader.resolve_home_dotenv`). config.yaml wins over
  147. both, as in the bridge. *process_env* (startup) also counts a ``TERMINAL_ENV`` the process received
  148. from its environment (systemd unit, Docker, shell export), for the launch home only: ``TERMINAL_*``
  149. is process-global (``get_secret`` never scopes it), so for any other served home it is the launch
  150. profile's backend, not this one's."""
  151. from gateway import config_loader
  152. try:
  153. terminal = config_loader.read_yaml_layers(home).get("terminal")
  154. except Exception: # malformed config.yaml: the bridge reads nothing from it either
  155. logger.debug("left-core: unreadable config for %s", home, exc_info=True)
  156. terminal = None
  157. terminal = terminal if isinstance(terminal, dict) else {}
  158. configured = str(terminal.get("backend") or terminal.get("env_type") or "").strip()
  159. if not configured:
  160. from hermes_cli.env_loader import resolve_home_dotenv
  161. configured = resolve_home_dotenv(home).get("TERMINAL_ENV", "").strip()
  162. if not configured and process_env:
  163. from hermes_constants import get_routing_process_hermes_home, hermes_home_key
  164. if hermes_home_key(home) == hermes_home_key(get_routing_process_hermes_home()):
  165. configured = os.environ.get("TERMINAL_ENV", "").strip()
  166. return configured.lower() == "singularity"
  167. def agent_imports_in_use(home: Path, *, process_env: bool = False) -> bool:
  168. """*home* registered a ``hermes import-agent`` source for ``--sync`` (its ``import-sync.json``,
  169. which scheduled syncs read). A one-shot import leaves no other trace, and installing the plugin
  170. for every home would add a command nobody asked for; the old spelling names the install."""
  171. return (home / "import-sync.json").is_file()
  172. def _home_env(home: Path, name: str, *, process_env: bool) -> str:
  173. """*name* as *home*'s dotenv layers resolve it (:func:`~hermes_cli.env_loader.resolve_home_dotenv`),
  174. else, with *process_env* and for the launch home only, the process environment."""
  175. from hermes_cli.env_loader import resolve_home_dotenv
  176. value = resolve_home_dotenv(home).get(name, "").strip()
  177. if not value and process_env:
  178. from hermes_constants import get_routing_process_hermes_home, hermes_home_key
  179. if hermes_home_key(home) == hermes_home_key(get_routing_process_hermes_home()):
  180. value = os.environ.get(name, "").strip()
  181. return value
  182. def camofox_in_use(home: Path, *, process_env: bool = False) -> bool:
  183. """What made core run its Camofox backend for *home*, read the way core selected it
  184. (``tools/browser_camofox.is_camofox_mode``): a CDP endpoint (``browser.cdp_url`` or
  185. ``BROWSER_CDP_URL``) won over Camofox; a stored selection (``browser.cloud_provider``, or
  186. ``use_gateway`` = the managed row) decided alone, Camofox only when it names ``camofox``; with
  187. none stored, ``CAMOFOX_URL`` in its dotenv layers (the process env too for the launch home with
  188. *process_env*). ``browser.camofox`` settings never selected it: a leftover block without an
  189. address ran browser_exec. Config is the raw config.yaml, as core read it; read-only."""
  190. from utils import is_truthy_value
  191. browser = _read_config(home).get("browser")
  192. browser = browser if isinstance(browser, dict) else {}
  193. if str(browser.get("cdp_url") or "").strip() or _home_env(home, "BROWSER_CDP_URL", process_env=process_env):
  194. return False
  195. if is_truthy_value(browser.get("use_gateway")):
  196. return False
  197. provider = browser.get("cloud_provider")
  198. selected = str(provider).strip().lower() if provider is not None else ""
  199. if selected:
  200. return selected == "camofox"
  201. return bool(_home_env(home, "CAMOFOX_URL", process_env=process_env))
  202. def _route_slots(home: Path) -> list[dict]:
  203. """Every inference route *home* configures, read with core's own loaders: config.yaml with the managed
  204. overlay (``read_yaml_layers``): ``model``, the fallback chain (``get_fallback_chain``: legacy
  205. ``fallback_model`` merged), each ``auxiliary.<task>``, ``delegation`` and its fallback chain, every
  206. delegation backend route (:func:`_delegation_backend_routes`) and its chain, every MoA preset's reference
  207. models and aggregator (``normalize_moa_config``), the cron-wide ``cron.model_provider``, each cron job's pin
  208. and the user's own ``providers:`` / ``custom_providers:`` endpoints (``get_compatible_custom_providers``)."""
  209. from cron.scheduler_preflight import cron_default_provider
  210. from gateway import config_loader
  211. from hermes_cli.config_providers import get_compatible_custom_providers
  212. from hermes_cli.fallback_config import get_fallback_chain
  213. from hermes_cli.moa_config import normalize_moa_config
  214. try:
  215. cfg = config_loader.read_yaml_layers(home)
  216. except Exception: # malformed config.yaml: the agent reads nothing from it either
  217. logger.debug("left-core: unreadable config for %s", home, exc_info=True)
  218. cfg = {}
  219. cfg = cfg if isinstance(cfg, dict) else {}
  220. def block(value) -> dict:
  221. return value if isinstance(value, dict) else {}
  222. def with_chain(slot: dict) -> list[dict]:
  223. return [slot, *get_fallback_chain({"fallback_providers": slot.get("fallback_providers")})]
  224. delegation = block(cfg.get("delegation"))
  225. slots = [block(cfg.get("model")), *get_fallback_chain(cfg), *map(block, block(cfg.get("auxiliary")).values()),
  226. *with_chain(delegation), {"provider": cron_default_provider(cfg)}]
  227. for preset in normalize_moa_config(cfg.get("moa"))["presets"].values():
  228. slots += [*map(block, preset.get("reference_models") or []), block(preset.get("aggregator"))]
  229. for route in _delegation_backend_routes(delegation):
  230. slots += with_chain(route)
  231. slots += [{"base_url": entry.get("base_url")} for entry in get_compatible_custom_providers(cfg)]
  232. import json
  233. try:
  234. jobs = json.loads((home / "cron" / "jobs.json").read_text(encoding="utf-8-sig")).get("jobs")
  235. except (OSError, ValueError, AttributeError): # no (readable) job store: no pins
  236. jobs = None
  237. return slots + ([block(job) for job in jobs] if isinstance(jobs, list) else [])
  238. def _provider_choices(home: Path) -> set[str]:
  239. """Every provider *home* routes inference through (:func:`_route_slots`), plus the ``auth.json``
  240. ``active_provider`` the resolver's auto rung follows."""
  241. chosen = {str(slot.get("provider") or "").strip().lower() for slot in _route_slots(home)}
  242. chosen.add(str(_auth_store(home).get("active_provider") or "").strip().lower())
  243. return chosen - {""}
  244. def routes_at_hosts(home: Path, hosts: tuple[str, ...]) -> bool:
  245. """A route *home* configures (:func:`_route_slots`) has its ``base_url`` at one of *hosts* (the host or
  246. a subdomain), whatever provider name it goes by (``custom``, a named endpoint)."""
  247. urls = {str(slot.get("base_url") or "").strip() for slot in _route_slots(home)} - {""} if hosts else set()
  248. return any(_at_host(url, host) for url in urls for host in hosts)
  249. def _at_host(url: str, host: str) -> bool:
  250. """*url* is at *host* or a subdomain. A URL ``urlparse`` rejects (an unclosed IPv6 bracket) is at no host:
  251. that route fails on its own, and one bad slot must not abort the home's other migrations."""
  252. from utils import base_url_host_matches
  253. try:
  254. return base_url_host_matches(url, host)
  255. except ValueError:
  256. return False
  257. def _delegation_backend_routes(delegation: dict) -> list[dict]:
  258. """The routes of every ``delegation.backends.<name>`` block: each entry of its ``options`` list (the
  259. ``model_map`` backend's titled provider/model routes, the shape ``web_routers/delegation.py`` writes).
  260. While a backend is active, these are the only routes delegated children take. The backends are
  261. plugins, so no core loader reads them; any backend using the ``options`` shape counts."""
  262. backends = delegation.get("backends")
  263. blocks = [b for b in backends.values() if isinstance(b, dict)] if isinstance(backends, dict) else []
  264. return [o for b in blocks if isinstance(b.get("options"), list) for o in b["options"] if isinstance(o, dict)]
  265. def providers_selected(home: Path, names: tuple[str, ...], *, process_env: bool = False) -> set[str]:
  266. """The provider *names* (ids or aliases) *home* routes inference through (:func:`_provider_choices`),
  267. or names in its ``HERMES_INFERENCE_PROVIDER`` (dotenv layers; the process env too for the launch home
  268. with *process_env*). A credential alone is not a choice: core never routed to a provider for a key, and
  269. a name that is the user's own custom endpoint (``custom_providers: [{name: github, ...}]``) is not one."""
  270. chosen = _provider_choices(home) | {_home_env(home, "HERMES_INFERENCE_PROVIDER", process_env=process_env).lower()}
  271. chosen &= {name.lower() for name in names}
  272. return {name for name in chosen if not _names_custom_endpoint(home, name)} if chosen else chosen
  273. def _names_custom_endpoint(home: Path, name: str) -> bool:
  274. """*name* resolves to one of *home*'s own ``providers:`` / ``custom_providers:`` endpoints (the
  275. resolver's named-custom rung: ``named_custom_provider_config_path``), not to the provider it aliases."""
  276. from gateway import config_loader
  277. from hermes_cli.runtime_provider_custom import named_custom_provider_config_path
  278. try:
  279. return named_custom_provider_config_path(name, config_loader.read_yaml_layers(home)) is not None
  280. except Exception: # malformed config.yaml: the resolver finds no custom entry in it either
  281. logger.debug("left-core: unreadable config for %s", home, exc_info=True)
  282. return False
  283. # GitHub Copilot: the API provider and the Copilot CLI over ACP, ids and every alias their profiles declared.
  284. _COPILOT_API = ("copilot", "github-copilot", "github-models", "github-model", "github")
  285. _COPILOT_ACP = ("copilot-acp", "github-copilot-acp", "copilot-acp-agent")
  286. def copilot_in_use(home: Path, *, process_env: bool = False) -> bool:
  287. """Core routed inference through GitHub Copilot for *home*: ``copilot`` or ``copilot-acp`` (any alias)
  288. is a provider it chose (:func:`providers_selected`). A GH_TOKEN in ``.env`` alone is not use."""
  289. return bool(providers_selected(home, _COPILOT_API + _COPILOT_ACP, process_env=process_env))
  290. def copilot_relogin_notice(home: Path, *, process_env: bool = False) -> str:
  291. """The Copilot API provider is in use in *home* with no token the plugin reads: no
  292. COPILOT_GITHUB_TOKEN / GH_TOKEN / GITHUB_TOKEN in its dotenv layers (process env too for the launch home
  293. with *process_env*) and no Hermes login in its ``auth.json`` (a ``manual`` credential-pool row from
  294. ``hermes auth add copilot``, or ``providers.copilot``). Core also took ``gh auth token`` and the
  295. GitHub/Copilot CLI's token files, which the plugin does not; read-only, never runs ``gh``."""
  296. if not providers_selected(home, _COPILOT_API, process_env=process_env):
  297. return ""
  298. if any(_home_env(home, name, process_env=process_env)
  299. for name in ("COPILOT_GITHUB_TOKEN", "GH_TOKEN", "GITHUB_TOKEN")):
  300. return ""
  301. store = _auth_store(home)
  302. pool = store.get("credential_pool")
  303. rows = pool.get("copilot") if isinstance(pool, dict) else None
  304. if isinstance(rows, list) and any(
  305. isinstance(row, dict) and str(row.get("source") or "").split(":", 1)[0] == "manual" for row in rows):
  306. return ""
  307. providers = store.get("providers")
  308. if isinstance(providers, dict) and isinstance(providers.get("copilot"), dict) and providers["copilot"]:
  309. return ""
  310. return ("This profile's Copilot login came from `gh auth token` or the GitHub/Copilot CLI, which the plugin "
  311. "no longer reads: run `hermes auth add copilot` to sign in.")
  312. def _no_notice(home: Path, *, process_env: bool = False) -> str:
  313. return ""
  314. @dataclass(frozen=True)
  315. class LeftCoreFeature:
  316. plugin: str # catalog entry name == installed plugin name
  317. label: str # user-facing feature name
  318. in_use: Callable[..., bool] # (home, *, process_env=False) -> bool, read-only
  319. unchanged: str # what migrated users keep, shown on success
  320. # Credentials core stripped from every child process while it shipped the feature. Core keeps
  321. # stripping them (tools/environments/local_env_policy.py): with the plugin absent (migration
  322. # pending, declined or failed) no manifest declares them, and they would reach every child.
  323. secret_env: tuple[str, ...] = ()
  324. # Non-secret settings core kept out of children by default (provider blocklist, Tier 2).
  325. private_env: tuple[str, ...] = ()
  326. # Toolsets the plugin registers. Core resolved them like any built-in toolset (on only where the
  327. # platform's saved list or default composite carried them); a plugin toolset is on for every
  328. # platform whose known_plugin_toolsets does not name it, so :func:`_record_migration` records
  329. # them there wherever core had them off.
  330. toolsets: tuple[str, ...] = ()
  331. # Platforms whose core default composite (``hermes-<platform>``) never carried those toolsets.
  332. off_platforms: tuple[str, ...] = ()
  333. # Core-era toolsets the plugin's toolsets replace while core keeps the name for something else
  334. # (core's ``browser`` is browser_exec now; Camofox's tools live in the plugin's ``camofox``). The
  335. # one-time scope conversion treats them as the plugin's toolsets for "did core carry it" and turns
  336. # them off in the home: a saved platform list naming one names the plugin's toolsets instead, and
  337. # ``agent.disabled_toolsets`` takes them for platforms on a default composite.
  338. replaces_toolsets: tuple[str, ...] = ()
  339. # Gateway platform the plugin ships: a running gateway serves it only after a restart.
  340. platform: str = ""
  341. # Channel ownership core declared for that platform, kept while the plugin is absent (migration
  342. # pending, declined, failed) so a channel-less profile clone still strips the source's identity
  343. # (hermes_cli/profile_channels.py): the env whose presence enabled the adapter, and the env
  344. # prefixes it shared with the feature's tools (stripped only when the source runs the adapter).
  345. enable_env: tuple[str, ...] = ()
  346. channel_env_prefixes: tuple[str, ...] = ()
  347. # Top-level command the plugin registers in place of core's ``hermes auth <cli>`` login
  348. # (``hermes <cli> login|status|logout``); :func:`moved_command_hint` points the old spelling at it.
  349. cli: str = ""
  350. # Top-level command the plugin registers: core's own command kept under its name (``hermes
  351. # import-agent``), or in place of core's nested ``old_command`` (``hermes mcp serve`` -> ``hermes
  352. # mcp-serve``); :func:`moved_command_hint` points the old spelling at it.
  353. command: str = ""
  354. old_command: str = ""
  355. # Other top-level commands core shipped that the same plugin now registers (``hermes claw``, the
  356. # OpenClaw migration's spelling before ``hermes import-agent openclaw``); hinted like *command*.
  357. old_cli: tuple[str, ...] = ()
  358. # Key of the bundled plugin core shipped (``observability/langfuse``). It stays an alias of the
  359. # catalog plugin in ``plugins.enabled`` / ``plugins.disabled`` (the loader's gate, an
  360. # administrator's pinned list) and for every `hermes plugins <verb>` (:func:`legacy_plugin_alias`).
  361. plugin_key: str = ""
  362. # ``terminal.backend`` value the plugin registers: unknown-backend errors name the install command.
  363. terminal_backend: str = ""
  364. # Config schema version that shipped without the feature, for a row whose conversion changes what a
  365. # home runs (``replaces_toolsets``): only a home from before it ran the core feature, so the row fires
  366. # only while the home's config is below it or when that version's config step found the feature in
  367. # use (:func:`record_core_use`). A newer home that sets the plugin up itself keeps core's toolsets.
  368. left_at: int = 0
  369. # Provider ids and aliases the plugin's model-provider profiles register. A name nothing resolves to
  370. # gets :func:`provider_install_hint` appended to its "unknown provider" error, runtime resolution
  371. # installs the plugin first for a home that uses it (:func:`recover_for_provider`), and those names
  372. # never resolve through another rung (the models.dev catalog) while the plugin is not loaded.
  373. providers: tuple[str, ...] = ()
  374. # Env names the plugin's providers read that core kept profile-managed: scrubbed when inherited but
  375. # absent from the profile's .env (env_loader._PROFILE_MANAGED_ENV_KEYS) and routed to .env by `hermes
  376. # config set` (config._EXTRA_ENV_KEYS). Read statically: env_loader runs before provider discovery.
  377. profile_env: tuple[str, ...] = ()
  378. # The subset of those names that choose an executable or its argv: the generic env writers refuse them
  379. # on every home (:func:`launch_env_names`), as core did. A loaded plugin's profile declares them itself;
  380. # a home whose plugin is absent, disabled, failed to load or quarantined would otherwise accept a value
  381. # that runs as the provider's binary once the plugin loads.
  382. launch_env: tuple[str, ...] = ()
  383. # Hosts the plugin's providers serve (a host covers its subdomains). Core attached their wire quirks by
  384. # host for any provider name, so a home with a route at one (a ``custom`` endpoint included) uses the
  385. # feature (:func:`feature_in_use`), and a request rejected there names the install
  386. # (:func:`host_install_hint`).
  387. hosts: tuple[str, ...] = ()
  388. # (home, *, process_env=False) -> str: one more sentence for every migration outcome in *home* (a
  389. # credential source core read that the plugin does not, and the command that replaces it), "" = none.
  390. notice: Callable[..., str] = _no_notice
  391. LEFT_CORE: tuple[LeftCoreFeature, ...] = (
  392. LeftCoreFeature(
  393. plugin="homeassistant", label="Home Assistant", in_use=homeassistant_in_use,
  394. unchanged="HASS_TOKEN/HASS_URL, platforms.homeassistant and the ha_* tool names are unchanged",
  395. secret_env=("HASS_TOKEN",), private_env=("HASS_URL",),
  396. toolsets=("homeassistant",), off_platforms=("acp", "webhook"), platform="homeassistant",
  397. enable_env=("HASS_TOKEN",), channel_env_prefixes=("HASS_",),
  398. ),
  399. LeftCoreFeature(
  400. plugin="spotify", label="Spotify", in_use=spotify_in_use,
  401. unchanged="your Spotify login, the spotify toolset and the spotify_* tools are unchanged; "
  402. "`hermes auth spotify` is now `hermes spotify login`",
  403. cli="spotify",
  404. ),
  405. LeftCoreFeature(
  406. plugin="langfuse", label="Langfuse", in_use=langfuse_in_use,
  407. unchanged="your Langfuse keys and HERMES_LANGFUSE_* settings are unchanged; the plugin is now "
  408. "`langfuse` (was observability/langfuse)",
  409. secret_env=("HERMES_LANGFUSE_SECRET_KEY",),
  410. private_env=("HERMES_LANGFUSE_PUBLIC_KEY", "HERMES_LANGFUSE_BASE_URL"),
  411. plugin_key="observability/langfuse",
  412. ),
  413. LeftCoreFeature(
  414. # MCP clients that launch `hermes mcp serve` are configured outside Hermes, so no home shows the
  415. # feature in use: nothing installs automatically, and the old spelling prints where it went.
  416. plugin="mcp-serve", label="Hermes as an MCP server", in_use=lambda home, **_: False,
  417. unchanged="the conversation tools keep their names; MCP clients change their args to [\"mcp-serve\"]",
  418. command="mcp-serve", old_command="hermes mcp serve",
  419. ),
  420. LeftCoreFeature(
  421. # CAMOFOX_URL is an address, not a credential: core kept it out of children only through its
  422. # `category: tool` OPTIONAL_ENV_VARS entry (the Tier 2 provider blocklist), as HASS_URL. The
  423. # bearer token is a credential.
  424. plugin="camofox", label="Camofox browser backend", in_use=camofox_in_use,
  425. unchanged="CAMOFOX_URL, the browser.camofox settings and the browser_navigate/browser_click/... tool "
  426. "names are unchanged; they are the `camofox` toolset now, and core's `browser` toolset "
  427. "(browser_exec) is turned off in this profile",
  428. secret_env=("CAMOFOX_API_KEY",), private_env=("CAMOFOX_URL",),
  429. toolsets=("camofox",), off_platforms=("webhook",), replaces_toolsets=("browser",), left_at=52,
  430. ),
  431. LeftCoreFeature(
  432. plugin="singularity", label="Singularity/Apptainer terminal backend", in_use=singularity_in_use,
  433. unchanged="terminal.backend: singularity, terminal.singularity_image (TERMINAL_SINGULARITY_IMAGE) "
  434. "and the container_* limits are unchanged",
  435. terminal_backend="singularity",
  436. ),
  437. LeftCoreFeature(
  438. plugin="agent-importers", label="`hermes import-agent`", in_use=agent_imports_in_use,
  439. unchanged="`hermes import-agent`, its flags and your import-sync.json sync sources are unchanged",
  440. command="import-agent", old_cli=("claw",),
  441. ),
  442. LeftCoreFeature(
  443. # Core kept COPILOT_GITHUB_TOKEN and the two base-URL overrides out of children as provider env
  444. # (Tier 2: credentialed CLIs still get them); GH_TOKEN/GITHUB_TOKEN stay on core's static lists.
  445. plugin="github-copilot", label="GitHub Copilot", in_use=copilot_in_use,
  446. unchanged="your COPILOT_GITHUB_TOKEN / GH_TOKEN / GITHUB_TOKEN and `hermes auth add copilot` logins, model "
  447. "names and copilot-acp settings are unchanged",
  448. private_env=("COPILOT_GITHUB_TOKEN", "COPILOT_API_BASE_URL", "COPILOT_ACP_BASE_URL"),
  449. providers=_COPILOT_API + _COPILOT_ACP, hosts=("githubcopilot.com", "models.github.ai"),
  450. profile_env=("HERMES_COPILOT_ACP_COMMAND", "HERMES_COPILOT_ACP_ARGS", "COPILOT_CLI_PATH",
  451. "COPILOT_ACP_BASE_URL"),
  452. launch_env=("HERMES_COPILOT_ACP_COMMAND", "HERMES_COPILOT_ACP_ARGS", "COPILOT_CLI_PATH"),
  453. notice=copilot_relogin_notice,
  454. ),
  455. )
  456. def _install_sentence(feature: LeftCoreFeature) -> str:
  457. from hermes_constants import get_hermes_home
  458. return (f"{feature.label} moved out of core into the '{feature.plugin}' plugin: install it with "
  459. f"`{_install_command(feature.plugin, Path(get_hermes_home()))}`")
  460. def platform_install_hint(platform: str) -> str:
  461. """For an unknown platform name that left core: the sentence that names its install command for
  462. the active home, else ``""``. Appended to "unknown platform" errors (``send_message``)."""
  463. feature = next((f for f in LEFT_CORE if f.platform and f.platform == platform), None)
  464. return f". {_install_sentence(feature)}" if feature else ""
  465. def terminal_backend_install_hint(backend: str) -> str:
  466. """For a ``terminal.backend`` value that left core: the sentence that names its install command for
  467. the active home, else ``""``. Appended to "unknown terminal backend" errors."""
  468. feature = next((f for f in LEFT_CORE if f.terminal_backend and f.terminal_backend == backend), None)
  469. return f". {_install_sentence(feature)}" if feature else ""
  470. def _provider_feature(name: str) -> Optional[LeftCoreFeature]:
  471. key = str(name or "").strip().lower()
  472. return next((f for f in LEFT_CORE if key and key in f.providers), None)
  473. def provider_install_hint(name: str) -> str:
  474. """For a provider name nothing resolves to that a left-core plugin supplies: the sentence naming its
  475. install command for the active home (its enable command when installed but disabled; its load error and
  476. update command when installed but it failed to load), else ``""``.
  477. Appended to every "unknown provider" error (runtime resolution, ``/model``, ``hermes model``, ``hermes
  478. auth add``)."""
  479. feature = _provider_feature(name)
  480. if feature is None:
  481. return ""
  482. from hermes_constants import get_hermes_home
  483. home = Path(get_hermes_home())
  484. if not plugin_present(feature.plugin, home):
  485. return f"{_install_sentence(feature)}."
  486. command = _install_command(feature.plugin, home)
  487. if _plugin_lists(home, feature.plugin)[1]:
  488. return (f"{feature.label} moved out of core into the '{feature.plugin}' plugin, which is installed but "
  489. f"disabled: run `{command.replace(' install ', ' enable ')}`.")
  490. # A model-provider plugin loads without plugins.enabled: present, not disabled and no profile = its load failed.
  491. error = _load_error(feature)
  492. return (f"{feature.label} moved out of core into the '{feature.plugin}' plugin, which is installed but failed "
  493. f"to load{f' ({error})' if error else ''}: run `{command.replace(' install ', ' update ')}`, or "
  494. f"see `hermes logs` for the cause.")
  495. def _load_error(feature: LeftCoreFeature) -> str:
  496. """The error *feature*'s provider plugin raised on import in the active home, else ``""``."""
  497. from providers import plugin_load_error
  498. return plugin_load_error(feature.plugin)
  499. def provider_left_core(name: str) -> bool:
  500. """*name* is a provider a left-core plugin supplies and no registered profile serves it now: no other
  501. resolution rung (the models.dev catalog) may stand in for it (it would send the user's token to the
  502. vendor's endpoint through a generic client)."""
  503. if _provider_feature(name) is None:
  504. return False
  505. from providers import get_provider_profile
  506. return get_provider_profile(str(name).strip().lower()) is None
  507. def feature_in_use(feature: LeftCoreFeature, home: Path, *, process_env: bool = False) -> bool:
  508. """*home* uses *feature*: its :attr:`~LeftCoreFeature.in_use` predicate, or a configured route at one of
  509. its :attr:`~LeftCoreFeature.hosts` (:func:`routes_at_hosts`)."""
  510. return feature.in_use(home, process_env=process_env) or bool(feature.hosts and routes_at_hosts(home, feature.hosts))
  511. def host_install_hint(base_url: str) -> str:
  512. """For a request rejected by an endpoint at a host a left-core plugin serves while none of that plugin's
  513. providers is registered (core attached the host's wire quirks itself): the install (or enable) sentence
  514. for the active home, else ``""``. Printed with non-retryable request errors."""
  515. feature = next((f for f in LEFT_CORE if any(_at_host(str(base_url or ""), h) for h in f.hosts)), None)
  516. if feature is None or not all(provider_left_core(name) for name in feature.providers):
  517. return ""
  518. return provider_install_hint(feature.providers[0])
  519. def recover_for_provider(name: Optional[str]) -> None:
  520. """Runtime resolution of *name*, a provider a left-core plugin supplies, in a home that uses it and lacks
  521. the plugin: run :func:`recover_at_startup` now. The CLI and Desktop resolve the provider before the agent
  522. (whose start runs the migration) exists, so they would otherwise stop at "unknown provider" on a home no
  523. ``hermes update`` migrated. Outcomes print in a declared terminal front end (:func:`serve_notices_on_stderr`),
  524. else wait for the home's next turn someone sees."""
  525. from hermes_constants import get_hermes_home, hermes_home_key
  526. from providers import get_provider_profile
  527. home = Path(get_hermes_home())
  528. name = str(name or "").strip().lower()
  529. if name in ("", "auto"): # the auto rung follows auth.json's active_provider (a core-era choice)
  530. name = str(_auth_store(home).get("active_provider") or "").strip().lower()
  531. feature = _provider_feature(name)
  532. if feature is None or _installs_held.get(): # held: a read-only diagnostic consumes no kept notice either
  533. return
  534. # A terminal front end shows outcomes now, also those another process (the gateway this CLI started) kept;
  535. # otherwise (Desktop, gateway, a detached turn) the home's next watched turn in any process gets them. Never
  536. # inferred from a TTY: a foreground `hermes gateway run` has one, and its resolutions serve the chat user.
  537. say = (lambda message: print(message, file=sys.stderr)) if _terminal_front_end else None
  538. if say is not None:
  539. for message in _claim_notices(home):
  540. say(message)
  541. if hermes_home_key(home) in _attempted: # this process already tried: skip the config/auth/.env reads
  542. return
  543. if plugin_present(feature.plugin, home) or get_provider_profile(name) is not None:
  544. return
  545. if feature_in_use(feature, home, process_env=True):
  546. recover_at_startup(say=say)
  547. _terminal_front_end = False
  548. def serve_notices_on_stderr() -> None:
  549. """This process is a terminal front end (the classic CLI, whose turns run in the gateway): outcomes of
  550. :func:`recover_for_provider` print to its stderr, also when its output is piped (``hermes chat -q``),
  551. since a resolution that fails before any agent exists (no credentials) leaves no agent to deliver them.
  552. Only a declaration counts: a foreground gateway has a TTY too, and its outcomes belong to the chat user."""
  553. global _terminal_front_end
  554. _terminal_front_end = True
  555. def profile_env_names() -> frozenset[str]:
  556. """Every row's :attr:`LeftCoreFeature.profile_env` (static: no discovery)."""
  557. return frozenset(name for feature in LEFT_CORE for name in feature.profile_env)
  558. def launch_env_names() -> frozenset[str]:
  559. """Every row's :attr:`LeftCoreFeature.launch_env` (static): the generic env writers refuse them."""
  560. return frozenset(name for feature in LEFT_CORE for name in feature.launch_env)
  561. def legacy_plugin_alias(name: str) -> str:
  562. """The catalog plugin a bundled key that left core now names (``observability/langfuse`` ->
  563. ``langfuse``), else ``""``."""
  564. return next((f.plugin for f in LEFT_CORE if f.plugin_key and f.plugin_key == name), "")
  565. def legacy_plugin_keys(plugin: str) -> set[str]:
  566. """Bundled keys that now name catalog *plugin* (inverse of :func:`legacy_plugin_alias`)."""
  567. return {f.plugin_key for f in LEFT_CORE if f.plugin_key and f.plugin == plugin}
  568. def moved_command_hint(prog: str, value: str, action: str = "") -> str:
  569. """For a command a left-core plugin took over: ``hermes auth [<action>] <cli>`` (core's old login
  570. spelling), core's old nested spelling (``hermes mcp serve``), or the plugin's own ``hermes <cli>`` /
  571. ``hermes <command>`` / ``hermes <old_cli>`` while the plugin is not loaded, the line saying where it
  572. went and how to get it for the active home, else ``""``."""
  573. from hermes_constants import get_hermes_home
  574. home = Path(get_hermes_home())
  575. moved = next((f for f in LEFT_CORE if f.old_command and f.old_command == f"{prog} {value}"), None)
  576. if moved is not None:
  577. present = plugin_present(moved.plugin, home)
  578. get = "" if present else f" Install it with: `{_install_command(moved.plugin, home)}`."
  579. return (f"{moved.label} moved out of core into the '{moved.plugin}' plugin: `{moved.old_command}` is now "
  580. f"`hermes {moved.command}`.{get}")
  581. if prog == "hermes auth":
  582. feature = next((f for f in LEFT_CORE if f.cli and f.cli == value), None)
  583. elif prog == "hermes":
  584. feature = next((f for f in LEFT_CORE if value and value in (f.cli, f.command, *f.old_cli)), None)
  585. else:
  586. feature = None
  587. if feature is None:
  588. return ""
  589. install = _install_command(feature.plugin, home)
  590. if not plugin_present(feature.plugin, home):
  591. get = f" Install it with: `{install}`."
  592. else:
  593. get = f" Enable it with: `{install.replace(' install ', ' enable ')}`." if prog == "hermes" else ""
  594. if prog == "hermes auth":
  595. old = " ".join(p for p in ("hermes auth", action, value) if p)
  596. return (f"{feature.label} moved out of core into the '{feature.plugin}' plugin: `{old}` is now "
  597. f"`hermes {value} {action or 'login'}`.{get}")
  598. label = f"`hermes {value}`" if value in feature.old_cli else feature.label
  599. return f"{label} moved out of core into the '{feature.plugin}' plugin, which is not loaded.{get}"
  600. def moved_plugin_hint(name: str) -> str:
  601. """For a plugin name nothing resolves to (so the plugin is not installed): the bundled key of a
  602. plugin that left core (``observability/langfuse``) or its catalog name, the line naming the install
  603. command for the active home, else ``""``. Appended to "No plugin named ..." errors."""
  604. feature = next((f for f in LEFT_CORE if f.plugin_key and name in (f.plugin_key, f.plugin)), None)
  605. return f"{_install_sentence(feature)}." if feature else ""
  606. _attempted: set[str] = set()
  607. _installs_held: ContextVar[bool] = ContextVar("left_core_installs_held", default=False)
  608. @contextmanager
  609. def installs_held():
  610. """No migration attempt inside (a read-only diagnostic such as ``hermes doctor``, whose provider checks run
  611. the runtime resolver): the unknown-provider and host hints still name the install command."""
  612. token = _installs_held.set(True)
  613. try:
  614. yield
  615. finally:
  616. _installs_held.reset(token)
  617. def defer_startup_notice(message: str) -> None:
  618. """Hand *message* to the active home's next turn someone sees (:func:`claim_kept_notices`), once.
  619. For boot-path work that runs before any agent exists."""
  620. from hermes_constants import get_hermes_home
  621. logger.warning(message)
  622. _queue_notice(Path(get_hermes_home()), message)
  623. def _notice_file(home: Path) -> Path:
  624. return home / "cache" / "left-core-notices.jsonl"
  625. @contextmanager
  626. def _notices_locked(home: Path):
  627. """The cross-process lock every append and claim of *home*'s kept notices holds: an append never lands
  628. in a file a claimant already read, and a claimant never reads a half-written line."""
  629. import threading
  630. from hermes_cli.auth import _file_lock
  631. path = _notice_file(home)
  632. # A fresh holder: the helper's per-thread reentrancy must never skip one home's lock inside another's.
  633. with _file_lock(path.with_name(f"{path.name}.lock"), threading.local(), 5.0,
  634. f"Timed out waiting for the left-core notice lock ({path})"):
  635. yield path
  636. def _queue_notice(home: Path, message: str) -> None:
  637. """Keep *message* for *home*'s next watched turn in ANY process (:func:`_claim_notices`): the process that
  638. produced it (a CLI resolving the provider, a gateway start) often runs no agent for that home itself.
  639. A line already kept is not kept again: every start with ``allow_lazy_installs`` off reports the same row."""
  640. import json
  641. line = json.dumps(message)
  642. try:
  643. with _notices_locked(home) as path:
  644. if path.exists() and line in path.read_text(encoding="utf-8-sig").splitlines():
  645. return
  646. with open(path, "a", encoding="utf-8") as fh:
  647. fh.write(line + "\n")
  648. except OSError as exc: # unwritable home or lock timeout: the outcome is still logged
  649. logger.debug("left-core notice not kept for %s: %s", home, exc)
  650. def _claim_notices(home: Path) -> list[str]:
  651. """Take every notice kept for *home*, exactly once across processes: read and removed under the notice
  652. lock, so of several agents starting at once only one gets (and delivers) them. A crash before the
  653. removal leaves them for the next claimant rather than losing them."""
  654. import json
  655. if not _notice_file(home).exists(): # the common case: no lock taken
  656. return []
  657. try:
  658. with _notices_locked(home) as path:
  659. lines = path.read_text(encoding="utf-8-sig").splitlines()
  660. path.unlink()
  661. except OSError: # another claimant took them first, or the lock timed out (they stay kept)
  662. return []
  663. messages = []
  664. for line in dict.fromkeys(lines):
  665. try:
  666. messages.append(str(json.loads(line)))
  667. except ValueError: # a line from outside Hermes: skip it only
  668. continue
  669. return messages
  670. def claim_kept_notices() -> list[str]:
  671. """Every notice kept for the active home in any process, for a turn someone sees (exactly once)."""
  672. from hermes_constants import get_hermes_home
  673. return _claim_notices(Path(get_hermes_home()))
  674. def plugin_present(plugin: str, home: Path) -> bool:
  675. """Installed in *home* (enabled or not: a user who disabled it chose to). Read-only."""
  676. return (home / "plugins" / plugin).is_dir()
  677. def _core_carried(feature: LeftCoreFeature, selection: list) -> bool:
  678. """Whether core resolved *feature*'s toolsets on for a platform selecting *selection*: named
  679. directly, or through a ``hermes`` / ``hermes-<platform>`` composite that included them."""
  680. def carries(name: str) -> bool:
  681. if name in feature.toolsets or name in feature.replaces_toolsets or name == "hermes":
  682. return True
  683. return name.startswith("hermes-") and name[len("hermes-"):].replace("-", "_") not in feature.off_platforms
  684. return any(carries(str(name)) for name in selection)
  685. _SCOPED_KEY = "_left_core_scoped" # config.yaml: rows whose toolset scope this home already converted
  686. # config.yaml: rows this home has had installed (by the migration, or by the user before it ran).
  687. # Never written before the plugin dir exists, so a home whose install never succeeded keeps retrying.
  688. _INSTALLED_KEY = "_left_core_installed"
  689. # config.yaml: rows whose ``left_at`` config step found the core feature in use in this home.
  690. _USED_KEY = "_left_core_used"
  691. def record_core_use(home: Path, config: dict, version: int) -> bool:
  692. """Config step *version* hook, before it writes *config* (*home*'s raw config.yaml, still showing the
  693. core-era setup): mark every row that left core at *version* and that *home* uses. Returns whether
  694. *config* changed. The launch home's process env counts, as at agent start."""
  695. used = [feature for feature in LEFT_CORE if feature.left_at == version
  696. and not _marked(config, _USED_KEY, feature) and feature_in_use(feature, home, process_env=True)]
  697. for feature in used:
  698. _mark(config, _USED_KEY, feature)
  699. return bool(used)
  700. def _predates_split(home: Path, feature: LeftCoreFeature) -> bool:
  701. """*home* ran *feature* in core: its config is still below ``left_at`` (this pass ran before the
  702. config step), that step recorded the feature in use, or config.yaml is missing or unstamped. Every
  703. config.yaml Hermes writes carries a stamp, and the first save that stamps one records the rows in use
  704. (``config_version_stamp.note_first_stamp``), so only a home from before the split lacks it; core ran
  705. the feature there from its .env alone."""
  706. if not feature.left_at:
  707. return True
  708. config = _read_config(home)
  709. if _marked(config, _USED_KEY, feature) or "_config_version" not in config:
  710. return True
  711. try:
  712. return int(config["_config_version"]) < feature.left_at
  713. except (TypeError, ValueError):
  714. return False
  715. def _marked(config: dict, key: str, feature: LeftCoreFeature) -> bool:
  716. done = config.get(key)
  717. return isinstance(done, list) and feature.plugin in map(str, done)
  718. def _scope_kept(config: dict, feature: LeftCoreFeature) -> bool:
  719. return not feature.toolsets or _marked(config, _SCOPED_KEY, feature)
  720. def _mark(config: dict, key: str, feature: LeftCoreFeature) -> None:
  721. done = config.get(key)
  722. config[key] = sorted({*(map(str, done) if isinstance(done, list) else ()), feature.plugin})
  723. def _turn_off_replaced(config: dict, feature: LeftCoreFeature) -> None:
  724. """Turn *feature*'s ``replaces_toolsets`` off in *config*: every saved platform list naming one names
  725. the plugin's toolsets instead (so turning core's toolset back on later stays that platform's choice),
  726. and ``agent.disabled_toolsets`` takes them, which also covers platforms on a default composite. One the
  727. user had already disabled there disables the plugin's toolsets too (they are on by default)."""
  728. from agent.skill_utils import parse_config_string_list
  729. from hermes_cli.toolset_validation import parse_platform_toolsets_value
  730. replaced = set(feature.replaces_toolsets)
  731. saved = config.get("platform_toolsets")
  732. for platform, value in (saved.items() if isinstance(saved, dict) else ()):
  733. selection = parse_platform_toolsets_value(value)
  734. if selection is not None and replaced & set(map(str, selection)):
  735. kept = [item for item in selection if str(item) not in replaced]
  736. saved[platform] = kept + [ts for ts in feature.toolsets if ts not in map(str, kept)]
  737. agent = config.get("agent") if isinstance(config.get("agent"), dict) else {}
  738. disabled = parse_config_string_list(agent.get("disabled_toolsets")) if agent.get("disabled_toolsets") else []
  739. turned_off = replaced if replaced.isdisjoint(disabled) else replaced | set(feature.toolsets)
  740. agent["disabled_toolsets"] = [*disabled, *sorted(turned_off - set(disabled))]
  741. config["agent"] = agent
  742. def _record_migration(home: Path, feature: LeftCoreFeature) -> None:
  743. """Keep *feature*'s core-era toolset scope, and mark it installed once its plugin is in *home*,
  744. in one config write.
  745. Scope: record the toolsets in ``known_plugin_toolsets[platform]`` (= off) for every platform
  746. where core had them off: a saved ``platform_toolsets`` list that does not carry them, or no list
  747. on an ``off_platforms`` platform. Platforms core resolved them on for are left alone, except that
  748. a row's ``replaces_toolsets`` go off everywhere (:func:`_turn_off_replaced`). A one-time
  749. conversion per home and row, independent of installation: a plugin installed before the update
  750. (it stays inert on a core that still ships the feature) still needs it. Completion is marked
  751. under ``_left_core_scoped`` so a later run never undoes a choice the user made since
  752. (``hermes tools``). Raises when config.yaml cannot be read or written."""
  753. from hermes_cli.config import atomic_config_write, read_user_config_raw
  754. from hermes_cli.config_backend import config_exists
  755. from hermes_cli.toolset_validation import parse_platform_toolsets_value
  756. path = home / "config.yaml"
  757. created = not config_exists(path)
  758. config = read_user_config_raw(path)
  759. installed = plugin_present(feature.plugin, home) and not _marked(config, _INSTALLED_KEY, feature)
  760. if _scope_kept(config, feature) and not installed:
  761. return
  762. if installed:
  763. _mark(config, _INSTALLED_KEY, feature)
  764. if not _scope_kept(config, feature):
  765. saved = config.get("platform_toolsets")
  766. saved = saved if isinstance(saved, dict) else {}
  767. selections = {str(p): parse_platform_toolsets_value(v) for p, v in saved.items()}
  768. for platform in feature.off_platforms:
  769. selections.setdefault(platform, None)
  770. known = config.get("known_plugin_toolsets")
  771. known = known if isinstance(known, dict) else {}
  772. for platform, selection in selections.items():
  773. if selection is None and platform not in feature.off_platforms:
  774. continue # no (valid) saved list: core's default composite carried the toolsets
  775. if selection is not None and _core_carried(feature, selection):
  776. continue
  777. current = known.get(platform) if isinstance(known.get(platform), list) else []
  778. if missing := [ts for ts in feature.toolsets if ts not in current]:
  779. known[platform] = sorted({*map(str, current), *missing})
  780. if known:
  781. config["known_plugin_toolsets"] = known
  782. if feature.replaces_toolsets:
  783. _turn_off_replaced(config, feature)
  784. _mark(config, _SCOPED_KEY, feature)
  785. if created:
  786. _stamp_created(home, config)
  787. atomic_config_write(path, config)
  788. def _stamp_created(home: Path, config: dict) -> None:
  789. """A missing config.yaml reads as the current schema, so no config step ever ran on this home: the file
  790. the conversion creates carries that stamp (unstamped, every boot warns it predates the support floor)
  791. and, as a plain save's first stamp does, the rows in use, or the stamp makes the home look post-split."""
  792. from hermes_cli.config_defaults import DEFAULT_CONFIG
  793. from hermes_cli.config_version_stamp import note_first_stamp
  794. config["_config_version"] = DEFAULT_CONFIG["_config_version"]
  795. note_first_stamp(home, {}, config)
  796. def _pending(home: Path, *, say: Callable[[str], None], process_env: bool = False,
  797. backoff: bool = False) -> list[LeftCoreFeature]:
  798. """Rows *home* uses whose plugin it never had and that the catalog ships (a catalog miss is
  799. reported through *say*). Converts the toolset scope of every row *home* uses once
  800. (:func:`_record_migration`), installed or not; a row whose scope cannot be recorded is
  801. reported and skipped, never installed unscoped. A row marked installed is done for good.
  802. *backoff* (startup) skips a row whose last attempt failed recently, before any network."""
  803. from hermes_cli.memory_provider_migration import catalog_source
  804. out = []
  805. for feature in LEFT_CORE:
  806. if _marked(_read_config(home), _INSTALLED_KEY, feature):
  807. continue
  808. if not feature_in_use(feature, home, process_env=process_env):
  809. continue
  810. if not _predates_split(home, feature):
  811. _say_post_split(home, feature, say=say, backoff=backoff, process_env=process_env)
  812. continue
  813. present = plugin_present(feature.plugin, home)
  814. try:
  815. _record_migration(home, feature)
  816. except Exception as exc:
  817. say(f" ⚠ {feature.label} moved out of core into the '{feature.plugin}' plugin: its per-platform "
  818. f"toolset selection could not be kept ({exc}). Check `hermes tools`"
  819. + ("." if present else f" and run `{_install_command(feature.plugin, home)}`."))
  820. continue
  821. if present:
  822. continue
  823. if backoff and _failed_recently(home, feature.plugin):
  824. logger.info("%s plugin install failed recently for %s; retrying later or on `hermes update`",
  825. feature.label, home)
  826. continue
  827. if catalog_source(feature.plugin) is None:
  828. _note_failure(home, feature.plugin)
  829. say(_noticed(f" ⚠ {feature.label} moved out of core into the '{feature.plugin}' plugin, which this "
  830. f"Hermes cannot find in the plugin catalog yet. Run "
  831. f"`{_install_command(feature.plugin, home)}` once it is listed.", home, feature, process_env))
  832. continue
  833. out.append(feature)
  834. return out
  835. def _say_post_split(home: Path, feature: LeftCoreFeature, *, say: Callable[[str], None], backoff: bool,
  836. process_env: bool = False) -> None:
  837. """*home* uses *feature* while its stamp says it never ran it in core (a newer home, or a Nix-managed
  838. config.yaml stamped at activation): nothing is converted or installed, but a home without the plugin is
  839. told where the feature went. Starts repeat it on the install backoff (``_note_failure``)."""
  840. if plugin_present(feature.plugin, home) or (backoff and _failed_recently(home, feature.plugin)):
  841. return
  842. _note_failure(home, feature.plugin)
  843. say(_noticed(f" ⚠ {feature.label} moved out of core into the '{feature.plugin}' plugin, which this profile "
  844. f"does not have, so it is off. Run `{_install_command(feature.plugin, home)}`.",
  845. home, feature, process_env))
  846. def _noticed(message: str, home: Path, feature: LeftCoreFeature, process_env: bool) -> str:
  847. """*message* with *feature*'s :attr:`~LeftCoreFeature.notice` for *home* appended."""
  848. extra = feature.notice(home, process_env=process_env)
  849. return f"{message} {extra}" if extra else message
  850. def _install_into(home: Path, *, consent: Optional[bool] = None) -> Callable[[str], dict]:
  851. def _install(name: str) -> dict:
  852. from hermes_cli.plugins_cmd import dashboard_install_plugin
  853. from hermes_constants import reset_hermes_home_override, set_hermes_home_override
  854. token = set_hermes_home_override(home)
  855. try:
  856. return dashboard_install_plugin("", force=False, enable=True, catalog_name=name,
  857. assume_deps_consent=_unattended_consent() if consent is None
  858. else consent)
  859. finally:
  860. reset_hermes_home_override(token)
  861. return _install
  862. def _first_cause(error: str) -> str:
  863. """One line for a notice: git's own ``fatal:`` / ``error:`` line when *error* ends with raw git
  864. stderr (a failed clone), else its first non-empty line."""
  865. lines = [line.strip() for line in error.splitlines() if line.strip()]
  866. cause = next((line.split(":", 1)[1].strip() for line in lines if line.startswith(("fatal:", "error:"))), None)
  867. return (cause or (lines[0] if lines else "unknown error")).rstrip(". ")
  868. def _install_one(home: Path, feature: LeftCoreFeature, *, install: Callable[[str], dict],
  869. say: Callable[[str], None], process_env: bool = False) -> bool:
  870. try:
  871. result = install(feature.plugin)
  872. except Exception as exc: # network, uv, kill list — report, do not raise
  873. result = {"ok": False, "error": str(exc)}
  874. if result.get("ok"):
  875. from providers import refresh_bound_home
  876. refresh_bound_home() # a provider plugin resolves in this same call, not after the stamp TTL
  877. try:
  878. _record_migration(home, feature)
  879. except Exception as exc: # the next run sees the plugin dir and records it then
  880. logger.debug("left-core install marker not written for %s: %s", home, exc)
  881. say(_noticed(f" ✓ {feature.label} moved out of core — installed the '{feature.plugin}' plugin from the "
  882. f"catalog ({feature.unchanged}).", home, feature, process_env))
  883. return True
  884. _note_failure(home, feature.plugin)
  885. error = _first_cause(str(result.get("error") or ""))
  886. say(_noticed(f" ⚠ {feature.label} moved out of core and its '{feature.plugin}' plugin could not be installed "
  887. f"automatically: {error}. Run `{_install_command(feature.plugin, home)}`.", home, feature, process_env))
  888. return False
  889. def migrate_home(home: Path, *, install: Callable[[str], dict], say: Callable[[str], None] = print,
  890. process_env: bool = False) -> list[str]:
  891. """Install every left-core plugin *home* uses and lacks. Returns installed plugin names; never raises."""
  892. installed = []
  893. for feature in _pending(home, say=say, process_env=process_env):
  894. if _install_one(home, feature, install=install, say=say, process_env=process_env):
  895. installed.append(feature.plugin)
  896. return installed
  897. def migrate_all_homes(*, say: Callable[[str], None] = print) -> list[str]:
  898. """``hermes update`` hook: every profile home sharing this venv. Grouped by plugin and each home's
  899. unattended consent like the memory migration: homes of one group share dependency answers, and a
  900. failure names the rest of its group in one line instead of failing them one by one."""
  901. from hermes_cli.plugins_cmd_install import shared_dependency_answers
  902. from hermes_constants import get_routing_process_hermes_home, hermes_home_key
  903. from pm.plugins_state import dependency_homes
  904. def labelled(home: Path) -> Callable[[str], None]:
  905. return lambda message: say(f" [{_home_label(home)}] {message.lstrip()}")
  906. def launched(home: Path) -> bool: # this process's env (a shell export) is the launch home's, as at start
  907. return hermes_home_key(home) == hermes_home_key(get_routing_process_hermes_home())
  908. pending: dict[tuple[str, bool], tuple[LeftCoreFeature, list[Path]]] = {}
  909. for home in dependency_homes():
  910. try:
  911. features = _pending(home, say=labelled(home), process_env=launched(home))
  912. consent = bool(features) and _home_consent(home)
  913. except Exception as exc:
  914. logger.debug("left-core migration skipped for %s: %s", home, exc)
  915. continue
  916. for feature in features:
  917. pending.setdefault((feature.plugin, consent), (feature, []))[1].append(home)
  918. installed: list[str] = []
  919. try:
  920. for feature, homes in pending.values():
  921. if len(homes) > 1 and _interactive():
  922. say(f" {feature.label} is used in {len(homes)} profiles "
  923. f"({', '.join(_home_label(h) for h in homes)}); your answers to its dependency "
  924. f"questions apply to all of them.")
  925. with shared_dependency_answers():
  926. for index, home in enumerate(homes):
  927. if _install_one(home, feature, install=_install_into(home), say=labelled(home),
  928. process_env=launched(home)):
  929. installed.append(feature.plugin)
  930. continue
  931. rest = homes[index + 1:]
  932. if rest:
  933. say(f" ⚠ The '{feature.plugin}' plugin was not installed for "
  934. f"{', '.join(_home_label(h) for h in rest)} either. Run "
  935. + ", ".join(f"`{_install_command(feature.plugin, h)}`" for h in rest) + ".")
  936. break
  937. except KeyboardInterrupt:
  938. say(" ⚠ Plugin migration cancelled. Profiles already migrated keep their plugin; run "
  939. "`hermes plugins install <name>` (with `-p <profile>`) for the rest.")
  940. return installed
  941. def _gateway_serves(home: Path) -> bool:
  942. """A live gateway serves *home*: it loaded its platforms before this agent-start install."""
  943. try:
  944. from gateway.status import resolve_gateway_liveness
  945. return resolve_gateway_liveness(profile_dir=home, use_cache=False).running
  946. except Exception:
  947. return False
  948. def recover_at_startup(*, say: Optional[Callable[[str], None]] = None, gateway_start: bool = False) -> list[str]:
  949. """Agent/gateway start hook for the active home: one attempt per process per home. With *say* (a
  950. terminal's sink) outcomes are delivered now, together with any an earlier attempt or boot maintenance
  951. (:func:`defer_startup_notice`) kept for this home in any process; without it they are logged and kept in
  952. the home (:func:`_queue_notice`) for its next turn someone sees (:func:`claim_kept_notices`), in
  953. whichever process. *gateway_start*: the gateway itself, which needs no restart hint. Returns installed
  954. plugin names."""
  955. from agent.safe_worker_policy import worker_config_snapshot
  956. if _installs_held.get():
  957. return []
  958. if worker_config_snapshot() is not None:
  959. # A frozen safe/ignore-user-config worker never reads the profile's config.yaml and never
  960. # installs customizations; the owner process runs this migration for the home.
  961. return []
  962. from hermes_constants import get_hermes_home, hermes_home_key
  963. home = Path(get_hermes_home())
  964. key = hermes_home_key(home)
  965. delivered: set[str] = set()
  966. def deliver(message: str) -> None:
  967. if say is None:
  968. _queue_notice(home, message)
  969. return
  970. if message in delivered: # a kept copy of what this attempt reports again (allow_lazy_installs off)
  971. return
  972. delivered.add(message)
  973. try:
  974. say(message)
  975. except Exception:
  976. logger.debug("left-core migration notification failed", exc_info=True)
  977. if say is not None:
  978. for message in _claim_notices(home):
  979. deliver(message)
  980. if key in _attempted:
  981. return []
  982. _attempted.add(key)
  983. def report(message: str) -> None:
  984. message = message.strip()
  985. logger.warning(message)
  986. deliver(message)
  987. try:
  988. features = _pending(home, say=report, process_env=True, backoff=True)
  989. if not features:
  990. return []
  991. from pm.install import lazy_installs_allowed
  992. if not lazy_installs_allowed():
  993. for feature in features:
  994. report(_noticed(f"⚠ {feature.label} moved out of core and its '{feature.plugin}' plugin is not "
  995. f"installed, so it is off. security.allow_lazy_installs is off, so Hermes did not "
  996. f"fetch it: run `{_install_command(feature.plugin, home)}`.", home, feature, True))
  997. return []
  998. installed = []
  999. # Agent init cannot answer a dependency prompt: under the CLI the chat input owns the terminal,
  1000. # so the question hangs at "Initializing agent...". Every row shipped in core, so its users
  1001. # already accepted its dependencies (as memory_provider_migration.recover_at_startup does).
  1002. for feature in features:
  1003. if _install_one(home, feature, install=_install_into(home, consent=True), say=report, process_env=True):
  1004. installed.append(feature.plugin)
  1005. if not gateway_start and feature.platform and _gateway_serves(home):
  1006. report(f"Restart the gateway (`hermes gateway restart`) so it serves {feature.label}.")
  1007. return installed
  1008. except Exception as exc: # never take agent/gateway start down
  1009. logger.warning("left-core plugin migration failed: %s", exc, exc_info=True)
  1010. return []
  1011. def recover_for_command(name: Optional[str]) -> None:
  1012. """``hermes <name>`` names a command a left-core plugin registers, and the active home uses that
  1013. feature but lacks the plugin: run :func:`recover_at_startup` now, before plugin commands are
  1014. discovered, so the command it installs runs in this same invocation. A home nothing migrated yet
  1015. (a Docker image swap runs no ``hermes update``) whose only Hermes process is a scheduled
  1016. ``hermes import-agent --sync`` never starts an agent or a gateway to do it."""
  1017. from hermes_constants import get_hermes_home
  1018. home = Path(get_hermes_home())
  1019. if any(name and name in (f.cli, f.command, *f.old_cli) and not plugin_present(f.plugin, home)
  1020. and feature_in_use(f, home) for f in LEFT_CORE):
  1021. recover_at_startup(say=lambda message: print(message, file=sys.stderr))