shared_metrics_disabled.py 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300
  1. """hermes.feature_disabled.count: a user turns off something Hermes ships on, or removes something shipped.
  2. One chokepoint sees every write: ``save_config`` hands over the raw config it replaced and the one it
  3. wrote, and :func:`config_transitions` diffs only what the user moved away from the shipped default
  4. (or back to it): default-on toolsets, ``skills.disabled``, ``plugins.disabled`` and default-``True``
  5. booleans. Names are public only when shipped (toolset key, bundled/catalog skill, bundled/catalog
  6. plugin, ``DEFAULT_CONFIG`` key path; never a value); anything else reads ``custom``. The store counts
  7. each (kind, name, event) at most once per day.
  8. The surface is the entry point that is running: ``set_process_surface`` from the ``hermes`` command
  9. dispatch (``tools`` / ``config`` / ``skills`` / ``plugins`` / chat slash commands / the web server) and
  10. the TUI gateway. A process with no surface (setup wizard, updates) records nothing, nor does a write
  11. Hermes makes itself inside a surfaced process (migrations, under :func:`hermes_applied_write`): those
  12. are Hermes applying choices, not a user turning something off.
  13. ``save_config``'s callers may hold their own write lock (the dashboard's ``_CONFIG_MUTATION_LOCK``), so
  14. the hook only runs the cheap gate inline; the diff and the record run on a thread bound to the owning
  15. profile.
  16. """
  17. from __future__ import annotations
  18. import contextlib
  19. import copy
  20. import functools
  21. import logging
  22. import threading
  23. from contextvars import ContextVar
  24. from typing import Any, Iterable, Iterator
  25. logger = logging.getLogger(__name__)
  26. CUSTOM = "custom"
  27. _COMMAND_SURFACES = {
  28. None: "cli_slash", "chat": "cli_slash", "tools": "cli_tools", "config": "cli_config",
  29. "skills": "cli_config", "plugins": "cli_config",
  30. "dashboard": "web", "serve": "web", "gui": "web", "desktop": "web",
  31. }
  32. _SETTING_KINDS = {"memory": "memory", "curator": "curator", "compression": "compression"}
  33. _OFF = frozenset({"false", "off", "no", "0", "none", ""})
  34. _process_surface: str | None = None
  35. _hermes_write: ContextVar[bool] = ContextVar("hermes_feature_disabled_hermes_write", default=False)
  36. def set_process_surface(command: Any) -> None:
  37. """Called once by the ``hermes`` dispatch (``command`` is the subcommand, None for chat) or the
  38. TUI gateway (``"tui_gateway"``). Unknown commands clear it."""
  39. global _process_surface
  40. _process_surface = "tui_gateway" if command == "tui_gateway" else _COMMAND_SURFACES.get(command)
  41. def current_surface() -> str | None:
  42. surface = _process_surface
  43. if surface == "web":
  44. from .shared_metrics_setup import web_setup_surface
  45. return web_setup_surface()
  46. if surface == "tui_gateway":
  47. try:
  48. from tui_gateway.server import _resolve_session_platform
  49. return _resolve_session_platform()
  50. except Exception:
  51. return "tui"
  52. return surface
  53. # ---- names -----------------------------------------------------------------------------------
  54. @functools.cache
  55. def _bundled_plugin_names() -> frozenset[str]:
  56. from .shared_metrics_catalog import _REPO_ROOT
  57. root = _REPO_ROOT / "plugins"
  58. try:
  59. return frozenset(
  60. p.parent.name.lower() for p in [*root.glob("*/plugin.yaml"), *root.glob("*/*/plugin.yaml")]
  61. )
  62. except OSError:
  63. return frozenset()
  64. def plugin_metric_name(raw: Any) -> str:
  65. from .shared_metrics_catalog import _norm, _safe, plugin_catalog_names
  66. name = _norm(raw).rsplit("/", 1)[-1]
  67. return name if name and (name in _safe(_bundled_plugin_names) or name in _safe(plugin_catalog_names)) else CUSTOM
  68. def skill_metric_name(raw: Any) -> str:
  69. from .shared_metrics_catalog import skill_metric_name as catalog_skill_name
  70. return catalog_skill_name(raw)
  71. @functools.cache
  72. def default_on_settings() -> frozenset[str]:
  73. """Dotted ``DEFAULT_CONFIG`` paths whose shipped value is ``True`` (the closed setting vocabulary)."""
  74. from hermes_cli.config import DEFAULT_CONFIG
  75. from .shared_metrics_contract import FEATURE_DISABLED_NAME_MAX_LENGTH, _metric_identifier
  76. paths: set[str] = set()
  77. def walk(node: Any, prefix: str) -> None:
  78. for key, value in node.items():
  79. if not isinstance(key, str) or key.startswith("_"):
  80. continue
  81. path = f"{prefix}{key}"
  82. if isinstance(value, dict):
  83. walk(value, f"{path}.")
  84. elif value is True and _metric_identifier(path, max_length=FEATURE_DISABLED_NAME_MAX_LENGTH) == path:
  85. paths.add(path)
  86. walk(DEFAULT_CONFIG, "")
  87. return frozenset(paths)
  88. # ---- transitions -----------------------------------------------------------------------------
  89. def _get(config: Any, path: str) -> Any:
  90. node = config
  91. for part in path.split("."):
  92. if not isinstance(node, dict) or part not in node:
  93. return True # absent = the shipped default (True for every tracked path)
  94. node = node[part]
  95. return node
  96. def _on(value: Any) -> bool:
  97. if isinstance(value, str):
  98. return value.strip().lower() not in _OFF
  99. return bool(value)
  100. def _setting_transitions(old: dict, new: dict) -> Iterable[tuple[str, str, str]]:
  101. for path in sorted(default_on_settings()):
  102. before, after = _get(old, path), _get(new, path)
  103. if any(isinstance(value, str) and "${" in value for value in (before, after)):
  104. continue # an unexpanded ``${VAR}`` template (the raw side): its value is unknown here
  105. before, after = _on(before), _on(after)
  106. if before != after:
  107. yield _SETTING_KINDS.get(path.split(".", 1)[0], "setting"), path, "re_enabled" if after else "disabled"
  108. def _names(config: Any, section: str, key: str, *, per_platform: str | None = None) -> set[str]:
  109. from agent.skill_utils import parse_config_string_list
  110. block = config.get(section) if isinstance(config, dict) else None
  111. if not isinstance(block, dict):
  112. return set()
  113. names = set(parse_config_string_list(block.get(key)) or ())
  114. platforms = block.get(per_platform) if per_platform else None
  115. if isinstance(platforms, dict):
  116. for value in platforms.values():
  117. names |= set(parse_config_string_list(value) or ())
  118. return {str(n) for n in names}
  119. def _plugin_kind(name: str) -> str:
  120. """A messaging-platform plugin (bundled or catalog) reports as a platform, other plugins as plugins."""
  121. from .shared_metrics_catalog import _safe, bundled_platform_names, catalog_platform_names
  122. platforms = _safe(bundled_platform_names) | _safe(catalog_platform_names)
  123. return "platform" if name.strip().lower().rsplit("/", 1)[-1] in platforms else "plugin"
  124. def _list_transitions(old_names: set[str], new_names: set[str], kind: str, namer) -> Iterable[tuple[str, str, str]]:
  125. for names, event in ((new_names - old_names, "disabled"), (old_names - new_names, "re_enabled")):
  126. for name in sorted(names):
  127. yield (_plugin_kind(name) if kind == "plugin" else kind), namer(name), event
  128. def _toolset_transitions(old: dict, new: dict) -> Iterable[tuple[str, str, str]]:
  129. def scope(config: dict) -> tuple[Any, Any]:
  130. agent = config.get("agent") if isinstance(config.get("agent"), dict) else {}
  131. return config.get("platform_toolsets"), agent.get("disabled_toolsets")
  132. if scope(old) == scope(new):
  133. return
  134. from hermes_cli.tools_config import _configurable_keys, _get_platform_tools
  135. platforms = {"cli"}
  136. for config in (old, new):
  137. if isinstance(config.get("platform_toolsets"), dict):
  138. platforms |= {str(p) for p in config["platform_toolsets"]}
  139. shipped = _configurable_keys()
  140. for platform in sorted(platforms):
  141. default = _get_platform_tools({}, platform, include_default_mcp_servers=False) & shipped
  142. before = _get_platform_tools(old, platform, include_default_mcp_servers=False)
  143. after = _get_platform_tools(new, platform, include_default_mcp_servers=False)
  144. for toolset in sorted(default):
  145. if (toolset in before) != (toolset in after):
  146. yield "toolset", toolset, "re_enabled" if toolset in after else "disabled"
  147. def config_transitions(old: Any, new: Any) -> list[tuple[str, str, str]]:
  148. """(kind, name, event) for each shipped-on thing the write turned off or back on (deduped)."""
  149. old = old if isinstance(old, dict) else {}
  150. new = new if isinstance(new, dict) else {}
  151. found: list[tuple[str, str, str]] = []
  152. for batch in (
  153. _setting_transitions(old, new),
  154. _list_transitions(_names(old, "skills", "disabled", per_platform="platform_disabled"),
  155. _names(new, "skills", "disabled", per_platform="platform_disabled"), "skill", skill_metric_name),
  156. _list_transitions(_names(old, "plugins", "disabled"), _names(new, "plugins", "disabled"), "plugin",
  157. plugin_metric_name),
  158. _toolset_transitions(old, new),
  159. ):
  160. try:
  161. found.extend(t for t in batch if t not in found)
  162. except Exception:
  163. logger.debug("Feature-disabled transitions skipped", exc_info=True)
  164. return found
  165. # ---- recording -------------------------------------------------------------------------------
  166. def _emit(transitions: Iterable[tuple[str, str, str]], surface: str) -> None:
  167. from .relay_shared_metrics import record_process_mark
  168. from .shared_metrics_contract import FEATURE_DISABLED_MARK
  169. for kind, name, event in transitions:
  170. record_process_mark(FEATURE_DISABLED_MARK, {"event": event, "kind": kind, "name": name, "surface": surface})
  171. @contextlib.contextmanager
  172. def hermes_applied_write() -> Iterator[None]:
  173. """Config writes Hermes makes on its own (migrations) record nothing, whatever the surface."""
  174. token = _hermes_write.set(True)
  175. try:
  176. yield
  177. finally:
  178. _hermes_write.reset(token)
  179. def _record(old: Any, new: Any, surface: str, home: str) -> None:
  180. from hermes_constants import reset_hermes_home_override, set_hermes_home_override
  181. token = set_hermes_home_override(home) # a thread does not inherit the profile binding
  182. try:
  183. _emit(config_transitions(old, new), surface)
  184. except Exception:
  185. logger.debug("Feature-disabled not recorded", exc_info=True)
  186. finally:
  187. reset_hermes_home_override(token)
  188. def record_config_saved(old_raw: Any, new_config: Any) -> None:
  189. """``save_config``'s hook, after the write and outside its lock. Never raises."""
  190. if _process_surface is None or _hermes_write.get():
  191. return
  192. try:
  193. from hermes_constants import get_hermes_home
  194. from .relay_shared_metrics import enabled
  195. if not enabled() or (surface := current_surface()) is None:
  196. return
  197. # Not a daemon: a CLI command that exits right after its write still records.
  198. threading.Thread(
  199. target=_record, args=(copy.deepcopy(old_raw), copy.deepcopy(new_config), surface, str(get_hermes_home())),
  200. name="hermes-feature-disabled",
  201. ).start()
  202. except Exception:
  203. logger.debug("Feature-disabled not recorded", exc_info=True)
  204. def recording_raw_config_write(config_path: Any, user_config: Any, write) -> None:
  205. """``hermes config set/unset`` write the raw file directly (not via ``save_config``): diff the file
  206. they replace against what they write. The write itself runs unguarded, so its errors are the caller's."""
  207. before = None
  208. if _process_surface is not None:
  209. try:
  210. from .relay_shared_metrics import enabled
  211. if enabled():
  212. from hermes_cli.config import read_user_config_raw
  213. before = read_user_config_raw(config_path)
  214. except Exception:
  215. logger.debug("Config snapshot for feature-disabled skipped", exc_info=True)
  216. write(config_path, user_config)
  217. if before is not None:
  218. record_config_saved(before, user_config)
  219. def record_skill_removed(name: Any) -> None:
  220. """A catalog skill (bundled/optional) was uninstalled; third-party hub skills were never shipped."""
  221. if _process_surface is None:
  222. return
  223. try:
  224. from .relay_shared_metrics import enabled
  225. if not enabled() or (surface := current_surface()) is None:
  226. return
  227. if (metric_name := skill_metric_name(name)) != CUSTOM:
  228. _emit([("skill", metric_name, "disabled")], surface)
  229. except Exception:
  230. logger.debug("Skill removal not recorded", exc_info=True)