Gateway Internals

​

Key Files

​

Architecture Overview

┌─────────────────────────────────────────────────┐
│                  GatewayRunner                  │
│                                                 │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐       │
│  │ Telegram │  │ Discord  │  │  Slack   │       │
│  │ Adapter  │  │ Adapter  │  │ Adapter  │       │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘       │
│       │             │             │             │
│       └─────────────┼─────────────┘             │
│                     ▼                           │
│              _handle_message()                  │
│                     │                           │
│         ┌───────────┼───────────┐               │
│         ▼           ▼           ▼               │
│  Slash command   AIAgent    Queue/BG            │
│    dispatch      creation   sessions            │
│                     │                           │
│                     ▼                           │
│                 SessionStore                    │
│              (SQLite persistence)               │
└───────┴─────────────┴─────────────┴─────────────┘

​

Message Flow

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:{namespace}:{platform}:{chat_type}:{chat_id}; the namespace is main for the default profile, <profile> under multiplexing — see Multiplexed profiles)
   • 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

agent:{namespace}:{platform}:{chat_type}:{chat_id}

​

Two-Level Message Guard

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_inbound.py): Checks _running_agents. Intercepts specific commands (/stop, /new, /queue, /status, /approve, /deny) and routes them appropriately. Everything else triggers running_agent.interrupt().

​

Authorization

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, or gateway.allow_all_users in config.yaml, bridged to the env var by gateway/config_loader.py::bridge_core_env_settings) — if set, all users across all platforms are authorized
5. Default: deny — unauthorized users are rejected

​

DM Pairing Flow

Admin: /pair
Gateway: "Pairing code: ABC123. Share with the user."
New user: ABC123
Gateway: "Paired! You're now authorized."

​

Slash Command Dispatch

1. resolve_command() from mibyan_cli/commands.py maps input to canonical name (handles aliases, prefix matching)
2. The canonical name is checked against GATEWAY_KNOWN_COMMANDS
3. _handle_message() (gateway/run_inbound.py) looks the handler up by name — _handle_<name>_command on the gateway/slash_commands_*.py mixins — via _command_handler_table over _IDLE_COMMANDS / _PLAIN_COMMANDS in gateway/run_busy.py; there is no if canonical == ... chain
4. Some commands are gated on config (gateway_config_gate on CommandDef)

​

Running-Agent Guard

​

Config Sources

​

Platform Adapters

plugins/platforms/                  # plugin-packaged adapters (one dir each)
├── telegram/adapter.py     # Telegram Bot API (long polling or webhook)
├── discord/adapter.py      # Discord bot via discord.py
├── slack/adapter.py        # Slack Socket Mode
├── whatsapp/adapter.py     # WhatsApp Business Cloud API
├── matrix/adapter.py       # Matrix via mautrix (optional E2EE)
├── mattermost/adapter.py   # Mattermost WebSocket API
├── email/adapter.py        # Email via IMAP/SMTP
├── sms/adapter.py          # SMS via Twilio
├── dingtalk/adapter.py     # DingTalk WebSocket
├── feishu/adapter.py       # Feishu/Lark WebSocket or webhook
├── wecom/adapter.py        # WeCom (WeChat Work) callback
├── line/adapter.py         # LINE Messaging API
├── teams/adapter.py        # Microsoft Teams
├── irc/adapter.py          # IRC (canonical scoped-lock example)
├── homeassistant/adapter.py # Home Assistant conversation integration
└── …                       # google_chat, ntfy, photon, raft, simplex, …

gateway/platforms/                  # core base + legacy direct adapters
├── base.py              # BasePlatformAdapter — shared logic for all platforms
├── signal.py            # Signal via signal-cli REST API
├── weixin.py            # Weixin (personal WeChat) via iLink Bot API
├── bluebubbles.py       # Apple iMessage via BlueBubbles macOS server
├── qqbot/               # QQ Bot (Tencent QQ) via Official API v2 (sub-package)
├── yuanbao.py           # Yuanbao (Tencent) DM/group adapter
├── msgraph_webhook.py   # Microsoft Graph change-notification webhook (Teams, Outlook, etc.)
├── webhook.py           # Inbound/outbound webhook adapter
└── api_server.py        # REST API server adapter

• connect() / disconnect() — lifecycle management
• send() — outbound message delivery
• inbound events are normalized into a MessageEvent and forwarded via handle_message()

​

Token Locks

​

Delivery Path

• 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 — the send engine specifying telegram:-1001234567890, exposed via the mibyan send CLI for shell scripts and via cron deliver: targets
• Cross-platform delivery — deliver to a different platform than the originating message

​

Hooks

​

Gateway Hook Events

​

Memory Provider Integration

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:

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

​

Background Maintenance

• Cron ticking — checks job schedules and fires due jobs
• Session housekeeping — reclaims cached resources without ending transcripts
• Memory flush — commits memory before soft cache eviction
• Cache refresh — refreshes model lists and provider status

​

Process Management

• mibyan gateway start / mibyan gateway stop — manual control
• systemctl (Linux) or launchctl (macOS) — service management
• PID file at ~/.mibyan/gateway.pid — profile-scoped process tracking

​

Multiplexed profiles

​

Mid-run plugin loading

• Discovery listener — _start_recover_previous_run subscribes PluginManager.on_plugin_loaded for the launch profile and _load_secondary_profile_config does so per served profile. The event fires from inside discover_and_load (never from an RPC) for the newly loaded plugins; the callback hops onto the gateway loop with call_soon_threadsafe.
• Idempotent re-wire — BasePlatformAdapter.rewire_plugin_handlers() re-reads get_platform_handler_factories(platform) and runs only factories not yet wired on the live native client (keyed (plugin, qualname) because a force reload hands back new function objects). Telegram hoists the added handlers ahead of core’s catch-alls; Slack also re-registers missing register_slack_action_handler callbacks once per AsyncApp.
• reload-plugins control verb — other processes (mibyan plugins install, mibyan serve) ask the running gateway to force-rescan the requested (served) home; the answer carries plugins, per-plugin activations and adapters_rewired, so the caller can say “active now” truthfully.
• Scope limit — handlers only. Tools and system-prompt sections of a late plugin wait for the next session (prompt-cache invariant); portable MCP servers wait for mcp.reload. Nothing un-wires on disable.

​

Related Docs

• Session Storage
• Cron Internals
• ACP Internals
• Agent Loop Internals
• Messaging Gateway (User Guide)