Spaces:
Paused
Paused
| sidebar_position: 7 | |
| title: "Gateway Internals" | |
| description: "How the messaging gateway boots, authorizes users, routes sessions, and delivers messages" | |
| # Gateway Internals | |
| The messaging gateway is the long-running process that connects Hermes to 14+ external messaging platforms through a unified architecture. | |
| ## Key Files | |
| | File | Purpose | | |
| |------|---------| | |
| | `gateway/run.py` | `GatewayRunner` — main loop, slash commands, message dispatch (~7,500 lines) | | |
| | `gateway/session.py` | `SessionStore` — conversation persistence and session key construction | | |
| | `gateway/delivery.py` | Outbound message delivery to target platforms/channels | | |
| | `gateway/pairing.py` | DM pairing flow for user authorization | | |
| | `gateway/channel_directory.py` | Maps chat IDs to human-readable names for cron delivery | | |
| | `gateway/hooks.py` | Hook discovery, loading, and lifecycle event dispatch | | |
| | `gateway/mirror.py` | Cross-session message mirroring for `send_message` | | |
| | `gateway/status.py` | Token lock management for profile-scoped gateway instances | | |
| | `gateway/builtin_hooks/` | Always-registered hooks (e.g., BOOT.md system prompt hook) | | |
| | `gateway/platforms/` | Platform adapters (one per messaging platform) | | |
| ## Architecture Overview | |
| ```text | |
| ┌─────────────────────────────────────────────────┐ | |
| │ GatewayRunner │ | |
| │ │ | |
| │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ | |
| │ │ Telegram │ │ Discord │ │ Slack │ ... │ | |
| │ │ Adapter │ │ Adapter │ │ Adapter │ │ | |
| │ └─────┬─────┘ └─────┬────┘ └─────┬────┘ │ | |
| │ │ │ │ │ | |
| │ └──────────────┼──────────────┘ │ | |
| │ ▼ │ | |
| │ _handle_message() │ | |
| │ │ │ | |
| │ ┌────────────┼────────────┐ │ | |
| │ ▼ ▼ ▼ │ | |
| │ Slash command AIAgent Queue/BG │ | |
| │ dispatch creation sessions │ | |
| │ │ │ | |
| │ ▼ │ | |
| │ SessionStore │ | |
| │ (SQLite persistence) │ | |
| └─────────────────────────────────────────────────┘ | |
| ``` | |
| ## Message Flow | |
| When a message arrives from any platform: | |
| 1. **Platform adapter** receives raw event, normalizes it into a `MessageEvent` | |
| 2. **Base adapter** checks active session guard: | |
| - If agent is running for this session → queue message, set interrupt event | |
| - If `/approve`, `/deny`, `/stop` → bypass guard (dispatched inline) | |
| 3. **GatewayRunner._handle_message()** receives the event: | |
| - Resolve session key via `_session_key_for_source()` (format: `agent:main:{platform}:{chat_type}:{chat_id}`) | |
| - Check authorization (see Authorization below) | |
| - Check if it's a slash command → dispatch to command handler | |
| - Check if agent is already running → intercept commands like `/stop`, `/status` | |
| - Otherwise → create `AIAgent` instance and run conversation | |
| 4. **Response** is sent back through the platform adapter | |
| ### Session Key Format | |
| Session keys encode the full routing context: | |
| ``` | |
| agent:main:{platform}:{chat_type}:{chat_id} | |
| ``` | |
| For example: `agent:main:telegram:private:123456789` | |
| Thread-aware platforms (Telegram forum topics, Discord threads, Slack threads) may include thread IDs in the chat_id portion. **Never construct session keys manually** — always use `build_session_key()` from `gateway/session.py`. | |
| ### Two-Level Message Guard | |
| When an agent is actively running, incoming messages pass through two sequential guards: | |
| 1. **Level 1 — Base adapter** (`gateway/platforms/base.py`): Checks `_active_sessions`. If the session is active, queues the message in `_pending_messages` and sets an interrupt event. This catches messages *before* they reach the gateway runner. | |
| 2. **Level 2 — Gateway runner** (`gateway/run.py`): Checks `_running_agents`. Intercepts specific commands (`/stop`, `/new`, `/queue`, `/status`, `/approve`, `/deny`) and routes them appropriately. Everything else triggers `running_agent.interrupt()`. | |
| Commands that must reach the runner while the agent is blocked (like `/approve`) are dispatched **inline** via `await self._message_handler(event)` — they bypass the background task system to avoid race conditions. | |
| ## Authorization | |
| The gateway uses a multi-layer authorization check, evaluated in order: | |
| 1. **Per-platform allow-all flag** (e.g., `TELEGRAM_ALLOW_ALL_USERS`) — if set, all users on that platform are authorized | |
| 2. **Platform allowlist** (e.g., `TELEGRAM_ALLOWED_USERS`) — comma-separated user IDs | |
| 3. **DM pairing** — authenticated users can pair new users via a pairing code | |
| 4. **Global allow-all** (`GATEWAY_ALLOW_ALL_USERS`) — if set, all users across all platforms are authorized | |
| 5. **Default: deny** — unauthorized users are rejected | |
| ### DM Pairing Flow | |
| ```text | |
| Admin: /pair | |
| Gateway: "Pairing code: ABC123. Share with the user." | |
| New user: ABC123 | |
| Gateway: "Paired! You're now authorized." | |
| ``` | |
| Pairing state is persisted in `gateway/pairing.py` and survives restarts. | |
| ## Slash Command Dispatch | |
| All slash commands in the gateway flow through the same resolution pipeline: | |
| 1. `resolve_command()` from `hermes_cli/commands.py` maps input to canonical name (handles aliases, prefix matching) | |
| 2. The canonical name is checked against `GATEWAY_KNOWN_COMMANDS` | |
| 3. Handler in `_handle_message()` dispatches based on canonical name | |
| 4. Some commands are gated on config (`gateway_config_gate` on `CommandDef`) | |
| ### Running-Agent Guard | |
| Commands that must NOT execute while the agent is processing are rejected early: | |
| ```python | |
| if _quick_key in self._running_agents: | |
| if canonical == "model": | |
| return "⏳ Agent is running — wait for it to finish or /stop first." | |
| ``` | |
| Bypass commands (`/stop`, `/new`, `/approve`, `/deny`, `/queue`, `/status`) have special handling. | |
| ## Config Sources | |
| The gateway reads configuration from multiple sources: | |
| | Source | What it provides | | |
| |--------|-----------------| | |
| | `~/.hermes/.env` | API keys, bot tokens, platform credentials | | |
| | `~/.hermes/config.yaml` | Model settings, tool configuration, display options | | |
| | Environment variables | Override any of the above | | |
| Unlike the CLI (which uses `load_cli_config()` with hardcoded defaults), the gateway reads `config.yaml` directly via YAML loader. This means config keys that exist in the CLI's defaults dict but not in the user's config file may behave differently between CLI and gateway. | |
| ## Platform Adapters | |
| Each messaging platform has an adapter in `gateway/platforms/`: | |
| ```text | |
| gateway/platforms/ | |
| ├── base.py # BaseAdapter — shared logic for all platforms | |
| ├── telegram.py # Telegram Bot API (long polling or webhook) | |
| ├── discord.py # Discord bot via discord.py | |
| ├── slack.py # Slack Socket Mode | |
| ├── whatsapp.py # WhatsApp Business Cloud API | |
| ├── signal.py # Signal via signal-cli REST API | |
| ├── matrix.py # Matrix via mautrix (optional E2EE) | |
| ├── mattermost.py # Mattermost WebSocket API | |
| ├── email.py # Email via IMAP/SMTP | |
| ├── sms.py # SMS via Twilio | |
| ├── dingtalk.py # DingTalk WebSocket | |
| ├── feishu.py # Feishu/Lark WebSocket or webhook | |
| ├── wecom.py # WeCom (WeChat Work) callback | |
| ├── weixin.py # Weixin (personal WeChat) via iLink Bot API | |
| ├── bluebubbles.py # Apple iMessage via BlueBubbles macOS server | |
| ├── webhook.py # Inbound/outbound webhook adapter | |
| ├── api_server.py # REST API server adapter | |
| └── homeassistant.py # Home Assistant conversation integration | |
| ``` | |
| Adapters implement a common interface: | |
| - `connect()` / `disconnect()` — lifecycle management | |
| - `send_message()` — outbound message delivery | |
| - `on_message()` — inbound message normalization → `MessageEvent` | |
| ### Token Locks | |
| Adapters that connect with unique credentials call `acquire_scoped_lock()` in `connect()` and `release_scoped_lock()` in `disconnect()`. This prevents two profiles from using the same bot token simultaneously. | |
| ## Delivery Path | |
| Outgoing deliveries (`gateway/delivery.py`) handle: | |
| - **Direct reply** — send response back to the originating chat | |
| - **Home channel delivery** — route cron job outputs and background results to a configured home channel | |
| - **Explicit target delivery** — `send_message` tool specifying `telegram:-1001234567890` | |
| - **Cross-platform delivery** — deliver to a different platform than the originating message | |
| Cron job deliveries are NOT mirrored into gateway session history — they live in their own cron session only. This is a deliberate design choice to avoid message alternation violations. | |
| ## Hooks | |
| Gateway hooks are Python modules that respond to lifecycle events: | |
| ### Gateway Hook Events | |
| | Event | When fired | | |
| |-------|-----------| | |
| | `gateway:startup` | Gateway process starts | | |
| | `session:start` | New conversation session begins | | |
| | `session:end` | Session completes or times out | | |
| | `session:reset` | User resets session with `/new` | | |
| | `agent:start` | Agent begins processing a message | | |
| | `agent:step` | Agent completes one tool-calling iteration | | |
| | `agent:end` | Agent finishes and returns response | | |
| | `command:*` | Any slash command is executed | | |
| Hooks are discovered from `gateway/builtin_hooks/` (always active) and `~/.hermes/hooks/` (user-installed). Each hook is a directory with a `HOOK.yaml` manifest and `handler.py`. | |
| ## Memory Provider Integration | |
| When a memory provider plugin (e.g., Honcho) is enabled: | |
| 1. Gateway creates an `AIAgent` per message with the session ID | |
| 2. The `MemoryManager` initializes the provider with the session context | |
| 3. Provider tools (e.g., `honcho_profile`, `viking_search`) are routed through: | |
| ```text | |
| AIAgent._invoke_tool() | |
| → self._memory_manager.handle_tool_call(name, args) | |
| → provider.handle_tool_call(name, args) | |
| ``` | |
| 4. On session end/reset, `on_session_end()` fires for cleanup and final data flush | |
| ### Memory Flush Lifecycle | |
| When a session is reset, resumed, or expires: | |
| 1. Built-in memories are flushed to disk | |
| 2. Memory provider's `on_session_end()` hook fires | |
| 3. A temporary `AIAgent` runs a memory-only conversation turn | |
| 4. Context is then discarded or archived | |
| ## Background Maintenance | |
| The gateway runs periodic maintenance alongside message handling: | |
| - **Cron ticking** — checks job schedules and fires due jobs | |
| - **Session expiry** — cleans up abandoned sessions after timeout | |
| - **Memory flush** — proactively flushes memory before session expiry | |
| - **Cache refresh** — refreshes model lists and provider status | |
| ## Process Management | |
| The gateway runs as a long-lived process, managed via: | |
| - `hermes gateway start` / `hermes gateway stop` — manual control | |
| - `systemctl` (Linux) or `launchctl` (macOS) — service management | |
| - PID file at `~/.hermes/gateway.pid` — profile-scoped process tracking | |
| **Profile-scoped vs global**: `start_gateway()` uses profile-scoped PID files. `hermes gateway stop` stops only the current profile's gateway. `hermes gateway stop --all` uses global `ps aux` scanning to kill all gateway processes (used during updates). | |
| ## Related Docs | |
| - [Session Storage](./session-storage.md) | |
| - [Cron Internals](./cron-internals.md) | |
| - [ACP Internals](./acp-internals.md) | |
| - [Agent Loop Internals](./agent-loop.md) | |
| - [Messaging Gateway (User Guide)](/docs/user-guide/messaging) | |