skills.py 20 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483
  1. """Skills dashboard routes.
  2. Two routers because global route order matters: ``hub_router`` (skills-hub
  3. install/search/scan) was registered before the profiles router include in
  4. web_server, the plain skills CRUD ``router`` after it — each is mounted at its
  5. original registration point. Shared helpers are reached via the late-binding
  6. seam so ``monkeypatch.setattr(<owning module>, ...)`` keeps working.
  7. """
  8. import asyncio
  9. from typing import Optional
  10. from fastapi import APIRouter, HTTPException
  11. from hermes_cli.web_deps import late
  12. from hermes_cli.web_server_profiles import _hub_action_name, _installed_hub_identifiers
  13. from hermes_cli.web_models import (
  14. SkillContentUpdate, SkillCreate, SkillInstallRequest, SkillLock, SkillToggle,
  15. SkillUninstallRequest, SkillsUpdateRequest)
  16. from hermes_cli.web_routers._common import (
  17. _profile_scope, config_write_scope, http_failure, log as _log, require, scoped_to_thread,
  18. spawn_profile_action)
  19. hub_router = APIRouter()
  20. router = APIRouter()
  21. _config_profile_scope = late("_config_profile_scope", "hermes_cli.web_server_profiles")
  22. load_config = late("load_config", "hermes_cli.config")
  23. # Labels per hub source id (matches `hermes skills search` provenance); keep in
  24. # sync with create_source_router()'s source list.
  25. _SKILL_HUB_SOURCE_LABELS = {
  26. "official": "Official (Nous)",
  27. "hermes-index": "Hermes Index",
  28. "skills-sh": "skills.sh",
  29. "well-known": "Well-Known",
  30. "url": "Direct URL",
  31. "github": "GitHub",
  32. "clawhub": "ClawHub",
  33. "lobehub": "LobeHub",
  34. "browse-sh": "browse.sh",
  35. }
  36. def _hub_sources(profile: Optional[str]):
  37. """Source router built under ``profile``'s config scope."""
  38. from tools.skills_hub_search import create_source_router
  39. with _config_profile_scope(profile):
  40. return create_source_router()
  41. def _resolve_hub_skill(ident: str, profile: Optional[str]):
  42. """``(meta, bundle)`` for a hub identifier, resolved under ``profile``'s scope."""
  43. from hermes_cli.skills_hub import _resolve_source_meta_and_bundle
  44. from tools.skills_hub_search import create_source_router
  45. with _config_profile_scope(profile):
  46. sources = create_source_router()
  47. meta, bundle, _src = _resolve_source_meta_and_bundle(ident, sources)
  48. return meta, bundle
  49. # Sources subsumed by an available hermes-index (progressive per-source fan-out
  50. # skips them: ~70 GitHub calls per keystroke saved). Keep in sync with
  51. # parallel_search_sources' _api_source_ids.
  52. _API_SOURCE_IDS = frozenset({"github", "skills-sh", "clawhub", "lobehub", "well-known"})
  53. def _flag(obj, attr: str) -> bool:
  54. """``bool(getattr(obj, attr, False))``; a raising property reads as False."""
  55. try:
  56. return bool(getattr(obj, attr, False))
  57. except Exception:
  58. return False
  59. def _skill_meta_to_payload(m) -> dict:
  60. return {
  61. "name": m.name, "description": m.description, "source": m.source,
  62. "identifier": m.identifier, "trust_level": m.trust_level, "repo": m.repo,
  63. "tags": list(m.tags or [])}
  64. def _clear_skills_prompt_cache() -> None:
  65. """Best-effort: invalidate the skills system-prompt snapshot after a write.
  66. Mirrors what ``skill_manage`` does so a dashboard-authored skill is picked
  67. up by the next session without a manual cache reset.
  68. """
  69. try:
  70. from agent.prompt_builder import clear_skills_system_prompt_cache
  71. clear_skills_system_prompt_cache(clear_snapshot=True)
  72. except Exception:
  73. pass
  74. @hub_router.post("/api/skills/hub/install")
  75. async def install_skill_hub(body: SkillInstallRequest, profile: Optional[str] = None):
  76. identifier = require(body.identifier, "identifier is required")
  77. return spawn_profile_action(
  78. body.profile or profile, ["skills", "install", identifier, "--yes"],
  79. _hub_action_name("install", identifier), log_msg="Failed to spawn skills install",
  80. prefix="Failed to install skill")
  81. @hub_router.post("/api/skills/hub/uninstall")
  82. async def uninstall_skill_hub(body: SkillUninstallRequest, profile: Optional[str] = None):
  83. name = require(body.name, "name is required")
  84. return spawn_profile_action(
  85. body.profile or profile, ["skills", "uninstall", name, "--yes"],
  86. _hub_action_name("uninstall", name), log_msg="Failed to spawn skills uninstall",
  87. prefix="Failed to uninstall skill")
  88. @hub_router.post("/api/skills/hub/update")
  89. async def update_skills_hub(
  90. body: Optional[SkillsUpdateRequest] = None, profile: Optional[str] = None):
  91. return spawn_profile_action(
  92. (body.profile if body else None) or profile, ["skills", "update"], "skills-update",
  93. log_msg="Failed to spawn skills update", prefix="Failed to update skills")
  94. @hub_router.get("/api/skills/hub/official")
  95. async def list_official_skills(profile: Optional[str] = None):
  96. """The ENTIRE optional-skills catalog (local scan), marked installed for ``profile``."""
  97. def _run():
  98. from tools.skills_hub_official import OptionalSkillSource
  99. installed = _installed_hub_identifiers(profile)
  100. out = []
  101. for m in OptionalSkillSource().list_local():
  102. payload = _skill_meta_to_payload(m)
  103. ident = payload.get("identifier") or ""
  104. # identifier format: official/<category>/<skill> — surface the
  105. # category for row subtitles.
  106. rel = ident.split("/", 1)[-1] if "/" in ident else ident
  107. payload["category"] = rel.split("/", 1)[0] if "/" in rel else "general"
  108. payload["installed"] = ident in installed
  109. out.append(payload)
  110. return {"skills": out}
  111. with http_failure("official skills catalog listing failed", 502, "Official catalog failed"):
  112. return await asyncio.to_thread(_run)
  113. @hub_router.get("/api/skills/hub/sources")
  114. async def list_skills_hub_sources(profile: Optional[str] = None):
  115. """Configured skill-hub sources + installed-skill provenance (scoped to
  116. ``profile``), so the Browse-hub tab has something before a search runs."""
  117. def _run():
  118. sources = _hub_sources(profile)
  119. out = []
  120. index_available = False
  121. featured = []
  122. for src in sources:
  123. sid = src.source_id()
  124. entry = {"id": sid, "label": _SKILL_HUB_SOURCE_LABELS.get(sid, sid)}
  125. # GitHub exposes a rate-limit flag; the index an availability flag.
  126. if sid == "github":
  127. entry["rate_limited"] = _flag(src, "is_rate_limited")
  128. if sid == "hermes-index":
  129. index_available = _flag(src, "is_available")
  130. entry["available"] = index_available
  131. # Empty-query search on the index returns featured/popular skills.
  132. if index_available:
  133. try:
  134. featured = [
  135. _skill_meta_to_payload(m) for m in src.search("", limit=12)]
  136. except Exception:
  137. featured = []
  138. out.append(entry)
  139. # Which sources are worth searching individually (see _API_SOURCE_IDS).
  140. for entry in out:
  141. entry["searchable"] = not (index_available and entry["id"] in _API_SOURCE_IDS)
  142. return {
  143. "sources": out, "index_available": index_available, "featured": featured,
  144. "installed": _installed_hub_identifiers(profile)}
  145. with http_failure("skills hub sources listing failed", 502, "Hub sources failed"):
  146. return await asyncio.to_thread(_run)
  147. @hub_router.get("/api/skills/hub/search")
  148. async def search_skills_hub(
  149. q: str = "", source: str = "all", limit: int = 20, profile: Optional[str] = None):
  150. """Search the skill hub across all configured sources (network-bound)."""
  151. query = (q or "").strip()
  152. if not query:
  153. return {"results": [], "source_counts": {}, "timed_out": [], "installed": {}}
  154. def _run():
  155. from tools.skills_hub_search import parallel_search_sources
  156. sources = _hub_sources(profile)
  157. capped = min(max(limit, 1), 50)
  158. all_results, source_counts, timed_out = parallel_search_sources(
  159. sources, query=query, source_filter=source or "all", overall_timeout=30)
  160. # Dedupe by identifier, preferring higher trust (mirrors unified_search).
  161. _rank = {"builtin": 2, "trusted": 1, "community": 0}
  162. seen = {}
  163. for r in all_results:
  164. prev = seen.get(r.identifier)
  165. if prev is None or _rank.get(r.trust_level, 0) > _rank.get(prev.trust_level, 0):
  166. seen[r.identifier] = r
  167. deduped = list(seen.values())[:capped]
  168. return {
  169. "results": [_skill_meta_to_payload(m) for m in deduped], "source_counts": source_counts,
  170. "timed_out": timed_out, "installed": _installed_hub_identifiers(profile)}
  171. with http_failure("skills hub search failed", 502, "Hub search failed"):
  172. return await asyncio.to_thread(_run)
  173. async def _hub_lookup(fn, ident: str, log_msg: str, prefix: str):
  174. """Run ``fn`` off-loop; any failure -> 502 ``"<prefix>: <exc>"``, None -> 404."""
  175. with http_failure(log_msg, 502, prefix):
  176. result = await asyncio.to_thread(fn)
  177. if result is None:
  178. raise HTTPException(status_code=404, detail=f"Skill not found: {ident}")
  179. return result
  180. @hub_router.get("/api/skills/hub/preview")
  181. async def preview_skill_hub(identifier: str = "", profile: Optional[str] = None):
  182. """A hub skill's SKILL.md + file manifest WITHOUT installing it; scoped to
  183. ``profile`` so different hub taps resolve against THAT source router."""
  184. ident = require(identifier, "identifier is required")
  185. def _run():
  186. meta, bundle = _resolve_hub_skill(ident, profile)
  187. if not bundle and not meta:
  188. return None
  189. files = {}
  190. skill_md = ""
  191. if bundle:
  192. for rel, content in (bundle.files or {}).items():
  193. if isinstance(content, bytes):
  194. # Some sources store every file as bytes; decode text so
  195. # SKILL.md renders, placeholder only for genuinely-binary data.
  196. try:
  197. files[rel] = content.decode("utf-8")
  198. except UnicodeDecodeError:
  199. files[rel] = "(binary file)"
  200. else:
  201. files[rel] = content
  202. skill_md = files.get("SKILL.md", "") or ""
  203. m = meta or bundle
  204. return {
  205. "name": getattr(m, "name", ident), "description": getattr(m, "description", "") or "",
  206. "source": getattr(m, "source", "") or "",
  207. "identifier": getattr(m, "identifier", ident) or ident,
  208. "trust_level": getattr(m, "trust_level", "community") or "community",
  209. "repo": getattr(m, "repo", None), "tags": list(getattr(m, "tags", None) or []),
  210. "skill_md": skill_md, "files": sorted(files.keys())}
  211. return await _hub_lookup(_run, ident, "skills hub preview failed", "Hub preview failed")
  212. @hub_router.get("/api/skills/hub/scan")
  213. async def scan_skill_hub(identifier: str = "", profile: Optional[str] = None):
  214. """Install-time security scan of a hub skill WITHOUT installing it (the CLI's
  215. ``scan_skill`` / ``should_allow_install`` pipeline on a quarantined bundle);
  216. scoped to ``profile`` so the bundle resolves where an install would."""
  217. ident = require(identifier, "identifier is required")
  218. def _run():
  219. import shutil as _shutil
  220. from tools.skills_hub_install import quarantine_bundle
  221. from tools.skills_guard import scan_skill, should_allow_install
  222. meta, bundle = _resolve_hub_skill(ident, profile)
  223. if not bundle:
  224. return None
  225. if bundle.source == "official":
  226. scan_source = "official"
  227. else:
  228. scan_source = (
  229. getattr(bundle, "identifier", "") or getattr(meta, "identifier", "") or ident)
  230. tier1 = None
  231. q_path = quarantine_bundle(bundle)
  232. try:
  233. result = scan_skill(q_path, source=scan_source)
  234. # Advisory SkillEvaluator Tier 1 second opinion: optional binary,
  235. # never blocks, errors degrade to no data (same as the CLI installer).
  236. try:
  237. from tools.skillevaluator_scan import run_tier1_scan, tier1_advisory_enabled
  238. if tier1_advisory_enabled():
  239. t1 = run_tier1_scan(q_path)
  240. if t1.available:
  241. tier1 = {
  242. "passed": t1.passed,
  243. "incomplete_checks": t1.incomplete_checks,
  244. "findings": [
  245. {
  246. "check": f.check, "validator": f.validator,
  247. "severity": f.severity, "message": f.message,
  248. "file": f.file, "line": f.line,
  249. "secrets_class": f.is_secrets_class}
  250. for f in t1.findings]}
  251. except Exception:
  252. _log.debug("Tier 1 advisory scan skipped", exc_info=True)
  253. finally:
  254. _shutil.rmtree(q_path, ignore_errors=True)
  255. # `allowed` may be None ("ask") for agent-created/dangerous gates.
  256. allowed, reason = should_allow_install(result, force=False)
  257. findings = [
  258. {
  259. "severity": f.severity, "category": f.category, "file": f.file,
  260. "line": f.line, "description": f.description}
  261. for f in result.findings]
  262. counts = {sev: 0 for sev in ("critical", "high", "medium", "low")}
  263. for f in result.findings:
  264. if f.severity in counts:
  265. counts[f.severity] += 1
  266. return {
  267. "name": result.skill_name,
  268. "identifier": ident,
  269. "source": result.source,
  270. "trust_level": result.trust_level,
  271. "verdict": result.verdict,
  272. "summary": result.summary,
  273. "policy": "allow" if allowed is True else "ask" if allowed is None else "block",
  274. "policy_reason": reason,
  275. "findings": findings,
  276. "severity_counts": counts,
  277. "tier1": tier1, # None when the optional scanner isn't installed/enabled
  278. }
  279. return await _hub_lookup(_run, ident, "skills hub scan failed", "Hub scan failed")
  280. @router.get("/api/skills")
  281. async def get_skills(profile: Optional[str] = None):
  282. from tools.skills_tool import find_all_skills
  283. from hermes_cli.skills_config import get_disabled_skills
  284. from tools.skill_usage import (
  285. _external_skill_names, _read_bundled_names, _read_hub_installed_names, activity_count, load_usage)
  286. def _run():
  287. with _profile_scope(profile):
  288. config = load_config()
  289. disabled = get_disabled_skills(config)
  290. skills = find_all_skills(skip_disabled=True)
  291. usage = load_usage()
  292. # Set-based provenance (same classification as skill_usage.provenance,
  293. # without a per-skill manifest read): hub > bundled > external > agent.
  294. # "external" is mounted from skills.external_dirs and absent locally —
  295. # externally authored, NOT learned. "agent" covers agent-authored AND
  296. # local hand-made skills — the ones the user may edit/delete from the
  297. # UI; external skills keep their in-place foreground edit rights
  298. # regardless of label (commit 8c8fc6c1ec).
  299. bundled_names = _read_bundled_names()
  300. hub_names = _read_hub_installed_names()
  301. external_names = _external_skill_names() - bundled_names - hub_names
  302. locked_dirs, dir_by_name = _locked_index()
  303. for s in skills:
  304. s["locked"] = dir_by_name.get(s["name"], s["name"]) in locked_dirs
  305. s["enabled"] = s["name"] not in disabled
  306. s["usage"] = activity_count(usage.get(s["name"], {}))
  307. s["provenance"] = (
  308. "hub" if s["name"] in hub_names
  309. else "bundled" if s["name"] in bundled_names
  310. else "external" if s["name"] in external_names
  311. else "agent")
  312. return skills
  313. return await asyncio.to_thread(_run)
  314. def _locked_index() -> tuple[set, dict]:
  315. """(locked directory names, load name -> directory name) for the ``locked`` row flag.
  316. Locks are keyed by the skill's DIRECTORY (what the write guards resolve to) while rows
  317. carry the load name. A corrupt sidecar reads as unlocked here (``locked_skill_names`` is
  318. best-effort); the write guards decide enforcement."""
  319. from tools.skill_usage import locked_skill_names
  320. locked = set(locked_skill_names())
  321. if not locked:
  322. return set(), {}
  323. from tools.skills_tool import _skill_catalog
  324. return locked, {e["load_name"]: e["path"].parent.name
  325. for e in _skill_catalog(skip_disabled=True) if e.get("load_name")}
  326. @router.put("/api/skills/lock")
  327. async def lock_skill(body: SkillLock, profile: Optional[str] = None):
  328. """Lock/unlock a skill against AGENT edits (same record as ``hermes curator lock``).
  329. The user's own edits (this dashboard's editor, their editor) stay allowed."""
  330. from tools import skill_usage
  331. from tools.skill_manager_tool import _find_skill
  332. def _run():
  333. with config_write_scope(body.profile or profile):
  334. existing = _find_skill(body.name)
  335. if existing is None:
  336. raise HTTPException(status_code=404, detail=f"Skill '{body.name}' not found.")
  337. key = existing["path"].name
  338. if not skill_usage.set_locked(key, body.locked):
  339. verb = "lock" if body.locked else "unlock"
  340. raise HTTPException(
  341. status_code=500,
  342. detail=f"Could not {verb} '{key}': skills/.usage.json is not writable.")
  343. return {"ok": True, "name": body.name, "locked": body.locked}
  344. return await asyncio.to_thread(_run)
  345. @router.put("/api/skills/toggle")
  346. async def toggle_skill(body: SkillToggle, profile: Optional[str] = None):
  347. from hermes_cli.skills_config import get_disabled_skills, save_disabled_skills
  348. def _run():
  349. with config_write_scope(body.profile or profile):
  350. config = load_config()
  351. disabled = get_disabled_skills(config)
  352. if body.enabled:
  353. disabled.discard(body.name)
  354. else:
  355. disabled.add(body.name)
  356. save_disabled_skills(config, disabled)
  357. return {"ok": True, "name": body.name, "enabled": body.enabled}
  358. return await asyncio.to_thread(_run)
  359. @router.get("/api/skills/content")
  360. async def get_skill_content(name: str, profile: Optional[str] = None):
  361. """Raw SKILL.md text for the dashboard editor."""
  362. from tools.skill_manager_tool import _find_skill
  363. def _read():
  364. found = _find_skill(name)
  365. if not found:
  366. raise HTTPException(status_code=404, detail=f"Skill '{name}' not found.")
  367. skill_md = found["path"] / "SKILL.md"
  368. if not skill_md.exists():
  369. raise HTTPException(status_code=404, detail=f"Skill '{name}' has no SKILL.md.")
  370. try:
  371. content = skill_md.read_text(encoding="utf-8-sig")
  372. except OSError as exc:
  373. raise HTTPException(status_code=500, detail=str(exc)) from exc
  374. return {"name": name, "content": content, "path": str(skill_md)}
  375. return await scoped_to_thread(profile, _read)
  376. @router.post("/api/skills")
  377. async def create_skill(body: SkillCreate, profile: Optional[str] = None):
  378. """Create a skill via the agent's ``skill_manage`` write path, minus the
  379. write-approval gate — an authenticated dashboard write IS the user.
  380. Profile from the body or ``?profile=``, like the rest of ``/api/skills``."""
  381. from tools.skill_manager_tool import _create_skill
  382. result = await scoped_to_thread(
  383. body.profile or profile, lambda: _create_skill(body.name, body.content, body.category or None))
  384. if not result.get("success"):
  385. raise HTTPException(status_code=400, detail=result.get("error", "Failed to create skill."))
  386. _clear_skills_prompt_cache()
  387. return result
  388. @router.put("/api/skills/content")
  389. async def update_skill_content(body: SkillContentUpdate, profile: Optional[str] = None):
  390. """Replace the SKILL.md of an existing skill (full rewrite) from the editor."""
  391. from tools.skill_manager_tool import _edit_skill
  392. result = await scoped_to_thread(body.profile or profile, lambda: _edit_skill(body.name, body.content))
  393. if not result.get("success"):
  394. err = result.get("error", "Failed to update skill.")
  395. status = 404 if "not found" in str(err).lower() else 400
  396. raise HTTPException(status_code=status, detail=err)
  397. _clear_skills_prompt_cache()
  398. return result