Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
17 changes: 17 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
8 changes: 6 additions & 2 deletions skills/hermes-plugins/references/plugin-kit.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/<path>` 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.<name>.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. |
Expand Down Expand Up @@ -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.
Expand Down
4 changes: 4 additions & 0 deletions tests/test_testing_harness.py
Original file line number Diff line number Diff line change
Expand Up @@ -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",
}
Expand Down
Loading