plugins_aux_tasks.py 3.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354
  1. """Validation and entry shape for ``PluginContext.register_auxiliary_task``."""
  2. from __future__ import annotations
  3. import logging
  4. from typing import Any, Dict, Optional
  5. logger = logging.getLogger("hermes_cli.plugins")
  6. def build_auxiliary_task_entry(
  7. me: str, owner_id: str, key: str, *, display_name: str, description: str,
  8. defaults: Optional[dict[str, Any]], inherit_from: Optional[str], registered: dict[str, dict[str, Any]],
  9. ) -> dict[str, Any]:
  10. """Registry entry for a plugin auxiliary task, or ``ValueError`` for a bad key.
  11. ``me`` is the manifest name (for messages); ``owner_id`` is the canonical id ``ctx.llm`` is
  12. bound to, so agent/plugin_llm.py can match it. ``registered`` is the manager's current
  13. ``_aux_tasks`` (re-registration by the same owner is allowed).
  14. """
  15. if not key or not isinstance(key, str):
  16. raise ValueError(f"Plugin '{me}' tried to register auxiliary task with invalid key {key!r}")
  17. if not all(c.isalnum() or c == "_" for c in key):
  18. raise ValueError(f"Plugin '{me}' auxiliary task key {key!r} "
  19. f"must contain only alphanumeric characters and underscores")
  20. from hermes_cli.main_provider_setup import _AUX_TASKS as _BUILTIN_AUX_TASKS
  21. builtin_aux_keys = {k for k, _name, _desc in _BUILTIN_AUX_TASKS}
  22. if key in builtin_aux_keys:
  23. raise ValueError(f"Plugin '{me}' cannot register auxiliary task {key!r} — that key is reserved "
  24. f"for a built-in task. Pick a plugin-namespaced key (e.g. '{me}_{key}').")
  25. existing = registered.get(key)
  26. if existing is not None and existing.get("plugin") != owner_id:
  27. raise ValueError(f"Plugin '{me}' cannot register auxiliary task {key!r} — already registered "
  28. f"by plugin '{existing.get('plugin')}'")
  29. # A bad base degrades to "no inheritance" rather than failing the whole plugin load; a
  30. # self-reference would otherwise only surface at read time, as a cycle.
  31. if inherit_from is not None and (
  32. not isinstance(inherit_from, str) or inherit_from == key
  33. or (inherit_from not in builtin_aux_keys and inherit_from not in registered)):
  34. logger.warning("Plugin '%s' auxiliary task %r: ignoring inherit_from=%r — not a built-in "
  35. "auxiliary task or one already registered by a plugin", me, key, inherit_from)
  36. inherit_from = None
  37. # Plugin owns the schema; routing fields are guaranteed present so consumers don't crash.
  38. # With inheritance the base supplies the shape, so only the plugin's own overrides go here.
  39. task_defaults = (dict(defaults or {}) if inherit_from else
  40. {"provider": "auto", "model": "", "base_url": "", "api_key": "", "timeout": 60,
  41. "extra_body": {}, **(defaults or {})})
  42. entry = {
  43. "key": key, "display_name": display_name, "description": description,
  44. "defaults": task_defaults,
  45. "inherit_from": inherit_from,
  46. "plugin": owner_id, "plugin_key": owner_id,
  47. }
  48. return entry