hermes-agent/hermes_cli/observability/shared_metrics_disabled.py

"""hermes.feature_disabled.count: a user turns off something Hermes ships on, or removes something shipped.

One chokepoint sees every write: ``save_config`` hands over the raw config it replaced and the one it
wrote, and :func:`config_transitions` diffs only what the user moved away from the shipped default
(or back to it): default-on toolsets, ``skills.disabled``, ``plugins.disabled`` and default-``True``
booleans. Names are public only when shipped (toolset key, bundled/catalog skill, bundled/catalog
plugin, ``DEFAULT_CONFIG`` key path; never a value); anything else reads ``custom``. The store counts
each (kind, name, event) at most once per day.

The surface is the entry point that is running: ``set_process_surface`` from the ``hermes`` command
dispatch (``tools`` / ``config`` / ``skills`` / ``plugins`` / chat slash commands / the web server) and
the TUI gateway. A process with no surface (setup wizard, updates) records nothing, nor does a write
Hermes makes itself inside a surfaced process (migrations, under :func:`hermes_applied_write`): those
are Hermes applying choices, not a user turning something off.

``save_config``'s callers may hold their own write lock (the dashboard's ``_CONFIG_MUTATION_LOCK``), so
the hook only runs the cheap gate inline; the diff and the record run on a thread bound to the owning
profile.
"""

from __future__ import annotations

import contextlib
import copy
import functools
import logging
import threading
from contextvars import ContextVar
from typing import Any, Iterable, Iterator

logger = logging.getLogger(__name__)

CUSTOM = "custom"
_COMMAND_SURFACES = {
    None: "cli_slash", "chat": "cli_slash", "tools": "cli_tools", "config": "cli_config",
    "skills": "cli_config", "plugins": "cli_config",
    "dashboard": "web", "serve": "web", "gui": "web", "desktop": "web",
}
_SETTING_KINDS = {"memory": "memory", "curator": "curator", "compression": "compression"}
_OFF = frozenset({"false", "off", "no", "0", "none", ""})
_process_surface: str | None = None
_hermes_write: ContextVar[bool] = ContextVar("hermes_feature_disabled_hermes_write", default=False)


def set_process_surface(command: Any) -> None:
    """Called once by the ``hermes`` dispatch (``command`` is the subcommand, None for chat) or the
    TUI gateway (``"tui_gateway"``). Unknown commands clear it."""
    global _process_surface
    _process_surface = "tui_gateway" if command == "tui_gateway" else _COMMAND_SURFACES.get(command)


def current_surface() -> str | None:
    surface = _process_surface
    if surface == "web":
        from .shared_metrics_setup import web_setup_surface

        return web_setup_surface()
    if surface == "tui_gateway":
        try:
            from tui_gateway.server import _resolve_session_platform

            return _resolve_session_platform()
        except Exception:
            return "tui"
    return surface


# ---- names -----------------------------------------------------------------------------------

@functools.cache
def _bundled_plugin_names() -> frozenset[str]:
    from .shared_metrics_catalog import _REPO_ROOT

    root = _REPO_ROOT / "plugins"
    try:
        return frozenset(
            p.parent.name.lower() for p in [*root.glob("*/plugin.yaml"), *root.glob("*/*/plugin.yaml")]
        )
    except OSError:
        return frozenset()


def plugin_metric_name(raw: Any) -> str:
    from .shared_metrics_catalog import _norm, _safe, plugin_catalog_names

    name = _norm(raw).rsplit("/", 1)[-1]
    return name if name and (name in _safe(_bundled_plugin_names) or name in _safe(plugin_catalog_names)) else CUSTOM


def skill_metric_name(raw: Any) -> str:
    from .shared_metrics_catalog import skill_metric_name as catalog_skill_name

    return catalog_skill_name(raw)


