hermes-agent/gateway/platforms/ADDING_A_PLATFORM.md
teknium1 43b8951beb fix(gateway): a platform replay after a reconnect is no longer answered twice
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.
2026-09-23 10:41:08 -07:00

18 KiB

Adding a New Messaging Platform

There are two ways to add a platform to the Hermes gateway:

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

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

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:

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:

_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():

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):

_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:

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:

"hermes-your-platform": {
    "description": "Your Platform bot toolset",
    "tools": _HERMES_CORE_TOOLS,
    "includes": []
},

And add it to the hermes-gateway composite:

"hermes-gateway": {
    "includes": [..., "hermes-your-platform"]
}

8. Cron Delivery (cron/scheduler.py)

Add to platform_map in _deliver_result():

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():

platform_map = {
    ...
    "your_platform": Platform.YOUR_PLATFORM,
}

Add routing in _send_to_platform():

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:

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:

platforms = {
    ...
    "Your Platform": ("YOUR_PLATFORM_TOKEN", "YOUR_PLATFORM_HOME_CHANNEL"),
}

13. Gateway Setup Wizard (hermes_cli/gateway.py)

Add to the _PLATFORMS list:

{
    "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:

# 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