delegation_provider.py 5.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110
  1. """Delegation Provider ABC.
  2. A delegation provider decides HOW one ``delegate_task`` task becomes a child run: which model,
  3. provider, endpoint and reasoning effort the child uses, or which Hermes profile it runs as. It may
  4. also add per-task parameters to the ``delegate_task`` schema (an enum of profile names, of titled
  5. model options, ...). Providers register via :meth:`PluginContext.register_delegation_provider`;
  6. ``delegation.backend`` in config.yaml selects the active one (unset = ``default``, today's
  7. behaviour, provided by the bundled ``plugins/delegation/default`` plugin). Core keeps the whole lifecycle (spawn, isolation, roles, depth, concurrency,
  8. background units, stop fan-out, results, ``output_schema``, progress); a provider only answers
  9. "which route does this task take".
  10. Everything crossing this interface is plain JSON data (no live agent objects), so a provider runs
  11. unchanged in-process and under ``plugins.isolation: host``.
  12. Route vocabulary (:meth:`DelegationProvider.route_task` returns a dict with any of):
  13. * ``model``, ``provider``, ``base_url``, ``api_key``, ``api_mode``, ``request_overrides``,
  14. ``reasoning_effort``, ``fallback_providers`` - shaped exactly like the ``delegation`` config
  15. section and resolved by the same credential resolver ``delegation.*`` uses (empty route = the
  16. child inherits the parent's route, like an empty ``delegation`` section). An unknown
  17. ``reasoning_effort`` refuses the task.
  18. * ``service_tier`` - ``normal``, ``fast`` or ``ultrafast``, checked like ``/fast`` against the
  19. resolved route (and, for ultrafast, the Codex account); a tier the route does not offer refuses
  20. the task, and the tier is re-applied after the child is built.
  21. * ``profile`` - the name of a Hermes profile. Core runs the child as that profile: its config,
  22. primary model and credentials, skills, ``SOUL.md`` and terminal policy, bound through the same
  23. scope helpers a multiplexed gateway uses for a routed turn. A profile route ignores the other
  24. route keys; the profile's own config decides them.
  25. * ``label`` - short text shown with the child's progress and result (e.g. the option title).
  26. A backend's own settings live under ``delegation.backends.<backend name>`` (:meth:`DelegationProvider.settings`),
  27. never beside the core ``delegation`` keys.
  28. """
  29. from __future__ import annotations
  30. import abc
  31. from typing import Any, Mapping
  32. from agent.provider_base import ProviderBase
  33. #: Per-task property names core owns. A provider-declared parameter with one of these names is
  34. #: refused at schema-build time: plugins add parameters, they never redefine core ones, and the
  35. #: raw route fields (``provider``/``model``/``base_url``/``api_key``) never become model-facing.
  36. RESERVED_TASK_PARAMETERS = frozenset({
  37. "goal", "context", "index", "output_schema", "images", "group", "role", "toolsets",
  38. "acp_command", "acp_args", "provider", "model", "base_url", "api_key", "api_mode",
  39. })
  40. #: Keys a route may carry; anything else in a provider's answer is ignored.
  41. ROUTE_KEYS = frozenset({
  42. "model", "provider", "base_url", "api_key", "api_mode", "request_overrides",
  43. "reasoning_effort", "service_tier", "fallback_providers", "profile", "label",
  44. })
  45. class DelegationRouteError(ValueError):
  46. """Raised by :meth:`DelegationProvider.route_task` to refuse a task; the message becomes the
  47. ``delegate_task`` tool error the model reads, so phrase it as an instruction."""
  48. class DelegationProvider(ProviderBase):
  49. """Abstract base class for a pluggable delegation strategy.
  50. :attr:`name` is the ``delegation.backend`` value. Every method receives ``config``, the
  51. ``delegation`` section of the active profile's config.yaml (read-only): ``dict(config)`` is the
  52. default route, and :meth:`settings` is this backend's own block, ``delegation.backends.<name>``.
  53. """
  54. def settings(self, config: Mapping[str, Any]) -> Mapping[str, Any]:
  55. """This backend's settings: ``delegation.backends.<name>`` (empty when unset or not a mapping)."""
  56. backends = config.get("backends") if isinstance(config, Mapping) else None
  57. own = backends.get(self.name) if isinstance(backends, Mapping) else None
  58. return own if isinstance(own, Mapping) else {}
  59. @property
  60. def summary(self) -> str:
  61. """One user-facing line for backend pickers (``/delegation``); never shown to the model."""
  62. return ""
  63. def is_available(self) -> bool:
  64. """Whether this provider can run here. MUST NOT make network calls. False fails delegation closed: a
  65. ``delegate_task`` call under this backend is a tool error naming it, never a run on another route."""
  66. return True
  67. def task_parameters(self, config: Mapping[str, Any]) -> dict[str, dict[str, Any]]:
  68. """Extra per-task JSON-schema properties, ``{name: schema}``, merged into
  69. ``delegate_task``'s ``tasks.items.properties``.
  70. Called when the tool definitions are built for a session, never mid-conversation, and the
  71. result must be deterministic for a given ``config`` (same input, same bytes): the schema
  72. is part of the cached prompt prefix. Names in :data:`RESERVED_TASK_PARAMETERS` are
  73. refused. An ``enum`` here is enforced by core before :meth:`route_task` runs, and a task
  74. carrying a parameter this method did not declare is refused before it reaches you.
  75. """
  76. return {}
  77. def description(self, config: Mapping[str, Any]) -> str:
  78. """Optional guidance appended to the ``delegate_task`` description (same caching rule
  79. as :meth:`task_parameters`)."""
  80. return ""
  81. @abc.abstractmethod
  82. def route_task(self, task: Mapping[str, Any], config: Mapping[str, Any]) -> dict[str, Any]:
  83. """Return the route for one task (vocabulary in the module docstring).
  84. ``task`` carries ``goal``, ``context``, ``index`` and the values the model supplied for
  85. this provider's :meth:`task_parameters` (absent when omitted). Raise
  86. :class:`DelegationRouteError` to refuse the task.
  87. """