diff --git a/AGENTS.md b/AGENTS.md index b376ba7..64c1f0c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -67,6 +67,9 @@ plugin. - Keep stateful Hermes provider ABCs as provider instances: register memory, image-generation, and video-generation providers through their specialized contexts instead of decorating provider methods as general plugin surfaces. + Do not add a provider declaration decorator: the explicit + `memory_providers=` / `image_gen_providers=` / `video_gen_providers=` tuples + are the contract (decided on offendingcommit/hermes-plugin-kit#22). - Register at most one real Hermes `ContextEngine` through `register_plugin`. Finish every registrar, identity, type, declaration, and provider preflight before submitting it or mutating another host registry. Keep engine schemas diff --git a/README.md b/README.md index c0545dc..2214b72 100644 --- a/README.md +++ b/README.md @@ -709,6 +709,23 @@ Image and video providers run through the general `PluginContext`. The kit does not decorate provider methods or replace the `MemoryProvider`, `ImageGenProvider`, or `VideoGenProvider` contracts. +Providers have no declaration decorator, by design. `@tool`, `@hook` and +`@platform` declare something the host calls or constructs; a provider is one +stateful instance the plugin builds, often only when a runtime policy allows +it. Make that choice in `register()`, where the policy is already evaluated for +the plugin's other surfaces: + +```python +providers = () if policy.read_only else (MyMemoryProvider(),) +return register_plugin(ctx, declarations, memory_providers=providers) +``` + +A decorator would have to construct the instance itself, assuming a +no-argument constructor, and would add a second activation gate beside the one +the plugin already runs. The tuple keeps construction explicit and one instance +per registration, and gets the same name validation and `RegistrationSummary` +fields. + Context engines likewise remain instances of Hermes' `ContextEngine` ABC, but are singular rather than a provider collection. Their native schemas and `handle_tool_call` own recovery-tool dispatch. diff --git a/skills/hermes-plugins/references/plugin-kit.md b/skills/hermes-plugins/references/plugin-kit.md index a635a96..814d71d 100644 --- a/skills/hermes-plugins/references/plugin-kit.md +++ b/skills/hermes-plugins/references/plugin-kit.md @@ -39,6 +39,7 @@ guidance, not a second implementation specification. | Plugin-owned skill | `plugin_skill` | `register_plugin(..., skills=...)` | Hermes adds the plugin namespace; missing required skills fail, optional skills warn and skip. Optional `references_dir` (a companion reference-files directory) drives kit-side validation and `plugin_reference_tool`; the host serves companion files by convention instead, from `references`/`templates`/`assets`/`scripts` beside `SKILL.md`, so name the directory accordingly. See [`README.md`](../../../README.md#commands-middleware-hooks-and-plugin-skills). | | Agent-visible skill reference files (today) | `plugin_reference_tool` | `register_plugin` (its return value is an ordinary `@tool` function — add it to the plugin's declarations) | Sidesteps `register_skill` entirely by exposing `references_dir` as a normal tool call; accepts both paths listed by the tool and skill-relative `references/` forms, while rejecting any path that resolves outside `references_dir` (symlink, absolute path, or `../`) and any non-string `file_path`. `references_dir` itself must be inside the skill's own directory — enforced by `plugin_skill` and re-checked here. | | Context engine | Hermes `ContextEngine` instance | `register_plugin(..., context_engine=...)` | Singular native engine registration; schemas and recovery dispatch stay in `get_tool_schemas()` / `handle_tool_call()`, never duplicated with `@tool`. | +| Specialized provider | Hermes `MemoryProvider`, `ImageGenProvider` or `VideoGenProvider` instance | `register_plugin(..., memory_providers=..., image_gen_providers=..., video_gen_providers=...)` | Pass constructed instances; there is deliberately no provider decorator. Gate construction in `register()` (`() if disabled else (Provider(),)`). Memory providers register through Hermes' memory-provider discovery context. | | Gateway platform | `@platform` on a `BasePlatformAdapter` subclass | `register_plugin` | The class is the adapter factory. Options are checked against the host's `PlatformEntry` before anything registers; `optional_options` may be dropped on an older host. Replacing a platform that exists fails unless the operator lists it in `plugins..replace_platforms`. A host refusal rolls back this call's platforms. | | Host-managed call | `invoke_host_tool` | None | Use for supported non-registry capabilities such as `send_message`; pre/post-tool hooks remain active. | | Local media delivery | `MediaPayload`, `MediaType`, `deliver_media` | Consumer registers suppression hooks | File must be absolute, present, and non-empty; `origin` resolves from task-local Hermes context. | @@ -71,8 +72,11 @@ Use the direct Hermes API or the specialized upstream plugin interface for: `ctx.llm.complete*`. - Gateway platform adapter behavior (connect, send, media); the kit registers adapters but `BasePlatformAdapter` and Hermes' helpers own what they do. -- Memory, model, image, video, browser, web-search, secret source, desktop, or - dashboard provider interfaces. The one supported context-engine seam is the +- Provider behavior and every provider interface beyond registration: memory, + model, image, video, browser, web-search, secret source, desktop, or + dashboard. The kit forwards memory, image and video provider instances + through `register_plugin`; it never decorates or wraps their methods. The one + supported context-engine seam is the singular typed `register_plugin` adapter; the kit does not abstract engine policy, schemas, or tool dispatch. - Plugin discovery, enablement, platform toolset selection, or core agent-loop behavior. diff --git a/tests/test_testing_harness.py b/tests/test_testing_harness.py index b6f12e3..d4e1bab 100644 --- a/tests/test_testing_harness.py +++ b/tests/test_testing_harness.py @@ -587,6 +587,10 @@ def test_conforming_schema_passes(self) -> None: HOST_OWNED_NAMES = { # Hermes' own class; the kit takes an instance, it does not provide one. "ContextEngine", + # Hermes' provider ABCs; the kit forwards instances, it provides none. + "MemoryProvider", + "ImageGenProvider", + "VideoGenProvider", # Hermes' adapter base; a @platform class subclasses it. "BasePlatformAdapter", }