skill_bundles.py 9.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213
  1. """Skill bundles — aliases that load multiple skills under one slash command.
  2. YAML files in ``<HERMES_HOME>/skill-bundles/`` (``name``, ``description``,
  3. ``skills: [...]``, optional ``instruction``; file stem = fallback name).
  4. ``/<bundle>`` loads every member skill into one user message. If a bundle and a
  5. skill share a slug, the bundle wins — slash dispatch checks bundles first, on purpose.
  6. """
  7. from __future__ import annotations
  8. import hashlib
  9. import logging
  10. import os
  11. from pathlib import Path
  12. from typing import Any, Dict, List, Optional, Tuple
  13. import hermes_yaml as yaml
  14. from hermes_constants import get_hermes_home
  15. from utils import atomic_write_text
  16. from agent.skill_commands import command_snapshot, diff_command_snapshots, resolve_slash_key, slugify_skill_name as _slugify
  17. logger = logging.getLogger(__name__)
  18. _bundles_cache: dict[str, dict[str, Any]] = {}
  19. _bundles_cache_mtime: Optional[tuple] = None # _bundles_sig() (content digests) of the cached scan
  20. def _bundles_dir() -> Path:
  21. """Bundles directory: ``HERMES_BUNDLES_DIR`` override (tests) or ``<HERMES_HOME>/skill-bundles``."""
  22. override = os.environ.get("HERMES_BUNDLES_DIR")
  23. return Path(override).expanduser() if override else get_hermes_home() / "skill-bundles"
  24. def _iter_bundle_files() -> list[Path]:
  25. base = _bundles_dir()
  26. return [f for ext in ("*.yaml", "*.yml") for f in sorted(base.glob(ext))] if base.exists() else []
  27. def _bundles_sig(files: list[Path]) -> tuple:
  28. """Sorted ``(path, content digest)`` of the bundle files. Content, not timestamps: a same-size
  29. rewrite within one coarse mtime/ctime tick, or under host/filesystem clock skew, still moves it.
  30. Bundles are a handful of small YAML files, so reading them per check is cheap."""
  31. entries = []
  32. for f in files:
  33. try:
  34. entries.append((str(f), hashlib.sha256(f.read_bytes()).hexdigest()))
  35. except OSError:
  36. continue
  37. return tuple(sorted(entries))
  38. def _load_bundle_file(path: Path) -> Optional[dict[str, Any]]:
  39. """Parse one bundle YAML; ``None`` (logged) on any error so a broken bundle can't break discovery."""
  40. try:
  41. data = yaml.safe_load(path.read_text(encoding="utf-8-sig"))
  42. except OSError as exc:
  43. logger.warning("Could not read bundle %s: %s", path, exc)
  44. return None
  45. except yaml.YAMLError as exc:
  46. logger.warning("Invalid YAML in bundle %s: %s", path, exc)
  47. return None
  48. def _skip(reason: str) -> None:
  49. logger.warning("Bundle %s %s; skipping", path, reason)
  50. if not isinstance(data, dict):
  51. return _skip("is not a mapping")
  52. name = str(data.get("name") or path.stem).strip()
  53. if not name:
  54. return _skip("has no name")
  55. raw_skills = data.get("skills") or []
  56. if not isinstance(raw_skills, list) or not raw_skills:
  57. return _skip("has no skills list")
  58. skills = [str(s).strip() for s in raw_skills if str(s).strip()]
  59. if not skills:
  60. return _skip("has empty skills list")
  61. slug = _slugify(name)
  62. if not slug:
  63. return _skip("yielded empty slug")
  64. return {
  65. "name": name, "slug": slug, "skills": skills, "path": str(path),
  66. "description": str(data.get("description") or "").strip() or f"Load {len(skills)} skills as a bundle",
  67. "instruction": str(data.get("instruction") or "").strip(),
  68. }
  69. def scan_bundles() -> dict[str, dict[str, Any]]:
  70. """Rebuild the ``"/slug"`` -> bundle info cache; duplicate slugs keep the first (alphabetical)."""
  71. global _bundles_cache, _bundles_cache_mtime
  72. files = _iter_bundle_files()
  73. # Stamp BEFORE parsing: a write landing mid-scan must leave the stamp stale, not match it.
  74. sig = _bundles_sig(files)
  75. out: dict[str, dict[str, Any]] = {}
  76. for f in files:
  77. info = _load_bundle_file(f)
  78. if not info:
  79. continue
  80. key = f"/{info['slug']}"
  81. if key in out:
  82. logger.warning("Duplicate bundle slug %s from %s; keeping %s", key, f, out[key]["path"])
  83. continue
  84. out[key] = info
  85. _bundles_cache = out
  86. _bundles_cache_mtime = sig
  87. return out
  88. def get_skill_bundles() -> dict[str, dict[str, Any]]:
  89. """Current bundle mapping; rescans only when the set of bundle files or their content changed."""
  90. current_mtime = _bundles_sig(_iter_bundle_files())
  91. if not _bundles_cache or _bundles_cache_mtime != current_mtime:
  92. scan_bundles()
  93. return _bundles_cache
  94. def resolve_bundle_command_key(command: str) -> Optional[str]:
  95. """Resolve a user-typed command to its ``/slug`` key (``_`` ≡ ``-``, as Telegram rewrites hyphens)."""
  96. return resolve_slash_key(command, get_skill_bundles())
  97. def reload_bundles() -> dict[str, Any]:
  98. """Re-scan and return an ``added``/``removed``/``unchanged``/``total`` diff (same shape as reload_skills)."""
  99. before = command_snapshot(_bundles_cache)
  100. return diff_command_snapshots(before, command_snapshot(scan_bundles()))
  101. def list_bundles() -> list[dict[str, Any]]:
  102. """Return a sorted list of bundle info dicts for display."""
  103. return sorted(get_skill_bundles().values(), key=lambda b: b["slug"])
  104. def build_bundle_invocation_message(
  105. cmd_key: str, user_instruction: str = "", task_id: str | None = None, platform: str | None = None,
  106. ) -> Optional[tuple[str, list[str], list[str]]]:
  107. """Build the user message for a bundle invocation: ``(message,
  108. loaded_skill_names, missing_skill_names)`` or ``None`` if the bundle wasn't
  109. found. Uninstalled members are skipped with a note; disabled ones too, since
  110. ``_load_skill_payload`` bypasses the scan-time filter (``platform`` scopes
  111. that check — gateway passes it, None resolves from env).
  112. Disabled skills are also skipped: bundles load members via ``_load_skill_payload`` directly, bypassing
  113. the scan-time disabled filter in ``get_skill_commands()``, so the disabled list must be re-applied here.
  114. ``platform`` scopes the check to a specific platform's ``skills.platform_disabled`` config (gateway
  115. dispatch passes it explicitly because the gateway handles multiple platforms in one process); when
  116. *None*, the platform resolves from session env vars and the global disabled list still applies. Mirrors
  117. the stacked-skill gate in gateway dispatch (#58888).
  118. """
  119. info = get_skill_bundles().get(cmd_key)
  120. if not info:
  121. return None
  122. # Late import keeps skill_bundles cheap to import (no tools/* at import time).
  123. from agent.skill_commands import _disabled_skill_names, _load_skill_blocks, _load_skill_payload, _scaffold_header
  124. bundle_name = info["name"]
  125. loaded_names, missing, disabled, skill_blocks = _load_skill_blocks(
  126. [(skill_id or "").strip() for skill_id in info["skills"]],
  127. lambda identifier: _load_skill_payload(identifier, task_id=task_id),
  128. lambda _name: f'[Loaded as part of the "{bundle_name}" skill bundle.]',
  129. task_id,
  130. disabled_names=_disabled_skill_names(platform),
  131. )
  132. if not skill_blocks:
  133. return None
  134. header = _scaffold_header(
  135. f'"{bundle_name}" skill bundle', loaded_names, lead_lines=[f"Bundle: {bundle_name}"], missing=missing,
  136. disabled=disabled, extra_instruction=info.get("instruction") or "", user_instruction=user_instruction,
  137. )
  138. return ("\n\n".join([header, *skill_blocks]), loaded_names, missing)
  139. # File-level CRUD — used by `hermes bundles`.
  140. def bundle_path_for(name: str) -> Path:
  141. """Return the canonical filesystem path for a bundle name."""
  142. slug = _slugify(name)
  143. if not slug:
  144. raise ValueError(f"Bundle name {name!r} normalizes to an empty slug")
  145. return _bundles_dir() / f"{slug}.yaml"
  146. def save_bundle(name: str, skills: list[str], description: str = "", instruction: str = "", overwrite: bool = False) -> Path:
  147. """Write a bundle to disk and refresh the cache. Raises ``FileExistsError``
  148. if the target exists and not ``overwrite``; ``ValueError`` for unusable inputs."""
  149. name = (name or "").strip()
  150. if not name:
  151. raise ValueError("Bundle name is required")
  152. cleaned_skills = [str(s).strip() for s in skills if str(s).strip()]
  153. if not cleaned_skills:
  154. raise ValueError("Bundle must reference at least one skill")
  155. path = bundle_path_for(name)
  156. if path.exists() and not overwrite:
  157. raise FileExistsError(f"Bundle already exists at {path}")
  158. path.parent.mkdir(parents=True, exist_ok=True)
  159. payload: dict[str, Any] = {"name": name, "skills": cleaned_skills}
  160. payload.update({k: v for k, v in (("description", description), ("instruction", instruction)) if v})
  161. # Atomic: a gateway process scanning mid-write must never parse a truncated bundle.
  162. atomic_write_text(path, yaml.safe_dump(payload, sort_keys=False, allow_unicode=True), preserve_mode=True)
  163. scan_bundles()
  164. return path
  165. def delete_bundle(name: str) -> Path:
  166. """Delete a bundle by name and return its path; ``FileNotFoundError`` if absent."""
  167. path = bundle_path_for(name)
  168. if not path.exists():
  169. raise FileNotFoundError(f"No bundle at {path}")
  170. path.unlink()
  171. scan_bundles()
  172. return path
  173. def get_bundle(name: str) -> Optional[dict[str, Any]]:
  174. """Look up a bundle by name (slug-normalized)."""
  175. return get_skill_bundles().get(f"/{_slugify(name)}")