mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-11-17 04:11:35 +00:00
The reconnect watcher replaces a failed adapter with a NEW instance, and every adapter keeps its inbound MessageDeduplicator on the instance. The rebuilt adapter started with an empty cache, so a platform re-delivering a recent inbound ID right after the reconnect (websocket resume replay, webhook retry, unacked poll batch) got it processed and answered again. The reconnect queue entry now holds the retired adapter's MessageDeduplicator attributes by reference, and the rebuilt adapter absorbs their live IDs before it connects. The multiplex secondary-profile reconnect path gets the same handover. Any adapter using the shared helper is covered without per-adapter code.
436 lines
18 KiB
Markdown
436 lines
18 KiB
Markdown
# Adding a New Messaging Platform
|
|
|
|
There are two ways to add a platform to the Hermes gateway:
|
|
|
|
## Plugin Path (Recommended for Community/Third-Party)
|
|
|
|
Create a plugin directory in `~/.hermes/plugins/` (or under `plugins/platforms/`
|
|
for bundled plugins) with a `plugin.yaml` and `adapter.py`. The adapter
|
|
inherits from `BasePlatformAdapter` and registers via
|
|
`ctx.register_platform()` in the `register(ctx)` entry point. This requires
|
|
**zero changes to core Hermes code**.
|
|
|
|
The plugin system automatically handles: adapter creation, config parsing,
|
|
user authorization, cron delivery, send_message routing, system prompt hints,
|
|
status display, gateway setup, and more.
|
|
|
|
**Optional hooks cover the edges most adapters need:**
|
|
|
|
- `env_enablement_fn: () -> Optional[dict]` — seeds `PlatformConfig.extra`
|
|
(and an optional `home_channel` dict) from env vars BEFORE the adapter is
|
|
constructed. Without this, env-only setups don't surface in
|
|
`hermes gateway status` or `get_connected_platforms()` until the SDK
|
|
instantiates. Build it from a `(ENV_VAR, extra_key, conv)` table with
|
|
`gateway.platforms._shared.seed_extra_from_env(spec, home_env=...)`; every
|
|
read goes through `_shared.get_scoped_secret` (multiplex-safe, never
|
|
`os.getenv`).
|
|
- `apply_yaml_config_fn: (yaml_cfg, platform_cfg) -> Optional[dict]` —
|
|
translate this platform's `config.yaml` keys into env vars and seed
|
|
`PlatformConfig.extra`. Lets a plugin own its YAML schema instead of
|
|
growing core `gateway/config.py` boilerplate per platform. Declare a
|
|
`(yaml_key, ENV_VAR, kind)` table and return
|
|
`_shared.apply_yaml_bridge(platform_cfg, TABLE)`: it writes env only when
|
|
unset (env > YAML), never under a multiplexed secondary profile's scope,
|
|
and returns the same values for `extra` (read `extra` first in the adapter
|
|
via `_shared.extra_or_secret`). Called during `load_gateway_config()`
|
|
after the generic shared-key loop and before `_apply_env_overrides()`.
|
|
- `is_connected: (config) -> bool` — for env-only platforms use
|
|
`_shared.env_is_connected("YOUR_TOKEN_VAR", ...)` instead of a hand-rolled
|
|
`get_env_value` check.
|
|
- `cron_deliver_env_var: str` — name of the `*_HOME_CHANNEL` env var. When
|
|
set, `deliver=<name>` cron jobs route to this var without editing
|
|
`cron/scheduler.py`'s hardcoded sets.
|
|
- `standalone_sender_fn: async (...) -> dict`: out-of-process delivery
|
|
for cron jobs that run separately from the gateway. Without this, a
|
|
`deliver=<name>` job fires correctly but the actual send returns
|
|
`No live adapter for platform '<name>'`. Pair with `cron_deliver_env_var`
|
|
for end-to-end cron support. See the docsite for the signature.
|
|
- `plugin.yaml` `requires_env` / `optional_env` rich-dict entries —
|
|
auto-populate `OPTIONAL_ENV_VARS` in `hermes_cli/config.py` so the setup
|
|
wizard surfaces proper descriptions, prompts, password flags, and URLs.
|
|
|
|
**Subclassing for platform-specific UX.** When a platform has a hard
|
|
time-window constraint that the base adapter can't anticipate (LINE's
|
|
60s single-use reply token, WhatsApp's 24h session window, etc.), an
|
|
adapter can override `_keep_typing` to layer a mid-flight bubble at a
|
|
threshold without expanding the kwarg surface. Always
|
|
`await super()._keep_typing(...)` so the typing heartbeat keeps running,
|
|
and tear down your side task in `finally`. See `plugins/platforms/line/`
|
|
for the full pattern (Template Buttons postback at 45s, `RequestCache`
|
|
state machine, `interrupt_session_activity` override for `/stop`
|
|
orphans) and the developer-guide page for the prose walkthrough.
|
|
|
|
**Sibling adapters that share behavior.** When a single platform has
|
|
two transport modes the user picks between — unofficial vs official
|
|
APIs, polling vs websocket, library A vs library B — the right
|
|
structure is two adapters that share a behavior mixin. WhatsApp does
|
|
this: `gateway/platforms/whatsapp.py` (Baileys bridge) and
|
|
`gateway/platforms/whatsapp_cloud.py` (Meta Cloud API) both inherit
|
|
from `WhatsAppBehaviorMixin` in `gateway/platforms/whatsapp_common.py`.
|
|
The mixin owns gating, allow-lists, mention parsing, broadcast
|
|
filters, and the WhatsApp-flavored markdown conversion — everything
|
|
that's platform-protocol-agnostic. Each adapter owns its transport.
|
|
Both register distinct `Platform.*` enum values so the gateway can run
|
|
both simultaneously against different phone numbers. The mixin must
|
|
come **first** in the bases list — `class WhatsAppAdapter(Mixin,
|
|
BasePlatformAdapter)` — so the mixin's `format_message` overrides
|
|
`BasePlatformAdapter`'s generic default.
|
|
|
|
See `plugins/platforms/irc/`, `plugins/platforms/teams/`, and
|
|
`plugins/platforms/google_chat/` for complete working examples, and
|
|
`website/docs/developer-guide/adding-platform-adapters.md` for the full
|
|
plugin guide with code examples and hook documentation.
|
|
|
|
---
|
|
|
|
Plugin-registered native handlers (`ctx.register_platform_handler(<platform>, factory)`): call
|
|
`self._wire_plugin_handlers(native_client)` once in `connect()` before your own catch-all handlers. The base
|
|
class then handles plugins that load mid-run — the runner calls `rewire_plugin_handlers()` on every
|
|
plugin-loaded event and only factories not yet wired on that native client run. Override it only when your
|
|
adapter keeps a second plugin registry (Slack action handlers) or dispatches by registration order with a
|
|
catch-all last (Telegram hoists late handlers ahead of core); see `gateway/run_plugin_rewire.py`.
|
|
|
|
## Built-in Path (Core Contributors Only)
|
|
|
|
Checklist for integrating a platform directly into the Hermes core.
|
|
Use this as a reference when building a built-in adapter — every item here
|
|
is a real integration point. Missing any of them will cause broken
|
|
functionality, missing features, or inconsistent behavior.
|
|
|
|
---
|
|
|
|
## 1. Core Adapter (`gateway/platforms/<platform>.py`)
|
|
|
|
The adapter is a subclass of `BasePlatformAdapter` from `gateway/platforms/base.py`.
|
|
|
|
### Required methods
|
|
|
|
| Method | Purpose |
|
|
|--------|---------|
|
|
| `__init__(self, config)` | Parse config, init state. Call `super().__init__(config, Platform.YOUR_PLATFORM)` |
|
|
| `connect() -> bool` | Connect to the platform, start listeners. Return True on success |
|
|
| `disconnect()` | Stop listeners, close connections, cancel tasks |
|
|
| `send(chat_id, text, ...) -> SendResult` | Send a text message |
|
|
| `send_typing(chat_id)` | Send typing indicator |
|
|
| `send_image(chat_id, image_url, caption) -> SendResult` | Send an image |
|
|
| `get_chat_info(chat_id) -> dict` | Return `{name, type, chat_id}` for a chat |
|
|
|
|
### Optional methods (have default stubs in base)
|
|
|
|
| Method | Purpose |
|
|
|--------|---------|
|
|
| `send_document(chat_id, path, caption)` | Send a file attachment |
|
|
| `send_voice(chat_id, path)` | Send a voice message |
|
|
| `send_video(chat_id, path, caption)` | Send a video |
|
|
| `send_animation(chat_id, path, caption)` | Send a GIF/animation |
|
|
| `send_image_file(chat_id, path, caption)` | Send image from local file |
|
|
|
|
### Interactive UX (recommended if your platform supports tappable buttons)
|
|
|
|
If your platform supports interactive button/menu messages, implement these for a more polished agent experience. They all degrade gracefully to plain text when not overridden:
|
|
|
|
| Method | Purpose |
|
|
|--------|---------|
|
|
| `send_clarify(chat_id, question, choices, clarify_id, session_key, ...)` | Render the `clarify` tool's multi-choice question as tappable buttons. Pair with inbound dispatch that routes button taps to `tools.clarify_gateway.resolve_gateway_clarify`. |
|
|
| `_send_exec_approval_prompt(prompt: ExecApprovalPrompt)` | Render a dangerous-command approval as native buttons. `send_exec_approval` is a base template method: it builds the shared text (`_format_exec_approval`, tune via the `_EA_*` class attrs) and the choice set (`prompt.actions` = `(label, choice, style)` rows, choices `once`/`session`/`always`/`deny`) — you only map those rows to widgets. Inbound dispatch routes to `tools.approval.resolve_gateway_approval`. |
|
|
| `send_slash_confirm(chat_id, title, message, session_key, confirm_id, ...)` | Render slash-command confirmations (e.g. `/reload-mcp`) as Once/Always/Cancel buttons. Inbound dispatch routes to `tools.slash_confirm.resolve`. |
|
|
| `send_model_picker(...)` | Interactive `/model` picker. Used by Telegram, Discord, and Slack (Socket Mode). |
|
|
| `send_choice_picker(...)` | Flat single-level picker for finite-choice commands (`/reasoning`, `/fast`). Implemented by Telegram (inline keyboard), Discord (select menu), and Matrix (reactions). Platforms without it fall back to the text status card automatically. |
|
|
|
|
See `gateway/platforms/telegram.py`, `discord.py`, and `whatsapp_cloud.py` for reference implementations. The button-callback id convention (`cl:<id>:<idx>`, `appr:<id>:<choice>`, `sc:<choice>:<id>`) is shared across adapters — match it so the gateway-side resolvers work without modification.
|
|
|
|
### Required function
|
|
|
|
```python
|
|
def check_<platform>_requirements() -> bool:
|
|
"""Check if this platform's dependencies are available."""
|
|
```
|
|
|
|
### Key patterns to follow
|
|
|
|
- Use `self.build_source(...)` to construct `SessionSource` objects (never `SessionSource(...)`
|
|
directly — the transport provenance and profile route are stamped there)
|
|
- Derive every adapter-side session key (batching, per-chat queues, busy detection) through
|
|
`self._event_session_key(event)` / `self._source_session_key(source)`, never the free
|
|
`build_session_key()` — the seam keys in the owning profile's namespace under a multiplexed
|
|
gateway; the advisory lint (`scripts/check_profile_scope_patterns.py`, pattern P32) flags both
|
|
- Call `self.handle_message(event)` to dispatch inbound messages to the gateway
|
|
- Use `MessageEvent`, `MessageType` from `gateway.platforms.event` and `SendResult` from base
|
|
- Use `cache_image_from_bytes`, `cache_audio_from_bytes`, `cache_document_from_bytes` for attachments
|
|
- Filter self-messages (prevent reply loops)
|
|
- Drop redelivered inbound IDs with `MessageDeduplicator` (`gateway/platforms/helpers.py`) held as an adapter
|
|
attribute; the runner's reconnect copies its live IDs into the rebuilt adapter, a hand-rolled cache starts empty
|
|
- Filter sync/echo messages if the platform has them
|
|
- Redact sensitive identifiers (phone numbers, tokens) in all log output
|
|
- Implement reconnection with exponential backoff + jitter for streaming connections
|
|
- Set `MAX_MESSAGE_LENGTH` if the platform has message size limits
|
|
|
|
---
|
|
|
|
## 2. Platform Enum (`gateway/config.py`)
|
|
|
|
Add the platform to the `Platform` enum:
|
|
|
|
```python
|
|
class Platform(Enum):
|
|
...
|
|
YOUR_PLATFORM = "your_platform"
|
|
```
|
|
|
|
Add a row to `_ENV_STEPS` in `gateway/config_env.py` (source order = application order);
|
|
`_Cred` enables the platform when the named env vars resolve and copies them into `extra`:
|
|
|
|
```python
|
|
_Cred(Platform.YOUR_PLATFORM, ("YOUR_PLATFORM_TOKEN",), token="YOUR_PLATFORM_TOKEN"),
|
|
_Home(Platform.YOUR_PLATFORM, "YOUR_PLATFORM_HOME_CHANNEL"),
|
|
```
|
|
|
|
Every read goes through `gateway/config.py::_getenv` (the active profile's secret scope when one
|
|
is bound, `os.environ` otherwise). **Never `os.getenv` here and never write `os.environ`**: under
|
|
`gateway.multiplex_profiles` the process env is the DEFAULT profile's, so a raw read enables your
|
|
platform for the wrong profile with the wrong credentials, and a write pins one profile's policy
|
|
process-wide (first profile wins). Adapter-side reads use `gateway.platforms._shared.get_scoped_secret`
|
|
/ `extra_or_secret`.
|
|
|
|
Update `get_connected_platforms()` if your platform doesn't use token/api_key
|
|
(e.g., WhatsApp uses `enabled` flag, Signal uses `extra` dict).
|
|
|
|
---
|
|
|
|
## 3. Adapter Factory (`gateway/run.py`)
|
|
|
|
Add to `_instantiate_adapter()`:
|
|
|
|
```python
|
|
elif platform == Platform.YOUR_PLATFORM:
|
|
from gateway.platforms.your_platform import YourAdapter, check_your_requirements
|
|
if not check_your_requirements():
|
|
logger.warning("Your Platform: dependencies not met")
|
|
return None
|
|
return YourAdapter(config)
|
|
```
|
|
|
|
`_create_adapter()` wraps this factory and binds every successful adapter to
|
|
its `GatewayRunner`. Do not construct platform adapters in lifecycle call sites;
|
|
startup and reconnect must keep using the wrapper so profile routing is wired
|
|
before `connect()`.
|
|
|
|
---
|
|
|
|
## 4. Authorization Maps (`gateway/pairing.py`, `gateway/authz_mixin.py`)
|
|
|
|
Add the allowlist var to `_PLATFORM_ALLOWLIST_ENV` in `gateway/pairing.py`;
|
|
`authz_mixin.py` derives `_ALLOWED_USERS_ENV` / `_ALLOW_ALL_ENV` from it (the `*_ALLOW_ALL_USERS`
|
|
name is computed, not hand-listed):
|
|
|
|
```python
|
|
_PLATFORM_ALLOWLIST_ENV = {
|
|
...
|
|
"your_platform": "YOUR_PLATFORM_ALLOWED_USERS",
|
|
}
|
|
```
|
|
|
|
Plugin adapters declare `allowed_users_env` / `allow_all_env` on `ctx.register_platform` instead.
|
|
`_is_user_authorized()` reads every gate through `_shared.platform_gate_env` (`_auth_env`), which
|
|
answers from the routed profile's secret scope under multiplex — never add an `os.getenv` here.
|
|
|
|
---
|
|
|
|
## 5. Session Source (`gateway/session.py`)
|
|
|
|
If your platform needs extra identity fields (e.g., Signal's UUID alongside
|
|
phone number), add them to the `SessionSource` dataclass with `Optional` defaults,
|
|
and update `to_dict()`, `from_dict()`, and `build_source()` in base.py.
|
|
|
|
---
|
|
|
|
## 6. System Prompt Hints (`agent/prompt_builder.py`)
|
|
|
|
Add a `PLATFORM_HINTS` entry so the agent knows what platform it's on:
|
|
|
|
```python
|
|
PLATFORM_HINTS = {
|
|
...
|
|
"your_platform": (
|
|
"You are on Your Platform. "
|
|
"Describe formatting capabilities, media support, etc."
|
|
),
|
|
}
|
|
```
|
|
|
|
Without this, the agent won't know it's on your platform and may use
|
|
inappropriate formatting (e.g., markdown on platforms that don't render it).
|
|
|
|
---
|
|
|
|
## 7. Toolset (`toolsets.py`)
|
|
|
|
Add a named toolset for your platform:
|
|
|
|
```python
|
|
"hermes-your-platform": {
|
|
"description": "Your Platform bot toolset",
|
|
"tools": _HERMES_CORE_TOOLS,
|
|
"includes": []
|
|
},
|
|
```
|
|
|
|
And add it to the `hermes-gateway` composite:
|
|
|
|
```python
|
|
"hermes-gateway": {
|
|
"includes": [..., "hermes-your-platform"]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 8. Cron Delivery (`cron/scheduler.py`)
|
|
|
|
Add to `platform_map` in `_deliver_result()`:
|
|
|
|
```python
|
|
platform_map = {
|
|
...
|
|
"your_platform": Platform.YOUR_PLATFORM,
|
|
}
|
|
```
|
|
|
|
Without this, `cronjob(action="create", deliver="your_platform", ...)` silently fails.
|
|
|
|
---
|
|
|
|
## 9. Send Message Tool (`tools/send_message_tool.py`)
|
|
|
|
Add to `platform_map` in `send_message_tool()`:
|
|
|
|
```python
|
|
platform_map = {
|
|
...
|
|
"your_platform": Platform.YOUR_PLATFORM,
|
|
}
|
|
```
|
|
|
|
Add routing in `_send_to_platform()`:
|
|
|
|
```python
|
|
elif platform == Platform.YOUR_PLATFORM:
|
|
return await _send_your_platform(pconfig, chat_id, message)
|
|
```
|
|
|
|
Implement `_send_your_platform()` — a standalone async function that sends
|
|
a single message without requiring the full adapter (for use by cron jobs
|
|
and the send_message tool outside the gateway process).
|
|
|
|
Update the tool schema `target` description to include your platform example.
|
|
|
|
---
|
|
|
|
## 10. Cronjob Tool Schema (`tools/cronjob_tools.py`)
|
|
|
|
Update the `deliver` parameter description and docstring to mention your
|
|
platform as a delivery option.
|
|
|
|
---
|
|
|
|
## 11. Channel Directory (`gateway/channel_directory.py`)
|
|
|
|
If your platform can't enumerate chats (most can't), add it to the
|
|
session-based discovery list:
|
|
|
|
```python
|
|
for plat_name in ("telegram", "whatsapp", "signal", "your_platform"):
|
|
```
|
|
|
|
---
|
|
|
|
## 12. Status Display (`hermes_cli/status.py`)
|
|
|
|
Add to the `platforms` dict in the Messaging Platforms section:
|
|
|
|
```python
|
|
platforms = {
|
|
...
|
|
"Your Platform": ("YOUR_PLATFORM_TOKEN", "YOUR_PLATFORM_HOME_CHANNEL"),
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 13. Gateway Setup Wizard (`hermes_cli/gateway.py`)
|
|
|
|
Add to the `_PLATFORMS` list:
|
|
|
|
```python
|
|
{
|
|
"key": "your_platform",
|
|
"label": "Your Platform",
|
|
"emoji": "📱",
|
|
"token_var": "YOUR_PLATFORM_TOKEN",
|
|
"setup_instructions": [...],
|
|
"vars": [...],
|
|
}
|
|
```
|
|
|
|
If your platform needs custom setup logic (connectivity testing, QR codes,
|
|
policy choices), add a `_setup_your_platform()` function and route to it
|
|
in the platform selection switch.
|
|
|
|
Update `_platform_status()` if your platform's "configured" check differs
|
|
from the standard `bool(get_env_value(token_var))`.
|
|
|
|
---
|
|
|
|
## 14. Phone/ID Redaction (`agent/redact.py`)
|
|
|
|
If your platform uses sensitive identifiers (phone numbers, etc.), add a
|
|
regex pattern and redaction function to `agent/redact.py`. This ensures
|
|
identifiers are masked in ALL log output, not just your adapter's logs.
|
|
|
|
---
|
|
|
|
## 15. Documentation
|
|
|
|
| File | What to update |
|
|
|------|---------------|
|
|
| `README.md` | Platform list in feature table + documentation table |
|
|
| `AGENTS.md` | Gateway description + env var config section |
|
|
| `website/docs/user-guide/messaging/<platform>.md` | **NEW** — Full setup guide (see existing platform docs for template) |
|
|
| `website/docs/user-guide/messaging/index.md` | Architecture diagram, toolset table, security examples, Next Steps links |
|
|
| `website/docs/reference/environment-variables.md` | All env vars for the platform |
|
|
|
|
---
|
|
|
|
## 16. Tests (`tests/gateway/test_<platform>.py`)
|
|
|
|
Recommended test coverage:
|
|
|
|
- Platform enum exists with correct value
|
|
- Config loading from env vars via `_apply_env_overrides`
|
|
- Adapter init (config parsing, allowlist handling, default values)
|
|
- Helper functions (redaction, parsing, file type detection)
|
|
- Session source round-trip (to_dict → from_dict)
|
|
- Authorization integration (platform in allowlist maps)
|
|
- Send message tool routing (platform in platform_map)
|
|
|
|
Optional but valuable:
|
|
- Async tests for message handling flow (mock the platform API)
|
|
- SSE/WebSocket reconnection logic
|
|
- Attachment processing
|
|
- Group message filtering
|
|
|
|
---
|
|
|
|
## Quick Verification
|
|
|
|
After implementing everything, verify with:
|
|
|
|
```bash
|
|
# All tests pass
|
|
python -m pytest tests/ -q
|
|
|
|
# Grep for your platform name to find any missed integration points
|
|
grep -r "telegram\|discord\|whatsapp\|slack" gateway/ tools/ agent/ cron/ hermes_cli/ toolsets.py \
|
|
--include="*.py" -l | sort -u
|
|
# Check each file in the output — if it mentions other platforms but not yours, you missed it
|
|
```
|