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
9 changes: 9 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,15 @@ plugin.
before submitting it or mutating another host registry. Keep engine schemas
and recovery dispatch on `get_tool_schemas` / `handle_tool_call`; do not
duplicate native engine tools through `@tool`.
- Register gateway platforms with `@platform` on a `BasePlatformAdapter`
subclass through `register_plugin`. Check options against the host's own
`PlatformEntry`, never a kit-owned field list; read platform existence with
`core_ships_platform` and `snapshot_registration` under the plugin manager's
scope (the one Hermes writes to) plus the global scope, never
`PlatformRegistry.get`, which imports deferred SDKs. Access-policy options
are never optional. Replacing an existing
platform stays operator-gated through `plugins.<name>.replace_platforms`, and
a host refusal must dispose this call's earlier platform handles.
- Redact secret-looking values in logs and avoid logging full untrusted payloads.
- Get Python and `uv` from `mise.toml` and `mise.lock`
(`mise trust && mise install --locked`), the same toolchain CI installs;
Expand Down
63 changes: 63 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -450,6 +450,8 @@ visible in container logs without forcing verbose plugin logging everywhere.
`log_registration_summary(logger, plugin_name, summary)` helper. The receipt
uses the Hermes manifest name when available and lists the actual registered
command, tool, middleware, hook, and skill names, plus skipped optional skills.
Platform fields (`platforms`, `replaced_platforms`) come last, after every
older field, so position-based parsers keep reading the fields they knew.
Runtime-gated consumers should pass their active decorated declarations to
`register_plugin`; a truly custom registration path can call the same helper
with its own `RegistrationSummary` instead of inventing a second receipt
Expand Down Expand Up @@ -760,6 +762,67 @@ and `send_voice` with the expected files, without separate text messages. It
also runs the kit-owned spoiler extension against Hermes' real config, session,
async bridge, and Telegram library shapes while mocking only Bot network calls.

## Gateway platforms

A plugin that adds a messaging channel annotates its adapter class with
`@platform` and passes it to `register_plugin` like any other declaration. The
class must subclass Hermes' `BasePlatformAdapter`; it is registered as-is and
becomes the `adapter_factory` Hermes calls with the platform config. Follow
Hermes' own adapter guide (`website/docs/developer-guide/adding-platform-adapters.md`)
for the adapter itself.

```python
from gateway.platforms.base import BasePlatformAdapter
from hermes_plugin_kit import platform, register_plugin


def web_chat_ready() -> bool: # passive: report whether dependencies import
return True


@platform(
"web_chat",
label="Web Chat",
check=web_chat_ready,
required_env=["WEB_CHAT_TOKEN"],
options={"emoji": "💬", "display_tier": "minimal"},
optional_options={"display_tier"},
)
class WebChatAdapter(BasePlatformAdapter):
...


def register(ctx):
return register_plugin(ctx, [WebChatAdapter])
```

`options` passes further `PlatformEntry` fields through unchanged, and
`register_plugin` checks every name against the running host's own
`PlatformEntry` before anything registers. An unknown option fails registration;
one listed in `optional_options` is dropped on a host that lacks it and logged
by name. Access-policy options (`trusted_inbound`, `allowed_users_env`,
`allow_all_env`, `allow_bots_env`, `own_policy_env`, `group_allowed_chats_env`,
`allowlist_suppresses_pairing`) cannot be optional: losing one would change who
can reach the agent. `source` and `plugin_name` belong to the host and are refused.
`trusted_inbound` is never set unless you pass it, and is refused on any
platform Hermes ships.

Replacing a platform that already exists, one Hermes ships or one already
registered, fails loudly. Only the operator can allow it, by naming the
platform in the plugin's config:

```yaml
plugins:
my-plugin:
replace_platforms: [telegram]
```

A reload of the plugin's own platform needs no entry, except for a platform
Hermes ships. If Hermes refuses a registration (`register_platform` returns
`None`), `register_plugin` disposes the platforms it already registered in that
call and raises, so a refused plugin leaves no platform behind. The receipt
names `platforms` and `replaced_platforms`.

## Agent skill

The repo owns a Hermes plugin authoring skill at
Expand Down
356 changes: 356 additions & 0 deletions docs/plans/2026-11-13-0900-feat-platform-annotation-plan.md

Large diffs are not rendered by default.

Loading
Loading