From 0fb01a5cb23b8e228af66eab6ff65b07ff05c03d Mon Sep 17 00:00:00 2001 From: Offending Commit Date: Fri, 13 Nov 2026 10:10:49 -0600 Subject: [PATCH] docs(providers): keep specialized providers as explicit instances Issue 22 asked whether memory, image and video providers should get a declaration decorator like @tool or @platform. They should not. A provider is one stateful instance the plugin builds, often behind a runtime policy the plugin already evaluates for its other surfaces; its only consumer gates it in one line. A decorator would construct the instance itself, assume a no-argument constructor, and add a second activation gate. README and the authoring skill now say so and show the gated tuple. The skill's surface map gains a specialized-provider row, its "does not own" list no longer reads as if the kit had no provider path, AGENTS.md records the decision, and the public-surface guard treats the three provider ABCs as host-owned. Closes: #22 Claude-Session: https://claude.ai/code/session_01B6XeAWUPdrx34tr5dTg5dY --- AGENTS.md | 3 +++ README.md | 17 +++++++++++++++++ skills/hermes-plugins/references/plugin-kit.md | 8 ++++++-- tests/test_testing_harness.py | 4 ++++ 4 files changed, 30 insertions(+), 2 deletions(-) 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", }