How Channels Are Handled

A guided tour of the platform/adapter system in hermes-agent. Start here; we'll dive into specific layers in follow-up notes.

TL;DR

Mental model

Three words you'll see everywhere:

The three layers

1. Channel (data)

Channels are not classes — they're just rows in a cached JSON directory at ~/.hermes/channel_directory.json. The gateway rebuilds this map every 5 minutes from two sources:

• Live API enumeration — for platforms that list channels (Discord, Slack).
• Session history — for everyone else: scan past sessions and harvest (chat_id, chat_name).

The agent's send_message tool and the MCP bridge read this file to resolve human-friendly names ("#general") into platform IDs.

Build/refresh: gateway/channel_directory.py:60

2. Adapter (behavior)

Each platform has a concrete adapter — a subclass of the abstract BasePlatformAdapter (gateway/platforms/base.py:1259). Every adapter implements the same async interface:

class BasePlatformAdapter(ABC):
    async def connect(self) -> bool: ...
    async def disconnect(self) -> None: ...
    async def send(self, chat_id, text, ...) -> SendResult: ...
    async def send_typing(self, chat_id) -> None: ...
    async def send_image(self, chat_id, image_url, caption) -> SendResult: ...
    async def get_chat_info(self, chat_id) -> dict: ...
    async def handle_message(self, event: MessageEvent) -> None: ...

The base class is ~3600 lines because it also handles cross-cutting concerns: typing heartbeats, chunking long messages, per-session interrupt events, draft streaming, auto-TTS, approval flows, media uploads, post-delivery callbacks. Subclasses override only what's platform-specific.

3. Gateway runner (control plane)

GatewayRunner in gateway/run.py is the orchestrator. It:

• Reads config.yaml, decides which platforms to enable.
• Calls _create_adapter(platform, config) for each — checks the plugin registry first, falls back to a built-in if/elif chain.
• Starts every adapter's connect() in parallel.
• Routes incoming MessageEvents to the agent and outgoing replies to adapter.send().
• Refreshes the channel directory every 5 min.

Design patterns in play

End-to-end flow (incoming message)

Channel inventory

Built-in adapters live in gateway/platforms/; plugin adapters live in plugins/platforms/ or ~/.hermes/plugins/.

Are channels shared? (Telegram → WhatsApp?)

Session isolation is structural

Session keys structurally embed the platform name:

agent:main:{platform}:{chat_type}:{chat_id}[:{thread_id}][:{user_id}]

Built by build_session_key() — gateway/session.py:594

Different keys → different session rows in sessions.json → different SQLite session_ids → different transcripts. There is no user field that spans platforms; Telegram-user-X and WhatsApp-user-Y are simply unrelated identifiers as far as the gateway is concerned.

What IS shared across platforms

Three globals, but only one of them carries conversational continuity:

1. The agent's long-term memory. ~/.hermes/memories/MEMORY.md + USER.md are profile-global — loaded once per agent start, injected into the system prompt. So if the agent learned "the user prefers concise replies" on Telegram, that fact also applies on WhatsApp. But the conversation history doesn't.

   tools/memory_tool.py:55-57, tools/memory_tool.py:127-142

   caveat Memory is profile-global, not user-global. Two different humans using the same Hermes instance share the same MEMORY.md / USER.md.
2. The channel directory. ~/.hermes/channel_directory.json is shared — the agent in any session can route a send_message to any reachable channel on any platform.
3. The agent persona & tools. Same system prompt, same toolset, same models everywhere.

The one explicit cross-platform feature: /handoff

There is a real handoff mechanism, but it's narrower than it first looks:

• It's a CLI → platform transfer. Not platform → platform.
• In the Hermes CLI you run /handoff telegram (or whatsapp, etc.). The CLI writes handoff_state='pending' on the session row. cli.py:5689
• A watcher in the gateway picks it up, atomically claims it, and re-binds the destination platform's session_key to the CLI's session_id via session_store.switch_session. The full transcript replays on the destination on the next agent turn. gateway/run.py:3721, gateway/session.py:1176
• Optionally, the adapter creates a fresh thread (Telegram topic, Discord thread, Slack thread) on the destination's home channel so the handoff has its own scrollback. gateway/run.py:3784
• The CLI process polls the row until completed or failed, then prints the result and exits.

There is no user-driven Telegram → WhatsApp handoff. The CLI is the only legal source.

Cross-platform send_message ≠ continuity