@functools.cache
def default_on_settings() -> frozenset[str]:
    """Dotted ``DEFAULT_CONFIG`` paths whose shipped value is ``True`` (the closed setting vocabulary)."""
    from hermes_cli.config import DEFAULT_CONFIG

    from .shared_metrics_contract import FEATURE_DISABLED_NAME_MAX_LENGTH, _metric_identifier

    paths: set[str] = set()

    def walk(node: Any, prefix: str) -> None:
        for key, value in node.items():
            if not isinstance(key, str) or key.startswith("_"):
                continue
            path = f"{prefix}{key}"
            if isinstance(value, dict):
                walk(value, f"{path}.")
            elif value is True and _metric_identifier(path, max_length=FEATURE_DISABLED_NAME_MAX_LENGTH) == path:
                paths.add(path)

    walk(DEFAULT_CONFIG, "")
    return frozenset(paths)


# ---- transitions -----------------------------------------------------------------------------

def _get(config: Any, path: str) -> Any:
    node = config
    for part in path.split("."):
        if not isinstance(node, dict) or part not in node:
            return True  # absent = the shipped default (True for every tracked path)
        node = node[part]
    return node


def _on(value: Any) -> bool:
    if isinstance(value, str):
        return value.strip().lower() not in _OFF
    return bool(value)


def _setting_transitions(old: dict, new: dict) -> Iterable[tuple[str, str, str]]:
    for path in sorted(default_on_settings()):
        before, after = _get(old, path), _get(new, path)
        if any(isinstance(value, str) and "${" in value for value in (before, after)):
            continue  # an unexpanded ``${VAR}`` template (the raw side): its value is unknown here
        before, after = _on(before), _on(after)
        if before != after:
            yield _SETTING_KINDS.get(path.split(".", 1)[0], "setting"), path, "re_enabled" if after else "disabled"


def _names(config: Any, section: str, key: str, *, per_platform: str | None = None) -> set[str]:
    from agent.skill_utils import parse_config_string_list

    block = config.get(section) if isinstance(config, dict) else None
    if not isinstance(block, dict):
        return set()
    names = set(parse_config_string_list(block.get(key)) or ())
    platforms = block.get(per_platform) if per_platform else None
    if isinstance(platforms, dict):
        for value in platforms.values():
            names |= set(parse_config_string_list(value) or ())
    return {str(n) for n in names}


def _plugin_kind(name: str) -> str:
    """A messaging-platform plugin (bundled or catalog) reports as a platform, other plugins as plugins."""
    from .shared_metrics_catalog import _safe, bundled_platform_names, catalog_platform_names

    platforms = _safe(bundled_platform_names) | _safe(catalog_platform_names)
    return "platform" if name.strip().lower().rsplit("/", 1)[-1] in platforms else "plugin"


def _list_transitions(old_names: set[str], new_names: set[str], kind: str, namer) -> Iterable[tuple[str, str, str]]:
    for names, event in ((new_names - old_names, "disabled"), (old_names - new_names, "re_enabled")):
        for name in sorted(names):
            yield (_plugin_kind(name) if kind == "plugin" else kind), namer(name), event


def _toolset_transitions(old: dict, new: dict) -> Iterable[tuple[str, str, str]]:
    def scope(config: dict) -> tuple[Any, Any]:
        agent = config.get("agent") if isinstance(config.get("agent"), dict) else {}
        return config.get("platform_toolsets"), agent.get("disabled_toolsets")

    if scope(old) == scope(new):
        return
    from hermes_cli.tools_config import _configurable_keys, _get_platform_tools

    platforms = {"cli"}
    for config in (old, new):
        if isinstance(config.get("platform_toolsets"), dict):
            platforms |= {str(p) for p in config["platform_toolsets"]}
    shipped = _configurable_keys()
    for platform in sorted(platforms):
        default = _get_platform_tools({}, platform, include_default_mcp_servers=False) & shipped
        before = _get_platform_tools(old, platform, include_default_mcp_servers=False)
        after = _get_platform_tools(new, platform, include_default_mcp_servers=False)
        for toolset in sorted(default):
            if (toolset in before) != (toolset in after):
                yield "toolset", toolset, "re_enabled" if toolset in after else "disabled"


