| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420 |
- """``manage_catalog`` install targets: catalog plugins and hub skills, installed through the card.
- ``prepare`` resolves every id against the plugin catalog (the Plugins tab's resolver) or the skills
- hub and fills the row the card draws; an id that does not resolve, or a plugin this OS cannot run,
- is drawn failed with the reason. Nothing installs until the user approves a row. The install runs on
- a worker under the TARGET profile's runtime scope (the calling chat's own home unless the Advanced
- modal named another profile), through the same host install the Plugins tab uses, so the catalog
- pin, the kill list, the security scan and the live activation of the plugin's MCP servers and skills
- are the host's.
- """
- from __future__ import annotations
- import contextlib
- import contextvars
- import io
- import json
- import logging
- import re
- import threading
- from dataclasses import dataclass, field
- from pathlib import Path
- from typing import Any, Callable, Dict, List, Optional
- from hermes_cli.plugin_install_phase import InstallPhase
- from hermes_constants import get_hermes_home, profile_name_for_home
- from tools.connectors.contract import Actor, SettleReason, TargetState
- from tools.connectors.mcp import _fail, _move
- from tools.connectors.operation import ConnectionOperation, IllegalTransition, Target
- logger = logging.getLogger(__name__)
- # The Advanced modal's own keys (CATALOG-ROW-CONTRACT.md); every other answer key is a credential.
- _OPTION_KEYS = frozenset({"target_profile", "agent_half", "desktop_half", "enable", "force", "ref"})
- _COMMIT_SHA = re.compile(r"^[0-9a-fA-F]{40}$")
- _TIERS = frozenset({"official", "verified", "community"})
- def _flag(value: Optional[str], default: bool) -> bool:
- return default if value in (None, "") else value == "1"
- def _first_sentence(text: str) -> str:
- text = " ".join(str(text or "").split())
- head, dot, _rest = text.partition(". ")
- return f"{head}." if dot else text
- def _display(identifier: str) -> str:
- leaf = identifier.rstrip("/").rsplit("/", 1)[-1]
- return " ".join(part.capitalize() for part in re.split(r"[-_]+", leaf) if part) or identifier
- @contextlib.contextmanager
- def target_scope(home: Path):
- """Bind the profile at *home*: its home, secrets and terminal policy, the way an RPC for that
- profile does. The install writes its tree, config and ``.env`` there. The home override is
- bound for the launch profile too: the calling thread may carry another profile's override, and
- an unbound launch scope would leave it in place."""
- from tui_gateway import server
- from tui_gateway.launch_profile_policy import launch_profile_runtime_scope
- launch = home.resolve() == Path(server._hermes_home).resolve()
- scope = (launch_profile_runtime_scope(server._hermes_home) if launch
- else server._session_profile_runtime_scope({"profile_home": str(home)}))
- with scope:
- yield
- def _named_home(name: str) -> Path:
- """The home of the profile the Advanced modal named; raises for one that does not exist."""
- from tui_gateway import server
- return server._profile_home(name) or Path(server._hermes_home)
- class HostInstaller:
- """The host side of a catalog row. Tests replace it; production reads the real catalog, hub and
- installer."""
- def plugin_entry(self, name: str) -> Any:
- from hermes_cli.plugin_catalog import get_live_catalog_entry
- return get_live_catalog_entry(name)
- def refuse(self, entry: Any) -> None:
- """Raise with the installer's own text when the catalog would refuse this entry here."""
- from hermes_cli.plugins_cmd_catalog import raise_if_removed, refuse_incompatible_catalog_entry
- raise_if_removed(entry.name, entry.repo)
- refuse_incompatible_catalog_entry(entry)
- def install_plugin(self, name: str, *, force: bool, enable: bool, ref: Optional[str],
- on_step: Callable[[InstallPhase], None]) -> dict[str, Any]:
- from hermes_cli.plugins_cmd import dashboard_install_plugin
- return dashboard_install_plugin("", force=force, enable=enable, catalog_name=name, ref=ref, on_step=on_step)
- def skill_meta(self, identifier: str) -> Optional[dict[str, Any]]:
- """The first hub source that knows the identifier; metadata only, no bundle download."""
- from hermes_cli.skills_hub import _sources
- from tools.skills_hub import skills_hub_http_session
- with skills_hub_http_session():
- for source in _sources():
- try:
- meta = source.inspect(identifier)
- except Exception:
- continue
- if meta is not None:
- return {"name": meta.name, "description": meta.description, "source": meta.source,
- "identifier": meta.identifier or identifier}
- return None
- def install_skill(self, identifier: str, *, force: bool, source: Optional[str] = None) -> dict[str, Any]:
- """Install headless; ``{name, already_installed}``. ``do_install`` reports only by printing, so
- success is read from the hub lock file and failure from its last line. A skill that is already
- installed (force off) is left as it is and reported so. ``source`` is the hub source that
- resolved ``identifier``; the lock records a ClawHub skill as ``@owner/slug``, so a ClawHub
- hit's bare slug is read back through its ``clawhub/<slug>`` card id."""
- from rich.console import Console
- from hermes_cli.skills_hub import do_install
- from tools.skills_hub import HubLockFile, installed_entry
- def entry() -> Optional[dict[str, Any]]:
- return installed_entry(HubLockFile().by_identifier(), identifier, source)
- before = entry()
- if before is not None and not force:
- return {"name": str(before["name"]), "already_installed": True}
- out = io.StringIO()
- verdict = do_install(identifier, force=force, skip_confirm=True,
- console=Console(file=out, width=200, no_color=True, highlight=False))
- after = entry()
- from tools.skills_sync_bundled_ops import bundled_skill_for_install
- if after is None and verdict is not False and (builtin := bundled_skill_for_install(identifier)):
- return {"name": builtin, "already_installed": verdict is None} # shipped skill, no hub lock entry
- if after is None or (before is not None and after.get("updated_at") == before.get("updated_at")):
- lines = [line.strip() for line in out.getvalue().splitlines() if line.strip()]
- raise RuntimeError(lines[-1] if lines else "the skill was not installed")
- return {"name": str(after["name"]), "already_installed": False}
- @dataclass
- class _Work:
- done: threading.Event = field(default_factory=threading.Event)
- outcome: dict[str, Any] = field(default_factory=dict)
- error: str = ""
- class _Runner:
- """Resolved catalog facts and install work for one operation's rows."""
- def __init__(self, installer: HostInstaller):
- self.installer = installer
- self.op_id: Optional[str] = None
- self.facts: dict[str, Any] = {} # row name -> PluginCatalogEntry | skill meta; never on the wire
- self.work: dict[str, _Work] = {}
- # The Advanced values the user approved per row; Try again (env null) reuses them. Values
- # are credentials in part, so they stay here, off the target.
- self.approved_env: dict[str, dict[str, str]] = {}
- # Built on the tool call's thread: the calling chat's own home is the default install
- # target, and its profile name labels the row (None for a home that is no named profile).
- self.home: Path = get_hermes_home()
- self.label: Optional[str] = profile_name_for_home(self.home)
- # -- prepare: resolve each id and draw its row ------------------------------------------------
- def prepare(self, operation: ConnectionOperation) -> None:
- _RUNNERS[operation.op_id] = self
- self.op_id = operation.op_id
- for target in operation.targets:
- target.extra = {"display": _display(target.name), "target_profile": self.label}
- try:
- self._resolve(target)
- except Exception as exc:
- _fail(operation, target, self._detail(exc, target))
- def _resolve(self, target: Target) -> None:
- if target.kind == "plugin":
- entry = self.installer.plugin_entry(target.name)
- if entry is None:
- raise LookupError(f"'{target.name}' is not in the Hermes plugin catalog")
- self.facts[target.name] = entry
- target.extra = _plugin_row(entry, self.label)
- target.required_env = [{"name": name, "required": False, "secret": True, "default": ""}
- for name in entry.capabilities.requires_env]
- self.installer.refuse(entry)
- return
- meta = self.installer.skill_meta(target.name)
- if not meta:
- raise LookupError(f"'{target.name}' was not found in the skills hub")
- self.facts[target.name] = meta
- target.extra = {
- "display": str(meta.get("name") or _display(target.name)),
- "description": _first_sentence(meta.get("description") or ""),
- "tier": "official" if meta.get("source") == "official" else "community",
- "target_profile": self.label,
- }
- # -- the card's answer ------------------------------------------------------------------------
- def approve(self, operation: ConnectionOperation, target: Target, env: Optional[dict[str, str]]) -> None:
- approved = {**self.approved_env.get(target.name, {}), **(env or {})}
- actor = Actor.user if target.state == TargetState.failed else Actor.backend_watcher
- if target.name not in self.facts: # failed at prepare: Try again resolves once more
- try:
- self._resolve(target)
- except Exception as exc:
- _fail(operation, target, self._detail(exc, target))
- return
- error = self._check_answer(target, approved)
- if error:
- _fail(operation, target, error)
- return
- self.approved_env[target.name] = approved
- # The non-secret choices go on the row, so a Try again after the operation settled repeats
- # what the user approved; the credentials are already in the target profile's .env by then.
- options = {"force": _flag(approved.get("force"), False), "enable": _flag(approved.get("enable"), True),
- "ref": approved.get("ref") or None}
- profile = (approved.get("target_profile") or "").strip()
- if not _move(operation, target, TargetState.initiated, actor, detail="",
- **{**target.extra, "target_profile": profile or self.label, "approved": options}):
- return
- self._spawn(operation, target, approved, options)
- def _check_answer(self, target: Target, env: dict[str, str]) -> str:
- if target.kind == "plugin" and env.get("agent_half") == "0":
- return "only the desktop half was selected; install it from Settings, Plugins"
- ref = env.get("ref")
- if ref and not _COMMIT_SHA.match(ref):
- return "the pin must be a full 40-character commit SHA"
- declared = set(target_declared_env(self.facts.get(target.name)))
- undeclared = sorted(k for k in env if k not in _OPTION_KEYS and k not in declared)
- if undeclared:
- return f"'{target.name}' does not declare {', '.join(undeclared)}"
- return ""
- def _spawn(self, operation: ConnectionOperation, target: Target, env: dict[str, str],
- options: dict[str, Any]) -> None:
- work = _Work()
- self.work[target.name] = work
- def step(phase: InstallPhase) -> None:
- # A row that left ``initiated`` keeps its own state.
- if not operation.settled and target.state == TargetState.initiated:
- operation.refresh(target.name, connect_url=None, detail="", actor=Actor.backend_watcher,
- phase=phase.value)
- def body() -> None:
- try:
- work.outcome = self._install(target, env, options, step)
- except Exception as exc:
- work.error = self._detail(exc, target)
- work.done.set()
- operation.wake.set()
- # A copy of the answering thread's context; the install binds the target profile itself.
- threading.Thread(target=contextvars.copy_context().run, args=(body,), daemon=True,
- name=f"catalog-install-{target.name}").start()
- def _install(self, target: Target, env: dict[str, str], options: dict[str, Any],
- step: Callable[[InstallPhase], None]) -> dict[str, Any]:
- named = (env.get("target_profile") or "").strip()
- with target_scope(_named_home(named) if named else self.home):
- _save_credentials({k: v for k, v in env.items() if k not in _OPTION_KEYS and v})
- if target.kind == "skill":
- meta = self.facts[target.name]
- identifier = str(meta.get("identifier") or target.name)
- step(InstallPhase.downloading)
- return self.installer.install_skill(identifier, force=options["force"], source=meta.get("source"))
- result = self.installer.install_plugin(target.name, force=options["force"], enable=options["enable"],
- ref=options["ref"], on_step=step)
- if not result.get("ok"):
- raise RuntimeError(result.get("error") or "the install failed")
- return {"enabled": options["enable"], **result}
- # -- the watcher --------------------------------------------------------------------------------
- def observe(self, operation: ConnectionOperation) -> None:
- for target in operation.targets:
- work = self.work.get(target.name)
- if operation.settled or target.state != TargetState.initiated or work is None or not work.done.is_set():
- continue
- self.work.pop(target.name, None)
- if work.error:
- _fail(operation, target, work.error)
- continue
- extra, detail = _installed_row(target, work.outcome)
- _move(operation, target, TargetState.connected, Actor.backend_watcher, detail=detail, **extra)
- def close(self) -> None:
- if self.op_id is not None:
- _RUNNERS.pop(self.op_id, None)
- def _detail(self, exc: Any, target: Target) -> str:
- from agent.redact import redact_sensitive_text
- text = str(exc) or exc.__class__.__name__
- # Only credentials are secret: the Advanced choices (a profile name, a commit) stay readable.
- for key, value in self.approved_env.get(target.name, {}).items():
- if key not in _OPTION_KEYS and value and len(value) > 3:
- text = text.replace(value, "[REDACTED]")
- return redact_sensitive_text(text, force=True) or "error"
- def target_declared_env(fact: Any) -> list[str]:
- caps = getattr(fact, "capabilities", None)
- return list(getattr(caps, "requires_env", None) or ())
- def _plugin_row(entry: Any, label: Optional[str]) -> dict[str, Any]:
- from hermes_cli.plugin_catalog_presence import presence
- row: dict[str, Any] = {
- "display": getattr(entry, "title", "") or _display(entry.name),
- "description": _first_sentence(entry.description),
- "tier": entry.tier if entry.tier in _TIERS else "community",
- "repo": entry.repo,
- "sha": entry.sha,
- "requires_hermes": entry.requires_hermes or None,
- "has_desktop_half": False,
- "target_profile": label,
- "app_state": presence(entry).state,
- }
- if entry.platforms:
- row["platforms"] = list(entry.platforms)
- if entry.subdir:
- row["subdir"] = entry.subdir
- return row
- def _installed_row(target: Target, outcome: dict[str, Any]) -> tuple:
- """The connected row's fields (the drawn row plus what went live, as facts the card words) and
- the same notes in one English line for the model."""
- extra = dict(target.extra)
- if target.kind == "skill":
- already = bool(outcome.get("already_installed"))
- detail = "already installed; left as it is (Advanced, force reinstall replaces it)" if already else ""
- return {**extra, "skill": outcome["name"], "tools": [], "already_installed": already}, detail
- live = (outcome.get("activation") or {}).get("live_now") or {}
- servers = live.get("mcp_servers") or []
- tools = [name for server in servers if server.get("connected") for name in server.get("tools") or ()]
- server_errors = [{"name": s["name"], "error": s.get("error") or ""} for s in servers if not s.get("connected")]
- enabled = bool(outcome.get("enabled", True))
- missing_env = list(outcome.get("missing_env") or ())
- notes = [f"MCP server {e['name']} not connected: {e['error'] or 'unknown error'}" for e in server_errors]
- if not enabled:
- notes.append("installed but not enabled")
- if missing_env:
- notes.append(f"set {', '.join(missing_env)} to finish setup")
- skills = [s["name"] for s in live.get("skills") or () if s.get("name")]
- if skills:
- extra["skill"] = skills[0]
- facts = {"tools": tools, "enabled": enabled, "missing_env": missing_env, "server_errors": server_errors}
- return {**extra, **facts}, "; ".join(notes)
- def _save_credentials(env: dict[str, str]) -> None:
- from hermes_cli.config import save_env_value, validate_env_var_name_for_write
- for key, value in env.items():
- validate_env_var_name_for_write(key)
- save_env_value(key, value)
- # op_id -> the runner driving it, so the card's answer (RPC thread) finds the work.
- _RUNNERS: dict[str, _Runner] = {}
- def owns(op_id: str) -> bool:
- return op_id in _RUNNERS
- def apply_answer(operation: ConnectionOperation, raw: str) -> None:
- """The card's ``connection.respond`` for a catalog operation: skip, approve (with the Advanced
- values or null for defaults), approve again on a failed row (Try again), and Continue."""
- try:
- answer = json.loads(raw)
- except (TypeError, ValueError):
- answer = {}
- answer = answer if isinstance(answer, dict) else {}
- runner = _RUNNERS.get(operation.op_id)
- for entry in answer.get("targets") or ():
- if not isinstance(entry, dict):
- continue
- target = operation.target(str(entry.get("name") or "").strip())
- if target is None:
- continue
- status = str(entry.get("status") or "").lower()
- if status == "skipped":
- try:
- operation.transition(target.name, TargetState.skipped, Actor.user)
- except IllegalTransition:
- if not target.resolved and not operation.settled:
- raise
- elif status == "approved" and runner is not None and target.state in (TargetState.pending, TargetState.failed):
- env = entry.get("env")
- runner.approve(operation, target, {str(k): str(v) for k, v in env.items()} if isinstance(env, dict) else None)
- if answer.get("settled_by") == SettleReason.continue_.value and not operation.all_resolved:
- operation.settle(SettleReason.continue_)
- def retry(operation: ConnectionOperation, names: list[str]) -> Optional[str]:
- runner = _RUNNERS.get(operation.op_id)
- if runner is None or operation.settled:
- return "this operation has settled; its result is frozen"
- for name in names:
- target = operation.target(name)
- if target is not None and target.state == TargetState.failed:
- runner.approve(operation, target, None)
- return None
- def open_runner(installer: Optional[HostInstaller] = None) -> _Runner:
- return _Runner(installer or HostInstaller())
- Callback = Callable[[dict[str, Any]], Optional[str]]
|