catalog.py 20 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420
  1. """``manage_catalog`` install targets: catalog plugins and hub skills, installed through the card.
  2. ``prepare`` resolves every id against the plugin catalog (the Plugins tab's resolver) or the skills
  3. hub and fills the row the card draws; an id that does not resolve, or a plugin this OS cannot run,
  4. is drawn failed with the reason. Nothing installs until the user approves a row. The install runs on
  5. a worker under the TARGET profile's runtime scope (the calling chat's own home unless the Advanced
  6. modal named another profile), through the same host install the Plugins tab uses, so the catalog
  7. pin, the kill list, the security scan and the live activation of the plugin's MCP servers and skills
  8. are the host's.
  9. """
  10. from __future__ import annotations
  11. import contextlib
  12. import contextvars
  13. import io
  14. import json
  15. import logging
  16. import re
  17. import threading
  18. from dataclasses import dataclass, field
  19. from pathlib import Path
  20. from typing import Any, Callable, Dict, List, Optional
  21. from hermes_cli.plugin_install_phase import InstallPhase
  22. from hermes_constants import get_hermes_home, profile_name_for_home
  23. from tools.connectors.contract import Actor, SettleReason, TargetState
  24. from tools.connectors.mcp import _fail, _move
  25. from tools.connectors.operation import ConnectionOperation, IllegalTransition, Target
  26. logger = logging.getLogger(__name__)
  27. # The Advanced modal's own keys (CATALOG-ROW-CONTRACT.md); every other answer key is a credential.
  28. _OPTION_KEYS = frozenset({"target_profile", "agent_half", "desktop_half", "enable", "force", "ref"})
  29. _COMMIT_SHA = re.compile(r"^[0-9a-fA-F]{40}$")
  30. _TIERS = frozenset({"official", "verified", "community"})
  31. def _flag(value: Optional[str], default: bool) -> bool:
  32. return default if value in (None, "") else value == "1"
  33. def _first_sentence(text: str) -> str:
  34. text = " ".join(str(text or "").split())
  35. head, dot, _rest = text.partition(". ")
  36. return f"{head}." if dot else text
  37. def _display(identifier: str) -> str:
  38. leaf = identifier.rstrip("/").rsplit("/", 1)[-1]
  39. return " ".join(part.capitalize() for part in re.split(r"[-_]+", leaf) if part) or identifier
  40. @contextlib.contextmanager
  41. def target_scope(home: Path):
  42. """Bind the profile at *home*: its home, secrets and terminal policy, the way an RPC for that
  43. profile does. The install writes its tree, config and ``.env`` there. The home override is
  44. bound for the launch profile too: the calling thread may carry another profile's override, and
  45. an unbound launch scope would leave it in place."""
  46. from tui_gateway import server
  47. from tui_gateway.launch_profile_policy import launch_profile_runtime_scope
  48. launch = home.resolve() == Path(server._hermes_home).resolve()
  49. scope = (launch_profile_runtime_scope(server._hermes_home) if launch
  50. else server._session_profile_runtime_scope({"profile_home": str(home)}))
  51. with scope:
  52. yield
  53. def _named_home(name: str) -> Path:
  54. """The home of the profile the Advanced modal named; raises for one that does not exist."""
  55. from tui_gateway import server
  56. return server._profile_home(name) or Path(server._hermes_home)
  57. class HostInstaller:
  58. """The host side of a catalog row. Tests replace it; production reads the real catalog, hub and
  59. installer."""
  60. def plugin_entry(self, name: str) -> Any:
  61. from hermes_cli.plugin_catalog import get_live_catalog_entry
  62. return get_live_catalog_entry(name)
  63. def refuse(self, entry: Any) -> None:
  64. """Raise with the installer's own text when the catalog would refuse this entry here."""
  65. from hermes_cli.plugins_cmd_catalog import raise_if_removed, refuse_incompatible_catalog_entry
  66. raise_if_removed(entry.name, entry.repo)
  67. refuse_incompatible_catalog_entry(entry)
  68. def install_plugin(self, name: str, *, force: bool, enable: bool, ref: Optional[str],
  69. on_step: Callable[[InstallPhase], None]) -> dict[str, Any]:
  70. from hermes_cli.plugins_cmd import dashboard_install_plugin
  71. return dashboard_install_plugin("", force=force, enable=enable, catalog_name=name, ref=ref, on_step=on_step)
  72. def skill_meta(self, identifier: str) -> Optional[dict[str, Any]]:
  73. """The first hub source that knows the identifier; metadata only, no bundle download."""
  74. from hermes_cli.skills_hub import _sources
  75. from tools.skills_hub import skills_hub_http_session
  76. with skills_hub_http_session():
  77. for source in _sources():
  78. try:
  79. meta = source.inspect(identifier)
  80. except Exception:
  81. continue
  82. if meta is not None:
  83. return {"name": meta.name, "description": meta.description, "source": meta.source,
  84. "identifier": meta.identifier or identifier}
  85. return None
  86. def install_skill(self, identifier: str, *, force: bool, source: Optional[str] = None) -> dict[str, Any]:
  87. """Install headless; ``{name, already_installed}``. ``do_install`` reports only by printing, so
  88. success is read from the hub lock file and failure from its last line. A skill that is already
  89. installed (force off) is left as it is and reported so. ``source`` is the hub source that
  90. resolved ``identifier``; the lock records a ClawHub skill as ``@owner/slug``, so a ClawHub
  91. hit's bare slug is read back through its ``clawhub/<slug>`` card id."""
  92. from rich.console import Console
  93. from hermes_cli.skills_hub import do_install
  94. from tools.skills_hub import HubLockFile, installed_entry
  95. def entry() -> Optional[dict[str, Any]]:
  96. return installed_entry(HubLockFile().by_identifier(), identifier, source)
  97. before = entry()
  98. if before is not None and not force:
  99. return {"name": str(before["name"]), "already_installed": True}
  100. out = io.StringIO()
  101. verdict = do_install(identifier, force=force, skip_confirm=True,
  102. console=Console(file=out, width=200, no_color=True, highlight=False))
  103. after = entry()
  104. from tools.skills_sync_bundled_ops import bundled_skill_for_install
  105. if after is None and verdict is not False and (builtin := bundled_skill_for_install(identifier)):
  106. return {"name": builtin, "already_installed": verdict is None} # shipped skill, no hub lock entry
  107. if after is None or (before is not None and after.get("updated_at") == before.get("updated_at")):
  108. lines = [line.strip() for line in out.getvalue().splitlines() if line.strip()]
  109. raise RuntimeError(lines[-1] if lines else "the skill was not installed")
  110. return {"name": str(after["name"]), "already_installed": False}
  111. @dataclass
  112. class _Work:
  113. done: threading.Event = field(default_factory=threading.Event)
  114. outcome: dict[str, Any] = field(default_factory=dict)
  115. error: str = ""
  116. class _Runner:
  117. """Resolved catalog facts and install work for one operation's rows."""
  118. def __init__(self, installer: HostInstaller):
  119. self.installer = installer
  120. self.op_id: Optional[str] = None
  121. self.facts: dict[str, Any] = {} # row name -> PluginCatalogEntry | skill meta; never on the wire
  122. self.work: dict[str, _Work] = {}
  123. # The Advanced values the user approved per row; Try again (env null) reuses them. Values
  124. # are credentials in part, so they stay here, off the target.
  125. self.approved_env: dict[str, dict[str, str]] = {}
  126. # Built on the tool call's thread: the calling chat's own home is the default install
  127. # target, and its profile name labels the row (None for a home that is no named profile).
  128. self.home: Path = get_hermes_home()
  129. self.label: Optional[str] = profile_name_for_home(self.home)
  130. # -- prepare: resolve each id and draw its row ------------------------------------------------
  131. def prepare(self, operation: ConnectionOperation) -> None:
  132. _RUNNERS[operation.op_id] = self
  133. self.op_id = operation.op_id
  134. for target in operation.targets:
  135. target.extra = {"display": _display(target.name), "target_profile": self.label}
  136. try:
  137. self._resolve(target)
  138. except Exception as exc:
  139. _fail(operation, target, self._detail(exc, target))
  140. def _resolve(self, target: Target) -> None:
  141. if target.kind == "plugin":
  142. entry = self.installer.plugin_entry(target.name)
  143. if entry is None:
  144. raise LookupError(f"'{target.name}' is not in the Hermes plugin catalog")
  145. self.facts[target.name] = entry
  146. target.extra = _plugin_row(entry, self.label)
  147. target.required_env = [{"name": name, "required": False, "secret": True, "default": ""}
  148. for name in entry.capabilities.requires_env]
  149. self.installer.refuse(entry)
  150. return
  151. meta = self.installer.skill_meta(target.name)
  152. if not meta:
  153. raise LookupError(f"'{target.name}' was not found in the skills hub")
  154. self.facts[target.name] = meta
  155. target.extra = {
  156. "display": str(meta.get("name") or _display(target.name)),
  157. "description": _first_sentence(meta.get("description") or ""),
  158. "tier": "official" if meta.get("source") == "official" else "community",
  159. "target_profile": self.label,
  160. }
  161. # -- the card's answer ------------------------------------------------------------------------
  162. def approve(self, operation: ConnectionOperation, target: Target, env: Optional[dict[str, str]]) -> None:
  163. approved = {**self.approved_env.get(target.name, {}), **(env or {})}
  164. actor = Actor.user if target.state == TargetState.failed else Actor.backend_watcher
  165. if target.name not in self.facts: # failed at prepare: Try again resolves once more
  166. try:
  167. self._resolve(target)
  168. except Exception as exc:
  169. _fail(operation, target, self._detail(exc, target))
  170. return
  171. error = self._check_answer(target, approved)
  172. if error:
  173. _fail(operation, target, error)
  174. return
  175. self.approved_env[target.name] = approved
  176. # The non-secret choices go on the row, so a Try again after the operation settled repeats
  177. # what the user approved; the credentials are already in the target profile's .env by then.
  178. options = {"force": _flag(approved.get("force"), False), "enable": _flag(approved.get("enable"), True),
  179. "ref": approved.get("ref") or None}
  180. profile = (approved.get("target_profile") or "").strip()
  181. if not _move(operation, target, TargetState.initiated, actor, detail="",
  182. **{**target.extra, "target_profile": profile or self.label, "approved": options}):
  183. return
  184. self._spawn(operation, target, approved, options)
  185. def _check_answer(self, target: Target, env: dict[str, str]) -> str:
  186. if target.kind == "plugin" and env.get("agent_half") == "0":
  187. return "only the desktop half was selected; install it from Settings, Plugins"
  188. ref = env.get("ref")
  189. if ref and not _COMMIT_SHA.match(ref):
  190. return "the pin must be a full 40-character commit SHA"
  191. declared = set(target_declared_env(self.facts.get(target.name)))
  192. undeclared = sorted(k for k in env if k not in _OPTION_KEYS and k not in declared)
  193. if undeclared:
  194. return f"'{target.name}' does not declare {', '.join(undeclared)}"
  195. return ""
  196. def _spawn(self, operation: ConnectionOperation, target: Target, env: dict[str, str],
  197. options: dict[str, Any]) -> None:
  198. work = _Work()
  199. self.work[target.name] = work
  200. def step(phase: InstallPhase) -> None:
  201. # A row that left ``initiated`` keeps its own state.
  202. if not operation.settled and target.state == TargetState.initiated:
  203. operation.refresh(target.name, connect_url=None, detail="", actor=Actor.backend_watcher,
  204. phase=phase.value)
  205. def body() -> None:
  206. try:
  207. work.outcome = self._install(target, env, options, step)
  208. except Exception as exc:
  209. work.error = self._detail(exc, target)
  210. work.done.set()
  211. operation.wake.set()
  212. # A copy of the answering thread's context; the install binds the target profile itself.
  213. threading.Thread(target=contextvars.copy_context().run, args=(body,), daemon=True,
  214. name=f"catalog-install-{target.name}").start()
  215. def _install(self, target: Target, env: dict[str, str], options: dict[str, Any],
  216. step: Callable[[InstallPhase], None]) -> dict[str, Any]:
  217. named = (env.get("target_profile") or "").strip()
  218. with target_scope(_named_home(named) if named else self.home):
  219. _save_credentials({k: v for k, v in env.items() if k not in _OPTION_KEYS and v})
  220. if target.kind == "skill":
  221. meta = self.facts[target.name]
  222. identifier = str(meta.get("identifier") or target.name)
  223. step(InstallPhase.downloading)
  224. return self.installer.install_skill(identifier, force=options["force"], source=meta.get("source"))
  225. result = self.installer.install_plugin(target.name, force=options["force"], enable=options["enable"],
  226. ref=options["ref"], on_step=step)
  227. if not result.get("ok"):
  228. raise RuntimeError(result.get("error") or "the install failed")
  229. return {"enabled": options["enable"], **result}
  230. # -- the watcher --------------------------------------------------------------------------------
  231. def observe(self, operation: ConnectionOperation) -> None:
  232. for target in operation.targets:
  233. work = self.work.get(target.name)
  234. if operation.settled or target.state != TargetState.initiated or work is None or not work.done.is_set():
  235. continue
  236. self.work.pop(target.name, None)
  237. if work.error:
  238. _fail(operation, target, work.error)
  239. continue
  240. extra, detail = _installed_row(target, work.outcome)
  241. _move(operation, target, TargetState.connected, Actor.backend_watcher, detail=detail, **extra)
  242. def close(self) -> None:
  243. if self.op_id is not None:
  244. _RUNNERS.pop(self.op_id, None)
  245. def _detail(self, exc: Any, target: Target) -> str:
  246. from agent.redact import redact_sensitive_text
  247. text = str(exc) or exc.__class__.__name__
  248. # Only credentials are secret: the Advanced choices (a profile name, a commit) stay readable.
  249. for key, value in self.approved_env.get(target.name, {}).items():
  250. if key not in _OPTION_KEYS and value and len(value) > 3:
  251. text = text.replace(value, "[REDACTED]")
  252. return redact_sensitive_text(text, force=True) or "error"
  253. def target_declared_env(fact: Any) -> list[str]:
  254. caps = getattr(fact, "capabilities", None)
  255. return list(getattr(caps, "requires_env", None) or ())
  256. def _plugin_row(entry: Any, label: Optional[str]) -> dict[str, Any]:
  257. from hermes_cli.plugin_catalog_presence import presence
  258. row: dict[str, Any] = {
  259. "display": getattr(entry, "title", "") or _display(entry.name),
  260. "description": _first_sentence(entry.description),
  261. "tier": entry.tier if entry.tier in _TIERS else "community",
  262. "repo": entry.repo,
  263. "sha": entry.sha,
  264. "requires_hermes": entry.requires_hermes or None,
  265. "has_desktop_half": False,
  266. "target_profile": label,
  267. "app_state": presence(entry).state,
  268. }
  269. if entry.platforms:
  270. row["platforms"] = list(entry.platforms)
  271. if entry.subdir:
  272. row["subdir"] = entry.subdir
  273. return row
  274. def _installed_row(target: Target, outcome: dict[str, Any]) -> tuple:
  275. """The connected row's fields (the drawn row plus what went live, as facts the card words) and
  276. the same notes in one English line for the model."""
  277. extra = dict(target.extra)
  278. if target.kind == "skill":
  279. already = bool(outcome.get("already_installed"))
  280. detail = "already installed; left as it is (Advanced, force reinstall replaces it)" if already else ""
  281. return {**extra, "skill": outcome["name"], "tools": [], "already_installed": already}, detail
  282. live = (outcome.get("activation") or {}).get("live_now") or {}
  283. servers = live.get("mcp_servers") or []
  284. tools = [name for server in servers if server.get("connected") for name in server.get("tools") or ()]
  285. server_errors = [{"name": s["name"], "error": s.get("error") or ""} for s in servers if not s.get("connected")]
  286. enabled = bool(outcome.get("enabled", True))
  287. missing_env = list(outcome.get("missing_env") or ())
  288. notes = [f"MCP server {e['name']} not connected: {e['error'] or 'unknown error'}" for e in server_errors]
  289. if not enabled:
  290. notes.append("installed but not enabled")
  291. if missing_env:
  292. notes.append(f"set {', '.join(missing_env)} to finish setup")
  293. skills = [s["name"] for s in live.get("skills") or () if s.get("name")]
  294. if skills:
  295. extra["skill"] = skills[0]
  296. facts = {"tools": tools, "enabled": enabled, "missing_env": missing_env, "server_errors": server_errors}
  297. return {**extra, **facts}, "; ".join(notes)
  298. def _save_credentials(env: dict[str, str]) -> None:
  299. from hermes_cli.config import save_env_value, validate_env_var_name_for_write
  300. for key, value in env.items():
  301. validate_env_var_name_for_write(key)
  302. save_env_value(key, value)
  303. # op_id -> the runner driving it, so the card's answer (RPC thread) finds the work.
  304. _RUNNERS: dict[str, _Runner] = {}
  305. def owns(op_id: str) -> bool:
  306. return op_id in _RUNNERS
  307. def apply_answer(operation: ConnectionOperation, raw: str) -> None:
  308. """The card's ``connection.respond`` for a catalog operation: skip, approve (with the Advanced
  309. values or null for defaults), approve again on a failed row (Try again), and Continue."""
  310. try:
  311. answer = json.loads(raw)
  312. except (TypeError, ValueError):
  313. answer = {}
  314. answer = answer if isinstance(answer, dict) else {}
  315. runner = _RUNNERS.get(operation.op_id)
  316. for entry in answer.get("targets") or ():
  317. if not isinstance(entry, dict):
  318. continue
  319. target = operation.target(str(entry.get("name") or "").strip())
  320. if target is None:
  321. continue
  322. status = str(entry.get("status") or "").lower()
  323. if status == "skipped":
  324. try:
  325. operation.transition(target.name, TargetState.skipped, Actor.user)
  326. except IllegalTransition:
  327. if not target.resolved and not operation.settled:
  328. raise
  329. elif status == "approved" and runner is not None and target.state in (TargetState.pending, TargetState.failed):
  330. env = entry.get("env")
  331. runner.approve(operation, target, {str(k): str(v) for k, v in env.items()} if isinstance(env, dict) else None)
  332. if answer.get("settled_by") == SettleReason.continue_.value and not operation.all_resolved:
  333. operation.settle(SettleReason.continue_)
  334. def retry(operation: ConnectionOperation, names: list[str]) -> Optional[str]:
  335. runner = _RUNNERS.get(operation.op_id)
  336. if runner is None or operation.settled:
  337. return "this operation has settled; its result is frozen"
  338. for name in names:
  339. target = operation.target(name)
  340. if target is not None and target.state == TargetState.failed:
  341. runner.approve(operation, target, None)
  342. return None
  343. def open_runner(installer: Optional[HostInstaller] = None) -> _Runner:
  344. return _Runner(installer or HostInstaller())
  345. Callback = Callable[[dict[str, Any]], Optional[str]]