From any session, the agent can call send_message(target="whatsapp:+...", message="...") to reach any channel on any other platform. But this starts a new isolated conversation on the destination — the recipient sees a single message, not the source-platform backstory. tools/send_message_tool.py

Adapter lifecycle

Every concrete adapter is a state machine governed by BasePlatformAdapter. The lifecycle has five stages — construct, wire, connect, dispatch loop, disconnect — but the interesting behavior is concentrated in the dispatch loop because it has to coordinate concurrent in-flight agent runs, interrupts, command bypasses, late-arriving messages, and stale guards.

Lifecycle states

connect()

Abstract method (gateway/platforms/base.py:1532); every adapter implements it. The shape is consistent across platforms:

1. Validate prerequisites. SDK installed? Token present? Bail with a clear log on missing deps.
2. Acquire a platform lock. _acquire_platform_lock(scope, identity, desc) prevents two Hermes instances from racing on the same bot token / IMAP inbox.
3. Build the platform client. e.g. Application.builder().token(...) for Telegram, discord.Client(...) for Discord, IMAP/SMTP sessions for Email.
4. Register platform-native handlers that ultimately invoke await self.handle_message(event) with a normalized MessageEvent. For Telegram this is PTB MessageHandler registrations (gateway/platforms/telegram.py:1217); each handler builds an event via _build_message_event and either buffers (text bursts) or dispatches.
5. Start the listener. Long polling, websocket, webhook server, IMAP IDLE, whatever the platform supports. Many adapters support multiple modes via env vars (e.g. TELEGRAM_WEBHOOK_URL).
6. Return True on success. _mark_connected() updates runtime status; the gateway adds the adapter to self.adapters.

Dispatch — handle_message(event)

Defined at gateway/platforms/base.py:2749.

This method returns quickly. It never runs the agent inline; it just classifies the incoming event and either spawns a background task, queues it, or routes it through a dedicated bypass path.

_process_message_background

Defined at gateway/platforms/base.py:2892. This is the worker task that actually runs the agent loop and sends the reply.

Concurrency state

Five fields on the adapter coordinate everything:

Edge cases worth knowing

• Photo bursts. Telegram clients split albums into multiple updates. Photos arriving during an active run are merged into _pending_messages via merge_pending_message_event instead of interrupting — otherwise the agent would restart mid-album.
• Stale guards. If a task crashed without unwinding, the guard would be permanent ("I'm always busy"). On every handle_message, _heal_stale_session_lock checks whether the owner task is actually done; if so, the lock is cleared and dispatch falls through normally.
• Two distinct drain paths. "In-band drain" runs while the current task is still inside its try block; "late-arrival drain" runs in the finally for messages that snuck in during the cleanup awaits. Both spawn a fresh task — recursion was banned after issue #17758 (sustained follow-ups blew the C stack at ~2000 frames).
• Generation-aware post-delivery callbacks. GatewayRunner tags each agent run with a generation number on the interrupt event. pop_post_delivery_callback(key, generation=...) refuses to fire if a fresher run has already registered new callbacks — prevents a stale run from clearing the newer run's deferred work.
• Pre-send order in command bypass. _dispatch_active_session_command sends the response before cancelling the old task (issue #18912). Reversed order risked the "/new" confirmation losing to a cancellation race.
• Suppressed stale response. If an interrupt fired during a long agent run and a pending message is queued, the (now-stale) response from the original run is dropped silently — the pending message gets a fresh run instead. Otherwise the user would see the answer to the question they already abandoned.

Where to read first

1. gateway/platforms/ADDING_A_PLATFORM.md — the canonical "what does a platform need to do?" checklist.
2. gateway/config.py:82 — the Platform enum and how plugin platforms slip in via _missing_.
3. gateway/platform_registry.py:38 — PlatformEntry dataclass: the contract between core and plugins.
4. gateway/platforms/base.py:1259 — BasePlatformAdapter: the interface every adapter implements.
5. gateway/channel_directory.py:60 — how channels are discovered and cached.

What we'll dive into next

Open questions for follow-up notes — pick any to go deeper:

• How does a single adapter actually connect and dispatch incoming messages? (lifecycle in BasePlatformAdapter)
• How are sessions identified across platforms? (session_key, chat_id, thread_id)
• How does the agent's send_message tool decide which channel to write to, and what happens when the adapter is offline (cron, MCP)?
• What does message chunking / typing heartbeat / interrupt look like, end to end?
• How do plugin.yaml, register(ctx), and bundled plugin discovery work together?