478 lines
20 KiB
Python
478 lines
20 KiB
Python
"""Plugin manifest model and parsing (``plugin.yaml`` v1/v2, portable ``plugin.json``).
|
||
|
||
Split out of :mod:`hermes_cli.plugins`; validation warns and never fails a load.
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
import hashlib
|
||
import importlib.util
|
||
import logging
|
||
from contextlib import suppress
|
||
from dataclasses import dataclass, field
|
||
from pathlib import Path
|
||
from typing import Any, Dict, List, Mapping, Optional, Set, Union
|
||
|
||
from utils import fast_safe_load
|
||
from hermes_cli.plugin_capabilities import parse_declared_capabilities as _parse_declared_capabilities
|
||
|
||
try:
|
||
import yaml
|
||
except ImportError: # pragma: no cover – yaml is optional at import time
|
||
yaml = None # type: ignore[assignment]
|
||
|
||
logger = logging.getLogger("hermes_cli.plugins")
|
||
|
||
|
||
def _plugins_debug() -> bool:
|
||
from hermes_cli import plugins as _origin
|
||
return _origin._PLUGINS_DEBUG
|
||
|
||
|
||
_VALID_PLUGIN_KINDS: Set[str] = {"standalone", "backend", "exclusive", "platform", "model-provider"}
|
||
|
||
|
||
def _portable_skill_namespace(key: str) -> str:
|
||
"""Return a readable, collision-resistant namespace for a portable plugin."""
|
||
|
||
slug = "".join(
|
||
ch if ch.isascii() and (ch.isalnum() or ch in "_-") else "-" for ch in key.lower()
|
||
)
|
||
slug = slug.strip("-_") or "plugin"
|
||
digest = hashlib.sha256(key.encode("utf-8")).hexdigest()[:8]
|
||
return f"agent-plugin-{slug}-{digest}"
|
||
|
||
|
||
def _display_author(value: object) -> str:
|
||
"""Normalize a manifest author value for the string PluginManifest field."""
|
||
if isinstance(value, Mapping):
|
||
return ", ".join(
|
||
str(value[field]) for field in ("name", "email", "url") if value.get(field)
|
||
)
|
||
return "" if value is None else str(value)
|
||
|
||
|
||
# Manifest v2 parsing. Unknown plugin.yaml fields are forward-compat surface: warn (debug for v1
|
||
# files, warning for v2+) and continue loading.
|
||
_KNOWN_MANIFEST_FIELDS: Set[str] = {
|
||
# v1
|
||
"name", "version", "description", "author", "requires_env",
|
||
"provides_tools", "provides_hooks", "kind", "hooks", "label",
|
||
"optional_env", "platforms", "external_dependencies", "pip_dependencies",
|
||
"provides_browser_providers", "provides_web_providers",
|
||
# v2
|
||
"manifest_version", "api_version", "requires_plugins",
|
||
"python_dependencies", "config_schema", "license", "homepage", "tags",
|
||
# owned by sibling sub-issues but reserved so their manifests don't warn
|
||
"capabilities", "emits", "listens", "hermes", "depends",
|
||
}
|
||
|
||
|
||
# Highest manifest schema version this Hermes understands.
|
||
SUPPORTED_MANIFEST_VERSION = 2
|
||
|
||
|
||
_CONFIG_SCHEMA_TYPES: Dict[str, tuple] = {
|
||
"str": (str,), "string": (str,), "int": (int,), "integer": (int,), "float": (int, float),
|
||
"number": (int, float), "bool": (bool,), "boolean": (bool,), "list": (list,), "array": (list,),
|
||
"dict": (dict,), "object": (dict,),
|
||
}
|
||
|
||
|
||
def _manifest_field_of_type(data: Mapping, key: str, field_name: str, typ, what: str):
|
||
"""Return ``data[field_name]`` when absent or of ``typ``; warn and return None otherwise."""
|
||
raw = data.get(field_name)
|
||
if raw is not None and not isinstance(raw, typ):
|
||
logger.warning("Plugin %s: %s must be %s; ignoring", key, field_name, what)
|
||
return None
|
||
return raw
|
||
|
||
|
||
def _parse_manifest_v2_fields(data: Mapping, key: str) -> Dict[str, Any]:
|
||
"""Validate/normalize manifest v2 fields into PluginManifest kwargs (warnings, never failures)."""
|
||
out: Dict[str, Any] = {}
|
||
|
||
# manifest_version — absent means v1 (supported forever).
|
||
raw_mv = data.get("manifest_version", 1)
|
||
try:
|
||
mv = int(raw_mv)
|
||
except (TypeError, ValueError):
|
||
logger.warning(
|
||
"Plugin %s: manifest_version %r is not an integer; treating as 1", key, raw_mv,
|
||
)
|
||
mv = 1
|
||
if mv > SUPPORTED_MANIFEST_VERSION:
|
||
logger.warning(
|
||
"Plugin %s: manifest_version %d is newer than this Hermes "
|
||
"supports (%d); loading anyway and ignoring unknown fields",
|
||
key, mv, SUPPORTED_MANIFEST_VERSION,
|
||
)
|
||
out["manifest_version"] = mv
|
||
|
||
# api_version — plugin API generation (independent of manifest_version).
|
||
raw_api = data.get("api_version")
|
||
out["api_version"] = None
|
||
if raw_api is not None:
|
||
try:
|
||
out["api_version"] = int(raw_api)
|
||
except (TypeError, ValueError):
|
||
logger.warning("Plugin %s: api_version %r is not an integer; ignoring", key, raw_api)
|
||
|
||
# requires_plugins — list of {id, version_range?} (str shorthand ok).
|
||
deps: List[Dict[str, Any]] = []
|
||
for item in _manifest_field_of_type(data, key, "requires_plugins", list, "a list") or []:
|
||
if isinstance(item, str):
|
||
deps.append({"id": item, "version_range": None})
|
||
elif isinstance(item, Mapping) and isinstance(item.get("id"), str) and item["id"]:
|
||
vr = item.get("version_range")
|
||
deps.append({"id": item["id"], "version_range": str(vr) if vr is not None else None})
|
||
else:
|
||
logger.warning(
|
||
"Plugin %s: requires_plugins entry %r must be a plugin id "
|
||
"string or a {id, version_range} mapping; skipping", key, item,
|
||
)
|
||
out["requires_plugins"] = deps
|
||
|
||
# python_dependencies — validated and surfaced ONLY; never auto-installed.
|
||
pydeps: List[str] = []
|
||
raw_pydeps = _manifest_field_of_type(
|
||
data, key, "python_dependencies", list, "a list of requirement strings"
|
||
)
|
||
for item in raw_pydeps or []:
|
||
if isinstance(item, str) and item.strip():
|
||
pydeps.append(item.strip())
|
||
else:
|
||
logger.warning(
|
||
"Plugin %s: python_dependencies entry %r must be a non-empty "
|
||
"requirement string; skipping", key, item,
|
||
)
|
||
out["python_dependencies"] = pydeps
|
||
|
||
# config_schema — mapping of key -> {type?, default?, description?, required?}.
|
||
schema: Dict[str, Any] = {}
|
||
raw_schema = _manifest_field_of_type(data, key, "config_schema", Mapping, "a mapping")
|
||
for skey, spec in (raw_schema or {}).items():
|
||
if not isinstance(spec, Mapping):
|
||
logger.warning(
|
||
"Plugin %s: config_schema entry %r must be a mapping "
|
||
"(e.g. {type: str}); skipping", key, skey,
|
||
)
|
||
continue
|
||
stype = spec.get("type")
|
||
if stype is not None and str(stype).lower() not in _CONFIG_SCHEMA_TYPES:
|
||
logger.warning(
|
||
"Plugin %s: config_schema key %r declares unknown type %r "
|
||
"(known: %s); type check will be skipped for it",
|
||
key, skey, stype, ", ".join(sorted(_CONFIG_SCHEMA_TYPES)),
|
||
)
|
||
schema[str(skey)] = dict(spec)
|
||
out["config_schema"] = schema
|
||
|
||
# Standard metadata.
|
||
out["license"] = str(data.get("license") or "")
|
||
out["homepage"] = str(data.get("homepage") or "")
|
||
raw_tags = _manifest_field_of_type(data, key, "tags", list, "a list")
|
||
out["tags"] = [str(t) for t in (raw_tags or [])]
|
||
|
||
# Forward compat: unknown fields warn (never fail); v1 manifests only at debug.
|
||
unknown = sorted(set(data.keys()) - _KNOWN_MANIFEST_FIELDS)
|
||
if unknown:
|
||
log = logger.warning if mv >= 2 else logger.debug
|
||
log(
|
||
"Plugin %s: unknown manifest field(s) ignored: %s "
|
||
"(newer manifest schema or typo; plugin still loads)", key, ", ".join(unknown),
|
||
)
|
||
|
||
return out
|
||
|
||
|
||
def validate_config_schema(plugin_id: str, schema: Mapping, settings: Mapping) -> List[str]:
|
||
"""Return actionable warning strings for settings vs config_schema mismatches (never raises)."""
|
||
warnings: List[str] = []
|
||
if not isinstance(schema, Mapping) or not isinstance(settings, Mapping):
|
||
return warnings
|
||
for skey, spec in schema.items():
|
||
if not isinstance(spec, Mapping):
|
||
continue
|
||
present = skey in settings
|
||
if not present:
|
||
if spec.get("required") and "default" not in spec:
|
||
warnings.append(
|
||
f"plugins.entries.{plugin_id}.settings.{skey} is required "
|
||
"by the plugin's config_schema but is not set"
|
||
)
|
||
continue
|
||
stype = spec.get("type")
|
||
expected = _CONFIG_SCHEMA_TYPES.get(str(stype).lower()) if stype else None
|
||
if expected is not None:
|
||
value = settings[skey]
|
||
# bool is an int subclass — don't let True satisfy int/float.
|
||
ok = isinstance(value, expected) and not (
|
||
isinstance(value, bool) and bool not in expected
|
||
)
|
||
if not ok:
|
||
warnings.append(
|
||
f"plugins.entries.{plugin_id}.settings.{skey} should be "
|
||
f"{stype} (got {type(value).__name__})"
|
||
)
|
||
return warnings
|
||
|
||
|
||
def resolve_plugin_load_order(manifests: Mapping[str, "PluginManifest"]) -> List[str]:
|
||
"""Return plugin keys in dependency order: B before A when A requires B; alphabetical ties.
|
||
|
||
A cycle warns and falls back to alphabetical order for all; a missing dependency warns once
|
||
but never removes the dependent plugin (loads never hard-fail on advisory deps).
|
||
"""
|
||
import graphlib
|
||
keys = sorted(manifests.keys())
|
||
by_name: Dict[str, str] = {}
|
||
for k in keys:
|
||
name = manifests[k].name
|
||
if name and name not in by_name:
|
||
by_name[name] = k
|
||
|
||
def _resolve_dep(dep_id: str) -> Optional[str]:
|
||
if dep_id in manifests:
|
||
return dep_id
|
||
return by_name.get(dep_id)
|
||
|
||
edges: Dict[str, Set[str]] = {k: set() for k in keys}
|
||
for k in keys:
|
||
for dep in manifests[k].requires_plugins:
|
||
dep_id = dep.get("id") if isinstance(dep, Mapping) else None
|
||
if not dep_id:
|
||
continue
|
||
resolved = _resolve_dep(dep_id)
|
||
if resolved is None:
|
||
logger.warning(
|
||
"Plugin %s requires plugin '%s' which is not enabled/"
|
||
"installed; loading anyway (probe availability at runtime "
|
||
"via ctx.has_plugin). Run `hermes plugins enable %s` if it is installed.",
|
||
k, dep_id, dep_id,
|
||
)
|
||
continue
|
||
if resolved == k:
|
||
logger.warning("Plugin %s declares a dependency on itself; ignoring", k)
|
||
continue
|
||
edges[k].add(resolved)
|
||
|
||
sorter = graphlib.TopologicalSorter(edges)
|
||
try:
|
||
sorter.prepare()
|
||
except graphlib.CycleError as exc:
|
||
cycle = exc.args[1] if len(exc.args) > 1 else []
|
||
logger.warning(
|
||
"Plugin dependency cycle detected (%s); falling back to "
|
||
"alphabetical load order for all plugins", " -> ".join(str(c) for c in cycle),
|
||
)
|
||
return keys
|
||
|
||
ordered: List[str] = []
|
||
while sorter.is_active():
|
||
ready = sorted(sorter.get_ready())
|
||
ordered.extend(ready)
|
||
sorter.done(*ready)
|
||
return ordered
|
||
|
||
|
||
def _detect_kind_from_source(source_text: str) -> Optional[str]:
|
||
"""Return the kind implied by source markers (mirrors plugins/memory ``_is_memory_provider_dir``).
|
||
|
||
Memory-provider markers -> ``exclusive``; ``register_provider`` + ``ProviderProfile`` ->
|
||
``model-provider``; else ``None``. Keeps both kinds out of the general manager's eager import.
|
||
"""
|
||
if "register_memory_provider" in source_text or "MemoryProvider" in source_text:
|
||
return "exclusive"
|
||
if "register_provider" in source_text and "ProviderProfile" in source_text:
|
||
return "model-provider"
|
||
return None
|
||
|
||
|
||
def _read_source_from_origin(origin: Optional[str], limit: int = 8192) -> str:
|
||
"""First ``limit`` chars of a module's source (``.pyc`` mapped back to ``.py``); "" on failure."""
|
||
if not origin:
|
||
return ""
|
||
if origin.endswith((".pyc", ".pyo")):
|
||
try:
|
||
origin = importlib.util.source_from_cache(origin)
|
||
except Exception:
|
||
return ""
|
||
if not origin.endswith(".py"):
|
||
return ""
|
||
try:
|
||
return Path(origin).read_text(encoding="utf-8", errors="replace")[:limit]
|
||
except Exception:
|
||
return ""
|
||
|
||
|
||
def resolve_module_origin(module_name: str) -> Optional[str]:
|
||
"""Return a module's source path WITHOUT importing it, or ``None``.
|
||
|
||
``find_spec`` on a dotted name imports the parent package, so only the top-level name uses it;
|
||
remaining segments are walked through ``submodule_search_locations`` by hand. Namespace/zipped/
|
||
extension modules return ``None``. Shared with ``plugins/memory/__init__.py``.
|
||
"""
|
||
parts = [p for p in module_name.split(".") if p]
|
||
if not parts:
|
||
return None
|
||
try:
|
||
spec = importlib.util.find_spec(parts[0])
|
||
if spec is None or not spec.origin:
|
||
return None
|
||
if len(parts) == 1:
|
||
return spec.origin
|
||
|
||
search_paths = spec.submodule_search_locations
|
||
if not search_paths:
|
||
return None
|
||
for i, part in enumerate(parts[1:], start=2):
|
||
found_origin = None
|
||
next_paths = None
|
||
for base in search_paths:
|
||
base = Path(base)
|
||
pkg_init = base / part / "__init__.py"
|
||
if pkg_init.is_file():
|
||
found_origin = str(pkg_init)
|
||
next_paths = [base / part]
|
||
break
|
||
mod_file = base / (part + ".py")
|
||
if mod_file.is_file():
|
||
found_origin = str(mod_file)
|
||
break
|
||
if found_origin is None:
|
||
return None
|
||
if i == len(parts) or next_paths is None:
|
||
return found_origin
|
||
search_paths = next_paths
|
||
return None
|
||
except Exception:
|
||
return None
|
||
|
||
|
||
def _resolve_module_source(module_name: str, limit: int = 8192) -> str:
|
||
"""First ``limit`` chars of a module's source without importing it ("" when unresolvable)."""
|
||
return _read_source_from_origin(resolve_module_origin(module_name), limit)
|
||
|
||
|
||
def manifest_key(manifest: "PluginManifest") -> str:
|
||
"""Registry id of a manifest: the path-derived ``key`` when set, else the bare ``name``."""
|
||
return manifest.key or manifest.name
|
||
|
||
|
||
@dataclass
|
||
class PluginManifest:
|
||
"""Parsed representation of a plugin.yaml manifest."""
|
||
|
||
name: str
|
||
version: str = ""
|
||
description: str = ""
|
||
author: str = ""
|
||
requires_env: List[Union[str, Dict[str, Any]]] = field(default_factory=list)
|
||
provides_tools: List[str] = field(default_factory=list)
|
||
provides_hooks: List[str] = field(default_factory=list)
|
||
source: str = "" # "bundled", "user", "project", or "entrypoint"
|
||
path: Optional[str] = None
|
||
# ``standalone`` (default; opt-in via plugins.enabled) | ``backend`` (pluggable backend for a
|
||
# core tool; bundled auto-load, user-installed gated) | ``exclusive`` (one active provider,
|
||
# selected via <category>.provider; own discovery, general scanner skips) | ``platform``
|
||
# (gateway adapter; bundled auto-load, user-installed gated as untrusted code).
|
||
kind: str = "standalone"
|
||
# Path-derived registry key used by plugins.enabled/disabled and `hermes plugins list`:
|
||
# ``disk-cleanup`` for a flat plugin, ``image_gen/openai`` for a category plugin. Empty -> name.
|
||
key: str = ""
|
||
portable: bool = False
|
||
skill_namespace: str = ""
|
||
# Declared capability ids, normalized to KNOWN ids. Declaration is consent metadata, NOT a
|
||
# grant: live only via plugins.entries.<id>.granted_capabilities or the legacy allow_* key.
|
||
capabilities: List[str] = field(default_factory=list)
|
||
# Manifest v2 fields — all optional and additive. manifest_version versions the FILE FORMAT
|
||
# (v1 supported forever); api_version is the runtime plugin API generation (None = current).
|
||
manifest_version: int = 1
|
||
api_version: Optional[int] = None
|
||
# Advisory deps [{"id", "version_range"}]: missing ones warn but load; they order the load.
|
||
requires_plugins: List[Dict[str, Any]] = field(default_factory=list)
|
||
# Declared pip deps — VALIDATED AND SURFACED ONLY, never auto-installed.
|
||
python_dependencies: List[str] = field(default_factory=list)
|
||
# Schema for plugins.entries.<id>.settings; mismatches warn, never fail.
|
||
config_schema: Dict[str, Any] = field(default_factory=dict)
|
||
license: str = ""
|
||
homepage: str = ""
|
||
tags: List[str] = field(default_factory=list)
|
||
# Event-bus declarations, advisory (discoverability only): ``emits`` bare names published under
|
||
# ``<key>:``; ``listens`` fully-qualified ``<plugin>:<event>`` names.
|
||
emits: List[str] = field(default_factory=list)
|
||
listens: List[str] = field(default_factory=list)
|
||
|
||
|
||
def portable_plugin_manifest(child: Path, source: str, prefix: str) -> PluginManifest:
|
||
"""Build the manifest for a portable Agent Plugin directory (``plugin.json``); diagnostics warn."""
|
||
from hermes_cli.agent_plugins import read_agent_plugin_manifest
|
||
data, diagnostics = read_agent_plugin_manifest(child)
|
||
for diagnostic in diagnostics:
|
||
logger.warning("Agent Plugin '%s': %s", child, diagnostic.message)
|
||
key = f"{prefix}/{child.name}" if prefix else data["name"]
|
||
return PluginManifest(
|
||
name=data["name"], version=data.get("version", ""), description=data.get("description", ""),
|
||
author=_display_author(data.get("author", "")), source=source, path=str(child), key=key,
|
||
portable=True, skill_namespace=_portable_skill_namespace(key),
|
||
)
|
||
|
||
|
||
def _manifest_kind(data: Mapping, key: str, plugin_dir: Path) -> str:
|
||
"""Normalize ``kind``; undeclared memory/model providers are auto-detected from ``__init__.py``
|
||
so they route to their own discovery instead of the general manager."""
|
||
raw_kind = data.get("kind", "standalone")
|
||
if not isinstance(raw_kind, str):
|
||
raw_kind = "standalone"
|
||
kind = raw_kind.strip().lower()
|
||
if kind not in _VALID_PLUGIN_KINDS:
|
||
logger.warning(
|
||
"Plugin %s: unknown kind '%s' (valid: %s); treating as 'standalone'",
|
||
key, raw_kind, ", ".join(sorted(_VALID_PLUGIN_KINDS)),
|
||
)
|
||
kind = "standalone"
|
||
if kind == "standalone" and "kind" not in data:
|
||
init_file = plugin_dir / "__init__.py"
|
||
if init_file.exists():
|
||
with suppress(Exception):
|
||
detected = _detect_kind_from_source(
|
||
init_file.read_text(errors="replace", encoding="utf-8")[:8192]
|
||
)
|
||
if detected:
|
||
kind = detected
|
||
logger.debug("Plugin %s: detected %s, treating as kind='%s'", key, detected, detected)
|
||
return kind
|
||
|
||
|
||
def parse_manifest_file(
|
||
manifest_file: Path, plugin_dir: Path, source: str, prefix: str
|
||
) -> Optional[PluginManifest]:
|
||
"""Parse one ``plugin.yaml`` into a :class:`PluginManifest`; ``None`` (warned) on failure."""
|
||
try:
|
||
if yaml is None:
|
||
logger.warning("PyYAML not installed – cannot load %s", manifest_file)
|
||
return None
|
||
data = fast_safe_load(manifest_file.read_text(encoding="utf-8")) or {}
|
||
name = data.get("name", plugin_dir.name)
|
||
key = f"{prefix}/{plugin_dir.name}" if prefix else name
|
||
kind = _manifest_kind(data, key, plugin_dir)
|
||
logger.debug(
|
||
"Parsed manifest: key=%s name=%s kind=%s source=%s path=%s",
|
||
key, name, kind, source, plugin_dir,
|
||
)
|
||
return PluginManifest(
|
||
name=name, version=str(data.get("version", "")),
|
||
description=data.get("description", ""), author=_display_author(data.get("author", "")),
|
||
requires_env=data.get("requires_env", []),
|
||
provides_tools=data.get("provides_tools", []),
|
||
provides_hooks=data.get("provides_hooks", []), source=source, path=str(plugin_dir),
|
||
kind=kind, key=key,
|
||
capabilities=_parse_declared_capabilities(data.get("capabilities"), name),
|
||
**_parse_manifest_v2_fields(data, key), emits=data.get("emits") or [],
|
||
listens=data.get("listens") or [],
|
||
)
|
||
except Exception as exc:
|
||
logger.warning("Failed to parse %s: %s", manifest_file, exc, exc_info=_plugins_debug())
|
||
return None
|