"""``manage_catalog``: a desktop chat's catalog search and install-through-the-card. ``search`` reads the plugin catalog (the Plugins tab's resolver) and the skills hub and says what is already installed in this chat's profile. ``install`` opens the same connection operation ``manage_connections`` opens, with rows of kind ``plugin`` / ``skill``; the host installs each row the user approves (``tools/connectors/catalog.py``). The model sends catalog ids and an action, nothing else: the pin, scan, target profile and activation are the host's. """ from __future__ import annotations import json from typing import Any, Callable, Dict, List, Optional from tools.registry import tool_error ACTIONS = ("search", "install") ITEM_KINDS = ("plugin", "skill") _TOP_KEYS = frozenset({"action", "kind", "query", "items", "reason"}) _ITEM_KEYS = frozenset({"kind", "id"}) SEARCH_LIMIT = 10 NOT_HERE = ( "manage_catalog is available only in the Hermes desktop app, where the approval card can be drawn. " "Tell the user to install from a terminal instead: `hermes plugins install ` for a plugin, " "`hermes skills install ` for a skill." ) NOTE = ( "Settled once; do not re-offer a row the user skipped. Each installed row names target_profile: " "its tools and skills are live now in that profile's open chats and in every new chat of it; " "they are callable in this chat only when this chat runs in that profile. A failed row carries " "the reason in detail." ) MANAGE_CATALOG_SCHEMA = { "name": "manage_catalog", "description": ( "Find and install Hermes catalog plugins and hub skills for the user. 'search' lists matches " "(id, kind, display, tier, platforms, installed) and changes nothing. 'install' shows the user " "one approval card with a row per item and blocks until every row is installed, skipped or " "failed, or the card is closed; the host installs each approved row into this chat's profile at " "the catalog's reviewed version, and turns on a catalog plugin that is installed but not " "enabled. Pass only catalog ids exactly as 'search' returns them; the " "host decides the source, version, profile and settings, and the user can change them on the " "card. Offer an install only for something the user asked for or agreed to." ), "parameters": { "type": "object", "properties": { "action": {"type": "string", "enum": list(ACTIONS)}, "kind": {"type": "string", "enum": list(ITEM_KINDS), "description": "search only: limit results to plugins or skills."}, "query": {"type": "string", "description": "search only: words to match; empty lists plugins."}, "items": { "type": "array", "description": "install only: the catalog items to offer, one card row each.", "items": { "type": "object", "properties": { "kind": {"type": "string", "enum": list(ITEM_KINDS)}, "id": {"type": "string", "description": "Catalog id as 'search' returns it."}, }, "required": ["kind", "id"], "additionalProperties": False, }, }, "reason": {"type": "string", "description": "install only: one line on why these are offered."}, }, "required": ["action"], "additionalProperties": False, }, } def _check_args(args: dict[str, Any]) -> Optional[str]: unknown = sorted(set(args) - _TOP_KEYS) if unknown: return (f"unknown parameter(s) {', '.join(unknown)}: manage_catalog takes action, kind, query, " "items and reason. The host decides source, version, profile and settings.") if args.get("action") not in ACTIONS: return f"action must be one of {', '.join(ACTIONS)}." if args.get("kind") not in (None, *ITEM_KINDS): return f"kind must be one of {', '.join(ITEM_KINDS)}." if args["action"] == "search": return None items = args.get("items") if not isinstance(items, list) or not items: return "install needs 'items': [{\"kind\": \"plugin\", \"id\": \"\"}, ...]." for item in items: if not isinstance(item, dict): return "every item is an object {kind, id}." extra = sorted(set(item) - _ITEM_KEYS) if extra: return (f"unknown item field(s) {', '.join(extra)}: an item is {{kind, id}}. The host decides " "source, version, profile and settings.") if item.get("kind") not in ITEM_KINDS or not str(item.get("id") or "").strip(): return "every item needs kind (plugin or skill) and a non-empty id." return None def manage_catalog( args: dict[str, Any], *, session_id: Optional[str] = None, tool_call_id: Optional[str] = None, connection_callback: Optional[Callable[[dict[str, Any]], Optional[str]]] = None, card_surface: bool = False, installer: Any = None, ) -> str: """``card_surface``: the session is a desktop chat, the one surface that draws catalog rows.""" error = _check_args(args) if error: return tool_error(error) if connection_callback is None or not card_surface: return tool_error(NOT_HERE) if args["action"] == "search": return json.dumps(search(str(args.get("query") or ""), args.get("kind"), installer=installer), ensure_ascii=False) return install(args["items"], session_id=session_id, tool_call_id=tool_call_id, connection_callback=connection_callback, installer=installer) def install(items: list[dict[str, str]], *, session_id: Optional[str], tool_call_id: Optional[str], connection_callback: Callable[[dict[str, Any]], Optional[str]], installer: Any = None) -> str: from tools.connectors.catalog import open_runner from tools.connectors.gateway.config import operation_session_key from tools.connectors.operation import Target from tools.connectors.run import Kind, run_operation seen, targets = set(), [] for item in items: key = (item["kind"], str(item["id"]).strip()) if key not in seen: seen.add(key) targets.append(Target(name=key[1], kind=key[0], action="install")) runner = open_runner(installer) try: return run_operation( targets, Kind(prepare=runner.prepare, observe=runner.observe, note=NOTE), session_key=operation_session_key(session_id), tool_call_id=tool_call_id, connection_callback=connection_callback, with_urls_in_result=False, ) finally: runner.close() def search(query: str, kind: Optional[str], *, installer: Any = None) -> dict[str, Any]: """Runs on the tool call's thread, in this chat's profile scope, so ``installed`` is this chat's profile's.""" from hermes_constants import get_hermes_home, profile_name_for_home rows: list[dict[str, Any]] = [] if kind in (None, "plugin"): rows += _plugin_rows(query) if kind in (None, "skill") and query.strip(): rows += _skill_rows(query) return {"results": rows, "installed_in": profile_name_for_home(get_hermes_home())} def _plugin_rows(query: str) -> list[dict[str, Any]]: from hermes_cli.plugin_catalog import filter_entries, load_catalog_live from hermes_cli.plugins_cmd import PluginOperationError, _read_install_metadata from tools.connectors.catalog import _display try: installed = {str(rec["catalog"]["name"]) for rec in _read_install_metadata().values() if isinstance(rec, dict) and isinstance(rec.get("catalog"), dict) and rec["catalog"].get("name")} except PluginOperationError: installed = set() return [{"id": e.name, "kind": "plugin", "display": _display(e.name), "tier": e.tier, "platforms": list(e.platforms), "installed": e.name in installed} for e in filter_entries(load_catalog_live(), query)[:SEARCH_LIMIT]] def _skill_rows(query: str) -> list[dict[str, Any]]: from tools.skills_hub import HubLockFile, installed_entry from tools.skills_hub_github import GitHubAuth from tools.skills_hub_search import create_source_router, unified_search installed = HubLockFile().by_identifier() return [{"id": r.identifier, "kind": "skill", "display": r.name, "tier": "official" if r.source == "official" else "community", "platforms": [], "installed": installed_entry(installed, r.identifier, r.source) is not None} for r in unified_search(query, create_source_router(GitHubAuth()), limit=SEARCH_LIMIT)]