skill_utils.py 40 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906
  1. """Lightweight skill metadata utilities shared by prompt_builder and skills_tool.
  2. Import-light by design: no tool registry, CLI config, or provider resolution."""
  3. import ast
  4. import hashlib
  5. import logging
  6. import os
  7. import re
  8. import sys
  9. import threading
  10. from pathlib import Path, PurePath
  11. from typing import Any, Callable, Dict, List, Optional, Set, Tuple
  12. from hermes_constants import (
  13. get_config_path,
  14. get_skills_dir,
  15. get_subprocess_home,
  16. )
  17. logger = logging.getLogger(__name__)
  18. PLATFORM_MAP = {"macos": "darwin", "linux": "linux", "windows": "win32"}
  19. # Where profile-distribution installs stage and set aside a dir they swap in (same parent, so the
  20. # rename stays atomic); a backup a lock keeps there must never be discovered as a second copy.
  21. DIST_SWAP_DIR = ".hermes-dist"
  22. EXCLUDED_SKILL_DIRS = frozenset((
  23. ".git", ".github", ".hub", ".archive", ".curator_backups", ".locks", DIST_SWAP_DIR,
  24. ".venv", "venv", "node_modules", "site-packages", "__pycache__",
  25. ".tox", ".nox", ".pytest_cache", ".mypy_cache", ".ruff_cache",
  26. ))
  27. # Progressive-disclosure support dirs inside a skill package: loaded explicitly
  28. # via skill_view(skill, file_path=...), never scanned as standalone skills.
  29. SKILL_SUPPORT_DIRS = frozenset(("references", "templates", "assets", "scripts"))
  30. def is_excluded_skill_path(path, *, root: Optional[Path] = None) -> bool:
  31. """True if *path* should be skipped by skill scanners (VCS/dependency/cache
  32. dirs + support packages). Apply to every SKILL.md from a direct ``rglob``."""
  33. parts = PurePath(str(path)).parts
  34. return any(part in EXCLUDED_SKILL_DIRS for part in parts) or is_skill_support_path(path, root=root)
  35. def is_skill_support_path(path, *, root: Optional[Path] = None) -> bool:
  36. """True if *path* is under a support dir sitting directly inside a skill root
  37. (``skills/scripts/foo`` stays discoverable: no ``SKILL.md`` above ``scripts``)."""
  38. path_obj = path if isinstance(path, Path) else Path(str(path))
  39. parts = path_obj.parts
  40. base = root if root is not None and not path_obj.is_absolute() else Path()
  41. # Only components before the leaf can be containing support directories.
  42. return any(
  43. part in SKILL_SUPPORT_DIRS and (base / Path(*parts[:idx]) / "SKILL.md").exists()
  44. for idx, part in enumerate(parts[:-1])
  45. if idx > 0
  46. )
  47. _yaml_load_fn = None
  48. def yaml_load(content: str):
  49. """Parse YAML with the shared safe loader, imported lazily."""
  50. global _yaml_load_fn
  51. if _yaml_load_fn is None:
  52. from hermes_yaml import safe_load
  53. _yaml_load_fn = safe_load
  54. return _yaml_load_fn(content)
  55. def parse_frontmatter(content: str) -> tuple[dict[str, Any], str]:
  56. """Parse YAML frontmatter from markdown; returns (frontmatter_dict, body).
  57. Malformed YAML falls back to key:value line splitting. A leading UTF-8 BOM
  58. (Windows editors) is stripped first or it would defeat the ``---`` fence check."""
  59. content = content.removeprefix("\ufeff")
  60. end_match = re.search(r"\n---\s*\n", content[3:]) if content.startswith("---") else None
  61. if not end_match:
  62. return {}, content
  63. yaml_content = content[3 : end_match.start() + 3]
  64. body = content[end_match.end() + 3 :]
  65. frontmatter: dict[str, Any] = {}
  66. try:
  67. parsed = yaml_load(yaml_content)
  68. if isinstance(parsed, dict):
  69. frontmatter = parsed
  70. except Exception:
  71. for line in yaml_content.strip().split("\n"):
  72. if ":" in line:
  73. key, value = line.split(":", 1)
  74. frontmatter[key.strip()] = value.strip()
  75. return frontmatter, body
  76. def skill_matches_platform_list(platforms: Any) -> bool:
  77. """Return True when *platforms* is compatible with the current OS."""
  78. if not platforms:
  79. return True
  80. if not isinstance(platforms, list):
  81. platforms = [platforms]
  82. current = sys.platform
  83. for platform in platforms:
  84. normalized = str(platform).lower().strip()
  85. mapped = PLATFORM_MAP.get(normalized, normalized)
  86. if current.startswith(mapped):
  87. return True
  88. return False
  89. def skill_matches_platform(frontmatter: dict[str, Any]) -> bool:
  90. """True when the skill's ``platforms:`` list (absent = all) matches this OS."""
  91. return skill_matches_platform_list(frontmatter.get("platforms"))
  92. # An ``environments:`` tag is a *relevance* gate for offer surfaces (index,
  93. # autocomplete, slash commands), not a compatibility gate: an explicit load
  94. # (skill_view, --skills) always succeeds. Detection is cached per process.
  95. _ENV_DETECT_CACHE: dict[str, bool] = {}
  96. def _detect_kanban() -> bool:
  97. # Mirror tools/kanban_tools.py: a dispatcher-spawned worker (env vars, but
  98. # only when this execution OWNS the task — delegate children / in-process
  99. # cron see the worker's vars) or a profile opted into the kanban toolset.
  100. if os.getenv("HERMES_KANBAN_TASK") or os.getenv("HERMES_KANBAN_BOARD"):
  101. try:
  102. from agent.delegation_context import is_dispatcher_owned_worker_context
  103. owned = is_dispatcher_owned_worker_context()
  104. except Exception:
  105. owned = True
  106. if owned:
  107. return True
  108. try:
  109. from tools.kanban_tools import _profile_has_kanban_toolset
  110. return bool(_profile_has_kanban_toolset())
  111. except Exception:
  112. return False
  113. def _detect_docker() -> bool:
  114. try:
  115. from hermes_constants import is_container
  116. return is_container()
  117. except Exception:
  118. return False
  119. _ENV_DETECTORS: dict[str, Callable[[], bool]] = {
  120. "kanban": _detect_kanban, "docker": _detect_docker,
  121. "s6": lambda: os.path.isdir("/run/s6") or os.path.isdir("/package/admin/s6-overlay"), # s6-overlay is PID 1 in the image
  122. }
  123. def _detect_environment(env: str) -> bool:
  124. """True when the named runtime environment is active (unknown => True).
  125. Cached per process EXCEPT ``kanban``: that verdict is context-dependent
  126. (delegate children / in-process cron see the worker's vars), so a
  127. process-wide cache would leak the first asker's answer to the others."""
  128. if env != "kanban" and env in _ENV_DETECT_CACHE:
  129. return _ENV_DETECT_CACHE[env]
  130. detector = _ENV_DETECTORS.get(env)
  131. result = detector() if detector else True
  132. _ENV_DETECT_CACHE[env] = result
  133. return result
  134. def skill_matches_environment(frontmatter: dict[str, Any]) -> bool:
  135. """True when ANY declared ``environments:`` tag is active (absent = all;
  136. unknown tags fail open). Offer-time filter only."""
  137. environments = frontmatter.get("environments")
  138. if not environments:
  139. return True
  140. tags = [str(env).lower().strip() for env in (environments if isinstance(environments, list) else [environments])]
  141. return any(_detect_environment(tag) for tag in tags if tag)
  142. def skill_matches_apps(frontmatter: dict[str, Any]) -> bool:
  143. """True when every app named in ``requires_apps:`` has a registered declaration this host satisfies.
  144. Names resolve through ``hermes_platform.declaration`` (registered by whoever owns the server,
  145. e.g. the plugin loader); the check is the same ``availability()`` the MCP check_fn uses. An
  146. unknown name hides the skill (fail closed). Offer-time filter, like ``environments:``.
  147. """
  148. names = frontmatter.get("requires_apps")
  149. if not names:
  150. return True
  151. from hermes_platform import declaration
  152. from hermes_platform.resolver.availability import availability
  153. for name in names if isinstance(names, list) else [names]:
  154. decl = declaration.lookup(str(name).strip())
  155. if decl is None or decl.app is None:
  156. return False
  157. if not availability(decl).offerable:
  158. return False
  159. return True
  160. _RAW_CONFIG_CACHE: dict[tuple[str, int, int, int, int], dict[str, Any]] = {}
  161. # A multiplexed watcher rotates through up to ~32 published profile/project scopes plus
  162. # the ambient one (#141610), so a miss must not drop the whole cache — only a stale
  163. # signature entry. The bound retires entries a config's own edits leave behind.
  164. _RAW_CONFIG_CACHE_MAX = 128
  165. # Guards every cache read/publish/evict: concurrent tool threads share it, and an unlocked
  166. # ``pop(next(iter(...)))`` races another thread's insert (RuntimeError) or pop (KeyError).
  167. _RAW_CONFIG_CACHE_LOCK = threading.Lock()
  168. def _raw_config_cache_clear() -> None:
  169. """Test hook — drop the shared raw config cache."""
  170. with _RAW_CONFIG_CACHE_LOCK:
  171. _RAW_CONFIG_CACHE.clear()
  172. def _config_cache_key(config_path: Path) -> Optional[tuple[Any, ...]]:
  173. """``(path, *backend cache version)`` identity of config.yaml, or None when unreadable/absent."""
  174. from hermes_cli.config_backend import config_cache_version_or_none
  175. version = config_cache_version_or_none(config_path)
  176. return None if version is None else (str(config_path), *version)
  177. def _load_raw_config() -> dict[str, Any]:
  178. """Read config.yaml with a version-keyed cache (no hermes_cli.config import)."""
  179. from agent.safe_worker_policy import worker_config_snapshot
  180. from hermes_cli.config_backend import config_exists, read_config_doc
  181. snapshot = worker_config_snapshot()
  182. if snapshot is not None:
  183. return snapshot
  184. config_path = get_config_path()
  185. if not config_exists(config_path):
  186. return {}
  187. cache_key = _config_cache_key(config_path)
  188. with _RAW_CONFIG_CACHE_LOCK:
  189. cached = _RAW_CONFIG_CACHE.get(cache_key) if cache_key is not None else None
  190. if cached is not None:
  191. return cached
  192. try:
  193. parsed = read_config_doc(config_path)
  194. except Exception as e:
  195. logger.debug("Could not read skill config %s: %s", config_path, e)
  196. return {}
  197. if not isinstance(parsed, dict):
  198. return {}
  199. if cache_key is not None:
  200. with _RAW_CONFIG_CACHE_LOCK:
  201. _RAW_CONFIG_CACHE[cache_key] = parsed
  202. while len(_RAW_CONFIG_CACHE) > _RAW_CONFIG_CACHE_MAX:
  203. _RAW_CONFIG_CACHE.pop(next(iter(_RAW_CONFIG_CACHE)))
  204. return parsed
  205. def _skills_cfg() -> Optional[dict[str, Any]]:
  206. """The ``skills:`` mapping from config.yaml, or None when absent/malformed."""
  207. skills_cfg = _load_raw_config().get("skills")
  208. return skills_cfg if isinstance(skills_cfg, dict) else None
  209. def _skills_cfg_get(key: str) -> Any:
  210. """``skills.<key>`` from config.yaml, or None when the section is absent/malformed."""
  211. skills_cfg = _skills_cfg()
  212. return skills_cfg.get(key) if skills_cfg is not None else None
  213. def _expand_path(entry: str) -> Path:
  214. """Expand ``~`` and ``${VAR}`` in a config path entry."""
  215. return Path(os.path.expanduser(os.path.expandvars(entry)))
  216. def _home_relative(p: Path) -> Path:
  217. """Anchor a relative config path at HERMES_HOME; absolute paths pass through."""
  218. from hermes_constants import get_hermes_home
  219. return p if p.is_absolute() else get_hermes_home() / p
  220. # Never disableable: `hermes-agent` is the agent's own operating manual and the
  221. # system prompt points at it unconditionally.
  222. ESSENTIAL_SKILLS: frozenset = frozenset({"hermes-agent"})
  223. def get_disabled_skill_names(platform: str | None = None) -> set[str]:
  224. """Disabled skill names from config.yaml: global list ∪ platform list
  225. (*platform* defaults to ``HERMES_PLATFORM`` / ``HERMES_SESSION_PLATFORM``)."""
  226. skills_cfg = _skills_cfg()
  227. if skills_cfg is None:
  228. return set()
  229. from gateway.session_context import get_session_env
  230. resolved_platform = platform or os.getenv("HERMES_PLATFORM") or get_session_env("HERMES_SESSION_PLATFORM")
  231. disabled = _normalize_string_set(skills_cfg.get("disabled"))
  232. platform_disabled = (skills_cfg.get("platform_disabled") or {}).get(resolved_platform) if resolved_platform else None
  233. if platform_disabled is not None:
  234. disabled |= _normalize_string_set(platform_disabled)
  235. return disabled - ESSENTIAL_SKILLS
  236. def parse_config_string_list(value) -> list[str]:
  237. """Normalize a config value that may hold a JSON-array string into a list.
  238. ``hermes config set`` stores lists as quoted JSON/Python-literal strings;
  239. treating one as a single name would silently filter nothing. A scalar
  240. string still means one name.
  241. See #13026, #86661.
  242. """
  243. if isinstance(value, str):
  244. if value.strip().startswith("["):
  245. try:
  246. parsed = ast.literal_eval(value.strip())
  247. except (ValueError, SyntaxError):
  248. parsed = None
  249. if isinstance(parsed, list):
  250. return [str(item) for item in parsed]
  251. return [value]
  252. return [str(item) for item in value] if isinstance(value, (list, tuple, set, frozenset)) else []
  253. def _normalize_string_set(values) -> set[str]:
  254. return {name.strip() for name in parse_config_string_list(values) if name.strip()}
  255. # config identity -> resolved external dirs. Called once per skill during
  256. # banner / tool-registry scans; re-resolving each time dominated cold-start.
  257. _EXTERNAL_DIRS_CACHE: dict[tuple[str, int, int, int, int], list[Path]] = {}
  258. def _external_dirs_cache_clear() -> None:
  259. """Test hook — drop the in-process cache."""
  260. _EXTERNAL_DIRS_CACHE.clear()
  261. _raw_config_cache_clear()
  262. def _config_str_list(raw) -> list[str]:
  263. """A scalar-or-list config entry as a list of stripped non-empty strings."""
  264. if isinstance(raw, str):
  265. raw = [raw]
  266. if not isinstance(raw, list):
  267. return []
  268. return [e for e in (str(entry).strip() for entry in raw) if e]
  269. def get_external_skills_dirs() -> list[Path]:
  270. """Validated, deduplicated ``skills.external_dirs`` (existing dirs only). Entries
  271. are ``~``/``${VAR}`` expanded, relative to HERMES_HOME; the local skills dir is skipped."""
  272. from hermes_cli.config_backend import config_exists
  273. config_path = get_config_path()
  274. if not config_exists(config_path):
  275. return []
  276. full_key = _config_cache_key(config_path)
  277. cache_key = full_key
  278. cached = _EXTERNAL_DIRS_CACHE.get(cache_key) if cache_key is not None else None
  279. if cached is not None:
  280. return list(cached) # copy so callers can't mutate the cache
  281. skills_cfg = _skills_cfg()
  282. if skills_cfg is None:
  283. return []
  284. local_skills = get_skills_dir().resolve()
  285. result: list[Path] = []
  286. for entry in _config_str_list(skills_cfg.get("external_dirs")):
  287. p = _home_relative(_expand_path(entry)).resolve()
  288. if p == local_skills or p in result:
  289. continue
  290. if p.is_dir():
  291. result.append(p)
  292. else:
  293. logger.debug("External skills dir does not exist, skipping: %s", p)
  294. if cache_key is not None:
  295. _EXTERNAL_DIRS_CACHE[cache_key] = list(result)
  296. return result
  297. def get_skill_create_dir() -> Optional[Path]:
  298. """Configured ``skills.create_dir`` (need not exist yet), or None when unset;
  299. relative to HERMES_HOME; a value equal to the local skills dir counts as unset."""
  300. raw = _skills_cfg_get("create_dir")
  301. entry = str(raw).strip() if raw and isinstance(raw, (str, os.PathLike)) else ""
  302. if not entry:
  303. return None
  304. p = _home_relative(_expand_path(entry))
  305. try:
  306. resolved = p.resolve()
  307. except OSError:
  308. resolved = p
  309. try:
  310. if resolved == get_skills_dir().resolve():
  311. return None
  312. except OSError:
  313. pass
  314. return resolved
  315. def display_skill_create_dir() -> str:
  316. """User-facing path where new skills are created (``~/`` shorthand when
  317. possible); tool schema descriptions and prompts follow ``skills.create_dir``."""
  318. from hermes_constants import display_hermes_home
  319. create_dir = get_skill_create_dir()
  320. if create_dir is None:
  321. return f"{display_hermes_home()}/skills/"
  322. if create_dir.is_relative_to(Path.home()):
  323. return "~/" + create_dir.relative_to(Path.home()).as_posix() + "/"
  324. return create_dir.as_posix() + "/"
  325. # Cross-directory precedence, lowest tier wins: trusted project > local profile > skills.create_dir >
  326. # skills.external_dirs. Inside ONE tier two different skills sharing a name stay ambiguous — refused,
  327. # never guessed (59da8ec4e) — while identical copies under one root resolve to the shallowest.
  328. TIER_PROJECT, TIER_LOCAL, TIER_CREATE_DIR, TIER_EXTERNAL = range(4)
  329. # Leading words of every same-tier refusal (skill_view error, preload/cron label) — one spelling.
  330. AMBIGUOUS_SKILL_PREFIX = "Ambiguous skill name "
  331. # (shadowed path, *sorted higher-tier paths) already judged: the identity check (it hashes both
  332. # SKILL.md files) and its one-time warning run once per pairing, not on every catalog resolve.
  333. _SHADOW_CHECKED: set[tuple[str, ...]] = set()
  334. def get_skill_search_roots(local: Optional[Path] = None, *, include_project: bool = True) -> list[tuple[int, Path]]:
  335. """``(tier, dir)`` for every skill root in precedence order — the ONE ordering the skills list,
  336. prompt index, slash commands, skill_view, preload and cron share. *local* overrides the profile
  337. skills dir (skills_tool passes its live root); that entry is kept even when missing."""
  338. from agent.runtime_context import current
  339. if current() is not None:
  340. import native_skills
  341. return [(TIER_LOCAL, native_skills.root())] if native_skills.root() else []
  342. roots = [(TIER_PROJECT, d) for d in get_project_skills_dirs()] if include_project else []
  343. roots.append((TIER_LOCAL, Path(local) if local is not None else get_skills_dir()))
  344. create_dir = get_skill_create_dir()
  345. if create_dir is not None and create_dir.is_dir():
  346. roots.append((TIER_CREATE_DIR, create_dir))
  347. roots += [(TIER_EXTERNAL, d) for d in get_external_skills_dirs()]
  348. seen: set[Path] = set()
  349. return [(t, d) for t, d in roots if not (d in seen or seen.add(d))]
  350. def get_all_skills_dirs() -> list[Path]:
  351. """Skill dirs: local ``~/.hermes/skills/`` first, then create_dir, then external.
  352. Trusted project dirs are NOT included (higher precedence; see get_project_skills_dirs)."""
  353. return [d for _tier, d in get_skill_search_roots(include_project=False)]
  354. def provably_same_skill(skill_mds) -> bool:
  355. """True only when every path is the SAME skill: one resolved file (symlink view) or byte-identical
  356. content (copy). Anything else is two different skills sharing a name, and picking one by depth
  357. would let ``<root>/evil`` (``name: github``) shadow the real one."""
  358. try:
  359. if len({os.path.realpath(p) for p in skill_mds}) == 1:
  360. return True
  361. return len({hashlib.sha256(Path(p).read_bytes()).hexdigest() for p in skill_mds}) == 1
  362. except OSError:
  363. return False
  364. def skill_candidate_rank(skill_md, root) -> tuple[bool, int]:
  365. """Same-root order of identical copies: a real SKILL.md beats a legacy flat ``<name>.md``,
  366. then the shallower path wins (shared by skill_view and :func:`resolve_skill_catalog`)."""
  367. skill_md = Path(skill_md)
  368. return (skill_md.name != "SKILL.md", len(skill_md.relative_to(root).parts))
  369. def pick_skill_candidate(candidates) -> tuple[Optional[int], list[int]]:
  370. """Winner index among one identifier's ``(tier, root, rank, skill_md)`` candidates, plus the
  371. winning tier's contender indexes. The lowest tier wins; inside it a lone candidate wins, identical
  372. copies under one root resolve to the strictly best ``rank``, anything else is ambiguous (None)."""
  373. top = min(c[0] for c in candidates)
  374. contenders = [i for i, c in enumerate(candidates) if c[0] == top]
  375. if len(contenders) > 1 and len({candidates[i][1] for i in contenders}) == 1 and provably_same_skill(
  376. [candidates[i][3] for i in contenders]):
  377. ranked = sorted(contenders, key=lambda i: candidates[i][2])
  378. if candidates[ranked[0]][2] != candidates[ranked[1]][2]:
  379. return ranked[0], contenders
  380. return (contenders[0] if len(contenders) == 1 else None), contenders
  381. def is_disabled_entry(entry: dict[str, Any], disabled: set[str]) -> bool:
  382. """``skills.disabled`` matches a resolved catalog entry by its declared name OR its ``load_name`` —
  383. the exact path a same-tier duplicate's list/config/web row shows (``a/one``) and saves. A unique
  384. copy elsewhere that merely sits at the same relative path is not matched."""
  385. return not disabled.isdisjoint({str(entry["name"]), entry.get("load_name")} - {None})
  386. def resolve_skill_catalog(entries: list[dict[str, Any]]) -> list[dict[str, Any]]:
  387. """Copies of scanned skills (each with ``name``, ``tier``, ``root`` and ``path`` = its SKILL.md)
  388. annotated with what skill_view() resolves, using its aliases (declared name, directory name, path
  389. relative to the root) and :func:`pick_skill_candidate`. Adds ``relative_path`` and ``status``:
  390. ``unique`` (``load_name`` = name), ``ambiguous`` (``load_name`` = the exact relative path, or None
  391. when even that is shared) or ``shadowed`` (a higher tier owns the name: hidden, warned once)."""
  392. out = [dict(e) for e in entries]
  393. owners: dict[str, list[int]] = {}
  394. for i, e in enumerate(out):
  395. skill_dir = Path(e["path"]).parent
  396. e["relative_path"] = skill_dir.relative_to(e["root"]).as_posix()
  397. for alias in {str(e["name"]), skill_dir.name, e["relative_path"]}:
  398. owners.setdefault(alias, []).append(i)
  399. winner: dict[str, Optional[int]] = {}
  400. for alias, idxs in owners.items():
  401. won, _ = pick_skill_candidate([
  402. (out[j]["tier"], str(out[j]["root"]), skill_candidate_rank(out[j]["path"], out[j]["root"]), out[j]["path"])
  403. for j in idxs])
  404. winner[alias] = None if won is None else idxs[won]
  405. for i, e in enumerate(out):
  406. name, rel = str(e["name"]), e["relative_path"]
  407. higher = [j for j in owners[name] if out[j]["tier"] < e["tier"]]
  408. if higher or winner[name] not in (None, i): # lower tier, or an identical same-root copy
  409. e.update(status="shadowed", load_name=None)
  410. # A symlink view or byte-identical copy of the winner hides nothing worth a warning.
  411. key = (str(e["path"]), *sorted(str(out[j]["path"]) for j in higher))
  412. if higher and key not in _SHADOW_CHECKED:
  413. _SHADOW_CHECKED.add(key)
  414. if not any(provably_same_skill([e["path"], out[j]["path"]]) for j in higher):
  415. logger.warning("Skill '%s' at %s is shadowed by a higher-precedence copy "
  416. "(project > local > create_dir > external_dirs)", name, e["path"])
  417. elif winner[name] == i:
  418. e.update(status="unique", load_name=name)
  419. else:
  420. e.update(status="ambiguous", load_name=rel if winner[rel] == i else None)
  421. return out
  422. # Project-local skills (<root>/.hermes/skills, <root>/.agents/skills; root = nearest
  423. # .git ancestor) are a prompt-injection vector if auto-sourced from any clone, so
  424. # they load only when the root is in ``skills.trusted_project_dirs``; then they
  425. # override same-named profile/bundled skills. cwd + trust list are session-fixed
  426. # so the skills index stays byte-stable.
  427. PROJECT_SKILLS_SUBDIRS = (os.path.join(".hermes", "skills"), os.path.join(".agents", "skills"))
  428. _PROJECT_ROOT_MAX_DEPTH = 64 # walk-up bound for pathological cwds
  429. def find_project_root(start: Optional[Path] = None) -> Optional[Path]:
  430. """Nearest ancestor containing ``.git`` (dir or worktree file), or None.
  431. Without *start*, the surface's effective working directory wins over the process cwd — the same
  432. ladder every other cwd consumer reads (``resolve_agent_cwd``: session-bound cwd, then the scope's
  433. ``TERMINAL_CWD``, then the process cwd). The session cwd comes first because a multi-session host
  434. (TUI/desktop gateway) pins each session's workspace there while its terminal scope resolves a
  435. placeholder ``terminal.cwd`` to ``$HOME``; reading only the scope made every project skill invisible
  436. on those surfaces (#114359). ``TERMINAL_CWD`` is the per-surface workdir the terminal tool and cron
  437. jobs use (a cron job sets it from its per-job ``workdir`` without chdir'ing the scheduler process),
  438. which lets non-interactive surfaces inherit a prior interactive trust decision by project identity —
  439. and a surface with no workdir in a trusted repo simply resolves no project and loads nothing (#48975).
  440. """
  441. try:
  442. if start is None:
  443. from agent.runtime_cwd import resolve_agent_cwd
  444. start = resolve_agent_cwd()
  445. cur = Path(start).resolve()
  446. except OSError:
  447. return None
  448. home = Path.home().resolve()
  449. try:
  450. for _ in range(_PROJECT_ROOT_MAX_DEPTH):
  451. if (cur / ".git").exists():
  452. # A dotfiles checkout AT home would make every session
  453. # project-scoped; treat home itself as non-project.
  454. return None if cur == home else cur
  455. if cur.parent == cur:
  456. return None
  457. cur = cur.parent
  458. except OSError:
  459. pass
  460. return None
  461. def _project_trusted_dirs_from_config() -> set[Path]:
  462. """Resolved set of trusted project roots from ``skills.trusted_project_dirs``."""
  463. result: set[Path] = set()
  464. for entry in _config_str_list(_skills_cfg_get("trusted_project_dirs")):
  465. try:
  466. result.add(_expand_path(entry).resolve())
  467. except OSError:
  468. continue
  469. return result
  470. def is_project_root_trusted(root: Path) -> bool:
  471. """True when *root* is listed in ``skills.trusted_project_dirs``."""
  472. try:
  473. return Path(root).resolve() in _project_trusted_dirs_from_config()
  474. except OSError:
  475. return False
  476. def _candidate_project_skills_dirs(root: Path) -> list[Path]:
  477. """Existing skill dirs under *root*, excluding the profile's own skills dir
  478. (HERMES_HOME itself may live inside a git checkout)."""
  479. local_skills = get_skills_dir().resolve()
  480. dirs: list[Path] = []
  481. for cand in (root / sub for sub in PROJECT_SKILLS_SUBDIRS):
  482. try:
  483. if cand.is_dir() and cand.resolve() != local_skills:
  484. dirs.append(cand.resolve())
  485. except OSError:
  486. continue
  487. return dirs
  488. def _current_project_root(trusted: bool) -> Optional[Path]:
  489. """cwd's project root when discovery is on and its trust state == *trusted*."""
  490. if _skills_cfg_get("project_discovery") is False:
  491. return None
  492. root = find_project_root()
  493. return root if root is not None and is_project_root_trusted(root) == trusted else None
  494. def get_project_skills_dirs() -> list[Path]:
  495. """Trusted project-local skill dirs for the current cwd (may be empty)."""
  496. root = _current_project_root(trusted=True)
  497. return _candidate_project_skills_dirs(root) if root is not None else []
  498. def get_untrusted_project_skills_root() -> Optional[tuple[Path, int]]:
  499. """(root, skill_count) when cwd's project has skills but is NOT trusted, else None."""
  500. root = _current_project_root(trusted=False)
  501. count = 0
  502. for d in _candidate_project_skills_dirs(root) if root is not None else ():
  503. try:
  504. count += sum(1 for _ in iter_skill_index_files(d, "SKILL.md"))
  505. except OSError:
  506. continue
  507. return (root, count) if count else None
  508. # Scan-time injection defense: trust is a repo-level decision made once, but a
  509. # `git pull` could inject a malicious skill into an already-trusted repo. Every
  510. # project SKILL.md is scanned with the hub's skills_guard scanner (content-hash
  511. # cached under HERMES_HOME, never inside the repo); "dangerous" excludes the
  512. # skill from index, list, view and slash commands ("caution" loads, as on the hub).
  513. # ── Project skill quarantine (scan-time injection defense) ──────────────── Trust (`hermes skills trust`)
  514. # is a REPO-level decision made once; the repo's skill content keeps changing underneath it with every pull.
  515. # The hub install path runs skills_guard on install, but project skills are read straight from a checkout —
  516. # without this gate a `git pull` could inject a malicious skill into an already-trusted repo with no scan
  517. # anywhere (#48974). Every project SKILL.md's parent dir is scanned with the same skills_guard scanner the
  518. # hub uses (content-hash cached, so the cost is one scan per skill per content change). A "dangerous"
  519. # verdict quarantines the skill: it is excluded from the index, skills_list, skill_view, and slash commands.
  520. # "caution" loads (matches hub behavior for prose-level keyword hits) — the quarantine is for
  521. # high-confidence findings only. The scan cache lives under HERMES_HOME, never inside the repo (we don't
  522. # write artifacts into the user's checkout).
  523. _PROJECT_SCAN_SOURCE = "project-local"
  524. _PROJECT_QUARANTINE_CACHE: dict[str, bool] = {} # skill_dir -> quarantined
  525. def is_quarantined_project_skill(skill_md) -> bool:
  526. """True when a project skill's scan verdict is ``dangerous``. Fail-closed: a
  527. scanner crash or missing scanner quarantines the skill. Scans
  528. unconditionally — non-project callers should not call this."""
  529. skill_dir = Path(skill_md).parent
  530. try:
  531. key = str(skill_dir.resolve())
  532. except OSError:
  533. key = str(skill_dir)
  534. if key in _PROJECT_QUARANTINE_CACHE:
  535. return _PROJECT_QUARANTINE_CACHE[key]
  536. try:
  537. from tools.skills_guard import scan_skill_cached
  538. from hermes_constants import get_hermes_home
  539. cache_dir = get_hermes_home() / "cache" / "project_skill_scans"
  540. result, _prov = scan_skill_cached(skill_dir, source=_PROJECT_SCAN_SOURCE, cache_dir=cache_dir)
  541. quarantined = result.verdict == "dangerous"
  542. if quarantined:
  543. logger.warning("Project skill quarantined (verdict=dangerous): %s — %s", skill_dir, result.summary)
  544. except Exception:
  545. logger.warning("Project skill scan failed — quarantining (fail closed): %s", skill_dir, exc_info=True)
  546. quarantined = True
  547. _PROJECT_QUARANTINE_CACHE[key] = quarantined
  548. return quarantined
  549. def iter_project_skill_files(project_dir: Path):
  550. """Yield non-quarantined SKILL.md files under a trusted project dir — the
  551. single iteration chokepoint for the project tier, so the quarantine cannot
  552. be bypassed by a call site forgetting the check."""
  553. yield from (p for p in iter_skill_index_files(project_dir, "SKILL.md") if not is_quarantined_project_skill(p))
  554. def normalize_skill_lookup_name(identifier: str) -> str:
  555. """Translate a trusted absolute skill path (slash commands / cron may store
  556. them) to the relative form ``skill_view()`` accepts."""
  557. raw_identifier = (identifier or "").strip()
  558. if not raw_identifier:
  559. return raw_identifier
  560. identifier_path = Path(raw_identifier).expanduser()
  561. if not identifier_path.is_absolute():
  562. return raw_identifier.lstrip("/")
  563. # Resolve the primary root via tools.skills_tool at CALL time: tests patch
  564. # ``tools.skills_tool.SKILLS_DIR`` and skill_view() enforces ``_skills_dir()``
  565. # (which follows the live profile-scoped HERMES_HOME), so normalization
  566. # must agree with that exact root. Import deferred (cycle).
  567. try:
  568. # See #67277.
  569. from tools import skills_tool as _skills_tool
  570. primary_root = _skills_tool._skills_dir()
  571. except Exception:
  572. primary_root = get_skills_dir()
  573. trusted_roots = [primary_root]
  574. for getter in (get_project_skills_dirs, get_external_skills_dirs):
  575. try:
  576. trusted_roots.extend(getter())
  577. except Exception:
  578. pass
  579. # Prefer the lexical path under a trusted root before resolving symlinks:
  580. # ~/.hermes/skills/<name> may be a symlink to a checkout elsewhere, and
  581. # resolving first would turn that trusted path into one skill_view rejects.
  582. for root in trusted_roots:
  583. if identifier_path.is_relative_to(root):
  584. return str(identifier_path.relative_to(root))
  585. try:
  586. return str(identifier_path.resolve().relative_to(primary_root.resolve()))
  587. except Exception:
  588. logger.debug("Skill identifier %r is an absolute path outside trusted skills "
  589. "roots — passing through unchanged (skill_view will reject it)", raw_identifier)
  590. return raw_identifier
  591. def _resolve_for_skill_ownership(path) -> Path:
  592. path_obj = path if isinstance(path, Path) else Path(str(path))
  593. try:
  594. return path_obj.expanduser().resolve()
  595. except (OSError, RuntimeError):
  596. return path_obj.expanduser().absolute()
  597. def is_external_skill_path(path) -> bool:
  598. """True when ``path`` lives under an external or trusted project skills dir.
  599. Those are externally owned: autonomous lifecycle maintenance treats them as
  600. read-only (user-directed tool calls may still edit them)."""
  601. candidate = _resolve_for_skill_ownership(path)
  602. roots: list[Path] = list(get_external_skills_dirs())
  603. try:
  604. roots.extend(get_project_skills_dirs())
  605. except Exception:
  606. pass
  607. return any(candidate.is_relative_to(_resolve_for_skill_ownership(root)) for root in roots)
  608. def _hermes_metadata(frontmatter: dict[str, Any]) -> dict[str, Any]:
  609. """``metadata.hermes`` mapping from frontmatter, or ``{}`` when malformed."""
  610. metadata = frontmatter.get("metadata")
  611. hermes = metadata.get("hermes") if isinstance(metadata, dict) else None
  612. return hermes if isinstance(hermes, dict) else {}
  613. # ``session_platforms`` is the gateway-channel gate: session platforms the skill
  614. # is FOR (hidden from the index elsewhere), unlike ``platforms:`` (host OS).
  615. _CONDITION_KEYS = ("fallback_for_toolsets", "requires_toolsets", "fallback_for_tools", "requires_tools", "session_platforms")
  616. def extract_skill_conditions(frontmatter: dict[str, Any]) -> dict[str, list]:
  617. """Extract conditional activation fields from parsed frontmatter (absent = ``[]``)."""
  618. hermes = _hermes_metadata(frontmatter)
  619. return {key: hermes.get(key, []) for key in _CONDITION_KEYS}
  620. def extract_skill_config_vars(frontmatter: dict[str, Any]) -> list[dict[str, Any]]:
  621. """Extract ``metadata.hermes.config`` declarations (key/description/default/prompt).
  622. Entries missing ``key`` or ``description`` are skipped; ``prompt`` defaults to the description."""
  623. raw = _hermes_metadata(frontmatter).get("config")
  624. if isinstance(raw, dict):
  625. raw = [raw]
  626. if not raw or not isinstance(raw, list):
  627. return []
  628. result: dict[str, dict[str, Any]] = {}
  629. for item in raw:
  630. if not isinstance(item, dict):
  631. continue
  632. key = str(item.get("key", "")).strip()
  633. desc = str(item.get("description", "")).strip()
  634. if not key or key in result or not desc:
  635. continue
  636. entry: dict[str, Any] = {"key": key, "description": desc}
  637. if item.get("default") is not None:
  638. entry["default"] = item["default"]
  639. prompt_text = item.get("prompt")
  640. entry["prompt"] = prompt_text.strip() if isinstance(prompt_text, str) and prompt_text.strip() else desc
  641. result[key] = entry
  642. return list(result.values())
  643. def discover_all_skill_config_vars() -> list[dict[str, Any]]:
  644. """Config var declarations across all enabled, platform-compatible skills,
  645. deduplicated by key; each dict carries a ``skill`` attribution key."""
  646. all_vars: dict[str, dict[str, Any]] = {}
  647. disabled = get_disabled_skill_names()
  648. for skills_dir in get_all_skills_dirs():
  649. if not skills_dir.is_dir():
  650. continue
  651. for skill_file in iter_skill_index_files(skills_dir, "SKILL.md"):
  652. try:
  653. frontmatter, _ = parse_frontmatter(skill_file.read_text(encoding="utf-8-sig"))
  654. except Exception:
  655. continue
  656. skill_name = str(frontmatter.get("name") or skill_file.parent.name)
  657. if skill_name in disabled or not skill_matches_platform(frontmatter):
  658. continue
  659. for var in extract_skill_config_vars(frontmatter):
  660. if var["key"] not in all_vars:
  661. var["skill"] = skill_name
  662. all_vars[var["key"]] = var
  663. return list(all_vars.values())
  664. # Skill config vars are stored under skills.config.<logical key> in config.yaml.
  665. SKILL_CONFIG_PREFIX = "skills.config"
  666. def _resolve_dotpath(config: dict[str, Any], dotted_key: str):
  667. """Walk a nested dict following a dotted key; None if any part is missing."""
  668. current = config
  669. for part in dotted_key.split("."):
  670. if not isinstance(current, dict) or part not in current:
  671. return None
  672. current = current[part]
  673. return current
  674. _HOME_VAR_RE = re.compile(r"\$(?:\{HOME\}|HOME)(?=$|[/\\])")
  675. def _expand_skill_config_path(value: str) -> str:
  676. """Expand ``~`` / ``$HOME`` against the HOME Hermes injects into tool subprocesses.
  677. Skill config defaults describe paths the agent hands to tools, so in a container where the
  678. control process HOME (``/opt/data``) differs from the tool HOME (``{HERMES_HOME}/home``) a
  679. plain ``expanduser`` pointed the prompt at a path no tool would ever read (#12260).
  680. """
  681. subprocess_home = get_subprocess_home()
  682. if subprocess_home:
  683. if value == "~" or value.startswith(("~/", "~\\")):
  684. value = subprocess_home + value[1:]
  685. # Callable replacement: a literal template would parse backslashes in the home path
  686. # as regex escapes.
  687. value = _HOME_VAR_RE.sub(lambda _m: subprocess_home, value)
  688. return os.path.expanduser(os.path.expandvars(value))
  689. def resolve_skill_config_values(config_vars: list[dict[str, Any]]) -> dict[str, Any]:
  690. """Map logical skill config keys to current values (or declared defaults);
  691. path-like string values are ``~``/``$HOME``/``${VAR}`` expanded against the tool HOME."""
  692. config = _load_raw_config()
  693. resolved: dict[str, Any] = {}
  694. for var in config_vars:
  695. value = _resolve_dotpath(config, f"{SKILL_CONFIG_PREFIX}.{var['key']}")
  696. if value is None or (isinstance(value, str) and not value.strip()):
  697. value = var.get("default", "")
  698. if isinstance(value, str) and ("~" in value or "$" in value):
  699. value = _expand_skill_config_path(value)
  700. resolved[var["key"]] = value
  701. return resolved
  702. # Max description chars shown per row of the system-prompt skill index. skill_manage rejects a new or changed
  703. # description over it and tests/skills/test_authoring_standards.py holds shipped skills to it, so only legacy or
  704. # hand-edited skills ever reach clip_skill_description().
  705. SKILL_PROMPT_DESC_LIMIT = 60
  706. _LAST_WHITESPACE_RE = re.compile(r"\s\S*$")
  707. _CLIP_TRAIL_RE = re.compile(r"[\s.,;:\-\u2013\u2014(/]+$")
  708. def _normalize_skill_description(frontmatter: dict[str, Any]) -> str:
  709. """Normalize a skill's description field for comparison/truncation."""
  710. raw_desc = frontmatter.get("description", "")
  711. return str(raw_desc).strip().strip("'\"") if raw_desc else ""
  712. def clip_skill_description(desc: str) -> str:
  713. """*desc* fitted to SKILL_PROMPT_DESC_LIMIT, cut at a word boundary so the index never shows a half word."""
  714. if len(desc) <= SKILL_PROMPT_DESC_LIMIT:
  715. return desc
  716. head = desc[:SKILL_PROMPT_DESC_LIMIT - 2] # one char past the budget: whitespace there means the last word is whole
  717. boundary = _LAST_WHITESPACE_RE.search(head) # any whitespace (tab, NBSP, ...) separates words, not just " "
  718. if not boundary or boundary.start() == 0: # a single word longer than the budget has no boundary to cut at
  719. return desc[:SKILL_PROMPT_DESC_LIMIT - 3] + "..."
  720. return _CLIP_TRAIL_RE.sub("", head[:boundary.start()]) + "..."
  721. def extract_skill_description(frontmatter: dict[str, Any]) -> str:
  722. """Extract a system-prompt-length description from parsed frontmatter."""
  723. return clip_skill_description(_normalize_skill_description(frontmatter))
  724. def is_skill_description_truncated_for_prompt(frontmatter: dict[str, Any]) -> bool:
  725. """True when the description will be truncated in the system prompt skill index."""
  726. return len(_normalize_skill_description(frontmatter)) > SKILL_PROMPT_DESC_LIMIT
  727. def iter_skill_index_files(skills_dir: Path, filename: str):
  728. """Walk skills_dir yielding sorted paths matching *filename*; prunes
  729. EXCLUDED_SKILL_DIRS and support dirs of skill roots."""
  730. matches: list[str] = []
  731. for root, dirs, files in os.walk(str(skills_dir), followlinks=True):
  732. has_skill_md = "SKILL.md" in files
  733. dirs[:] = [d for d in dirs if d not in EXCLUDED_SKILL_DIRS and not (has_skill_md and d in SKILL_SUPPORT_DIRS)]
  734. if filename in files:
  735. matches.append(os.path.join(root, filename))
  736. yield from map(Path, sorted(matches))
  737. # Namespace helpers for plugin-provided skills.
  738. _NAMESPACE_RE = re.compile(r"^[a-zA-Z0-9_-]+$")
  739. def parse_qualified_name(name: str) -> tuple[Optional[str], str]:
  740. """Split ``'namespace:skill-name'`` into ``(namespace, bare_name)``; ``(None, name)`` without ``':'``."""
  741. namespace, sep, bare = name.partition(":")
  742. return (namespace, bare) if sep else (None, name)
  743. def is_valid_namespace(candidate: Optional[str]) -> bool:
  744. """Check whether *candidate* is a valid namespace (``[a-zA-Z0-9_-]+``)."""
  745. return bool(candidate) and bool(_NAMESPACE_RE.match(candidate))