def config_transitions(old: Any, new: Any) -> list[tuple[str, str, str]]:
    """(kind, name, event) for each shipped-on thing the write turned off or back on (deduped)."""
    old = old if isinstance(old, dict) else {}
    new = new if isinstance(new, dict) else {}
    found: list[tuple[str, str, str]] = []
    for batch in (
        _setting_transitions(old, new),
        _list_transitions(_names(old, "skills", "disabled", per_platform="platform_disabled"),
                          _names(new, "skills", "disabled", per_platform="platform_disabled"), "skill", skill_metric_name),
        _list_transitions(_names(old, "plugins", "disabled"), _names(new, "plugins", "disabled"), "plugin",
                          plugin_metric_name),
        _toolset_transitions(old, new),
    ):
        try:
            found.extend(t for t in batch if t not in found)
        except Exception:
            logger.debug("Feature-disabled transitions skipped", exc_info=True)
    return found


# ---- recording -------------------------------------------------------------------------------

def _emit(transitions: Iterable[tuple[str, str, str]], surface: str) -> None:
    from .relay_shared_metrics import record_process_mark
    from .shared_metrics_contract import FEATURE_DISABLED_MARK

    for kind, name, event in transitions:
        record_process_mark(FEATURE_DISABLED_MARK, {"event": event, "kind": kind, "name": name, "surface": surface})


@contextlib.contextmanager
def hermes_applied_write() -> Iterator[None]:
    """Config writes Hermes makes on its own (migrations) record nothing, whatever the surface."""
    token = _hermes_write.set(True)
    try:
        yield
    finally:
        _hermes_write.reset(token)


def _record(old: Any, new: Any, surface: str, home: str) -> None:
    from hermes_constants import reset_hermes_home_override, set_hermes_home_override

    token = set_hermes_home_override(home)  # a thread does not inherit the profile binding
    try:
        _emit(config_transitions(old, new), surface)
    except Exception:
        logger.debug("Feature-disabled not recorded", exc_info=True)
    finally:
        reset_hermes_home_override(token)


def record_config_saved(old_raw: Any, new_config: Any) -> None:
    """``save_config``'s hook, after the write and outside its lock. Never raises."""
    if _process_surface is None or _hermes_write.get():
        return
    try:
        from hermes_constants import get_hermes_home

        from .relay_shared_metrics import enabled

        if not enabled() or (surface := current_surface()) is None:
            return
        # Not a daemon: a CLI command that exits right after its write still records.
        threading.Thread(
            target=_record, args=(copy.deepcopy(old_raw), copy.deepcopy(new_config), surface, str(get_hermes_home())),
            name="hermes-feature-disabled",
        ).start()
    except Exception:
        logger.debug("Feature-disabled not recorded", exc_info=True)


def recording_raw_config_write(config_path: Any, user_config: Any, write) -> None:
    """``hermes config set/unset`` write the raw file directly (not via ``save_config``): diff the file
    they replace against what they write. The write itself runs unguarded, so its errors are the caller's."""
    before = None
    if _process_surface is not None:
        try:
            from .relay_shared_metrics import enabled

            if enabled():
                from hermes_cli.config import read_user_config_raw

                before = read_user_config_raw(config_path)
        except Exception:
            logger.debug("Config snapshot for feature-disabled skipped", exc_info=True)
    write(config_path, user_config)
    if before is not None:
        record_config_saved(before, user_config)


def record_skill_removed(name: Any) -> None:
    """A catalog skill (bundled/optional) was uninstalled; third-party hub skills were never shipped."""
    if _process_surface is None:
        return
    try:
        from .relay_shared_metrics import enabled

        if not enabled() or (surface := current_surface()) is None:
            return
        if (metric_name := skill_metric_name(name)) != CUSTOM:
            _emit([("skill", metric_name, "disabled")], surface)
    except Exception:
        logger.debug("Skill removal not recorded", exc_info=True)