[SPRINT-3] Add multi-platform messaging gateway (Telegram, Discord, Slack, WhatsApp)

[redsand]

Priority: Medium

Hermes's gateway is what makes it a 24/7 agent — it pushes scheduled results, cron outputs, and subagent completions to wherever you are. Our Discord integration exists but is chat-only. A proper gateway enables the agent to deliver proactive messages, not just respond to incoming ones.

Depends on: #185 (cron engine needs delivery targets), #180 (MEMORY.md for session continuity across platforms)

Blocks: None

Acceptance Criteria

• src/integrations/gateway/gateway-engine.ts created with GatewayEngine class
• Platform adapters for: Telegram, Discord (enhance existing), Slack, WhatsApp (via Signal bridge)
• Each adapter implements send(userId: string, message: string, options?: DeliveryOptions) and receive(): AsyncIterable<IncomingMessage>
• deliver tool registered for sending messages to platforms
• Session continuity: conversation started on Telegram can continue on Discord
• Gateway runs as a background service, reconnects on disconnect
• [SILENT] trick: messages containing [SILENT] are suppressed (no delivery)
• Delivery receipts tracked in data/gateway/delivery-log.json
• Unit tests in tests/unit/integrations/gateway/

Coding Prompt

Files to modify: src/integrations/gateway/gateway-engine.ts (new), src/integrations/gateway/platform-adapter.ts (new), src/integrations/gateway/telegram-adapter.ts (new), src/integrations/gateway/slack-adapter.ts (new), src/integrations/gateway/whatsapp-adapter.ts (new), src/integrations/discord/ (enhance existing), src/agent/tool-registry.ts (register deliver tool), src/agent/tool-dispatcher.ts (handle deliver tool), src/server.ts (start gateway on boot), src/config/env.ts (GATEWAY_ENABLED, platform tokens)

Current behavior: The Discord integration in src/integrations/discord/ handles incoming messages and routes them to the agent. There is no outbound delivery mechanism — the agent can only respond in the same channel where the message came from. There is no Telegram, Slack, or WhatsApp integration. The Signal integration in src/integrations/signal/ exists but is receive-only.

Required change:

1. Create src/integrations/gateway/platform-adapter.ts:

   interface PlatformAdapter {
     platform: string;
     send(userId: string, message: string, options?: DeliveryOptions): Promise<DeliveryResult>;
     receive(): AsyncIterable<IncomingMessage>;
     start(): Promise<void>;
     stop(): Promise<void>;
     isConnected(): boolean;
   }
   
   interface DeliveryOptions {
     parseMode?: 'markdown' | 'html' | 'plain';
     silent?: boolean;
     replyToMessageId?: string;
   }
   
   interface DeliveryResult {
     success: boolean;
     messageId?: string;
     platform: string;
     timestamp: string;
     suppressed: boolean; // true if [SILENT] was detected
   }
   
   interface IncomingMessage {
     platform: string;
     userId: string;
     channelId: string;
     content: string;
     timestamp: string;
     metadata?: Record<string, unknown>;
   }

2. Create src/integrations/gateway/gateway-engine.ts:

   • GatewayEngine class that manages all platform adapters
   • start(): Initialize all configured adapters, begin listening
   • stop(): Graceful shutdown, wait for in-flight messages
   • send(platform, userId, message, options?): Route message to correct adapter
   • broadcast(message, platforms?): Send to all platforms for a user
   • Session mapping: data/gateway/sessions.json maps {userId, platform} → sessionId for cross-platform continuity
   • [SILENT] detection: if message contains [SILENT], return { suppressed: true } without sending
   • Delivery logging: append to data/gateway/delivery-log.json

3. Create src/integrations/gateway/telegram-adapter.ts:

   • Use node-telegram-bot-api (add as dependency)
   • Polling mode (no webhook required for MVP)
   • Handle /start command to register user and link session
   • Support markdown formatting
   • Reconnect on disconnect with exponential backoff

4. Create src/integrations/gateway/slack-adapter.ts:

   • Use @slack/web-api and @slack/socket-mode (add as dependencies)
   • Socket Mode for real-time messages (no public URL needed)
   • Support thread replies and channel messages
   • Handle app mentions and DMs

5. Enhance existing src/integrations/discord/:

   • Add outbound delivery method (currently receive-only)
   • Support DMs and channel messages
   • Reuse existing Discord.js client

6. Create src/integrations/gateway/whatsapp-adapter.ts:

   • Bridge through Signal (reuse existing src/integrations/signal/)
   • WhatsApp messages → Signal → gateway → agent
   • Document the Signal-WhatsApp bridge setup in README

7. Register deliver tool:

   • platform: "telegram" | "discord" | "slack" | "whatsapp"
   • user_id: string (platform-specific user ID)
   • message: string
   • silent: boolean (optional, default false)

Code patterns to follow:

• Follow the existing adapter pattern from src/integrations/discord/
• Use environment variables for platform tokens (consistent with src/config/env.ts)
• AsyncIterable for message streams (follow Node.js AsyncGenerator pattern)
• Delivery logging follows the JSON file pattern from ConversationManager
• Error handling: each adapter catches its own errors and reports via DeliveryResult, never crashes the gateway

Files to add/update tests in: tests/unit/integrations/gateway/gateway-engine.test.ts, tests/unit/integrations/gateway/platform-adapter.test.ts

Reasoning: The gateway is what makes an agent proactive rather than reactive. Without it, the agent can only respond when you type. With it, scheduled tasks, reflections, and subagent results can reach you wherever you are. Cross-platform session continuity means you can start on Telegram and pick up on Discord without losing context.

[redsand]

Dependency Analysis (AI Assistant)

Chain: hermes-automation — #185 → #188

#188 (multi-platform messaging gateway) depends on #185 (cron engine) because the gateway provides delivery targets for scheduled task outputs. Without cron, the gateway has nothing proactive to deliver. It also depends on #180 (MEMORY.md) for cross-platform session continuity.

Depends on: #180, #185
Blocks: None

Recommendation: Sprint 3, after cron engine is complete. The gateway transforms the agent from reactive (only responds when you type) to proactive (pushes insights to you wherever you are).

[redsand]

🤖 AiRemoteCoder completed work

• Branch: ai/issue-188-sprint-3-add-multi-platform-messaging-ga
• PR: [AI] [SPRINT-3] Add multi-platform messaging gateway (Telegram, Discord, Slack, WhatsApp) #202
• Exit code: 0

Review is in progress.

[redsand]

Coding Prompt

Rework from PR Review

The following must be completed before merge:

Required Tests (do these first)

• Write tests for unknown: No unit tests for GatewayEngine (send, broadcast, session mapping, [SILENT] suppression logic)
• Write tests for unknown: No unit tests for platform adapters (Telegram, Slack, Discord) with mocked clients
• Write tests for gateway.deliver: No integration test for gateway.deliver tool handler validating param checks and error paths

Required Fixes

• Fix [critical] quality issue in src/agent/tool-registry.ts:7567: src/agent/tool-registry.ts:7567 — gateway.deliver riskLevel is "low" but enables arbitrary outbound messaging to any user on any platform; should be at least "medium" to require appropriate approval gating
• Fix [high] security issue in src/agent/tool-dispatcher.ts:5330: src/agent/tool-dispatcher.ts:5330 — No rate limiting on gateway.deliver; agent could spam users across all platforms without throttling
• Fix [high] security issue in src/agent/tool-registry.ts:7567: src/agent/tool-registry.ts:7567 — gateway.deliver riskLevel is "low" allowing auto-approval of unsolicited outbound messages to arbitrary user IDs

Reviewer Notes

The gateway architecture looks solid — clean adapter pattern, session persistence, and [SILENT] suppression are well-designed. A few things to address before merge:

• Risk level: gateway.deliver is marked riskLevel: "low" but enables arbitrary outbound messaging to any user. This should be "medium" to ensure proper approval gating.
• Synchronous I/O: logDelivery and saveSessions use fs.appendFileSync/writeFileSync which block the event loop. Switch to async equivalents.
• Infinite reconnect: Telegram adapter's reconnect() has no max retry cap — add a limit.
• No rate limiting: The agent can spam users across all platforms without throttling. Consider adding per-platform rate limits.
• Missing tests: No unit or integration tests for any of the new gateway code.

Reasoning

These findings were identified by the security, QA, code quality, and regression review agents. All critical and high severity issues must be resolved and all test gaps must be filled. Re-run the full implementation addressing each item.

[redsand]

Review Complete for MR !202

❌ Review Failed — Rework Required

The gateway architecture looks solid — clean adapter pattern, session persistence, and [SILENT] suppression are well-designed. A few things to address before merge:

• Risk level: gateway.deliver is marked riskLevel: "low" but enables arbitrary outbound messaging to any user. This should be "medium" to ensure proper approval gating.
• Synchronous I/O: logDelivery and saveSessions use fs.appendFileSync/writeFileSync which block the event loop. Switch to async equivalents.
• Infinite reconnect: Telegram adapter's reconnect() has no max retry cap — add a limit.
• No rate limiting: The agent can spam users across all platforms without throttling. Consider adding per-platform rate limits.
• Missing tests: No unit or integration tests for any of the new gateway code.

Findings

• [CRITICAL] [quality] src/agent/tool-registry.ts:7567: src/agent/tool-registry.ts:7567 — gateway.deliver riskLevel is "low" but enables arbitrary outbound messaging to any user on any platform; should be at least "medium" to require appropriate approval gating
  → Suggestion: See the full review comment on the PR.
• [HIGH] [security] src/agent/tool-dispatcher.ts:5330: src/agent/tool-dispatcher.ts:5330 — No rate limiting on gateway.deliver; agent could spam users across all platforms without throttling
  → Suggestion: See the full review comment on the PR.
• [HIGH] [security] src/agent/tool-registry.ts:7567: src/agent/tool-registry.ts:7567 — gateway.deliver riskLevel is "low" allowing auto-approval of unsolicited outbound messages to arbitrary user IDs
  → Suggestion: See the full review comment on the PR.
• [MEDIUM] [quality] src/integrations/gateway/gateway-engine.ts:188: src/integrations/gateway/gateway-engine.ts:188 — logDelivery uses synchronous fs.appendFileSync which blocks the event loop on every delivery
  → Suggestion: See the full review comment on the PR.
• [MEDIUM] [quality] src/integrations/gateway/gateway-engine.ts:178: src/integrations/gateway/gateway-engine.ts:178 — saveSessions uses synchronous fs.writeFileSync and fs.renameSync; should use async equivalents
  → Suggestion: See the full review comment on the PR.
• [MEDIUM] [quality] src/integrations/gateway/telegram-adapter.ts:67: src/integrations/gateway/telegram-adapter.ts:67 — reconnect() retries indefinitely with no max retry limit; will loop forever if Telegram is permanently unavailable
  → Suggestion: See the full review comment on the PR.
• [MEDIUM] [quality] src/agent/tool-dispatcher.ts:5330: src/agent/tool-dispatcher.ts:5330 — No message content length limit or sanitization before passing to adapters; extremely long messages could cause API errors
  → Suggestion: See the full review comment on the PR.
• [MEDIUM] [qa] unknown: No unit tests for GatewayEngine (send, broadcast, session mapping, [SILENT] suppression logic)
  → Suggestion: See the full review comment on the PR.
• [MEDIUM] [qa] unknown: No unit tests for platform adapters (Telegram, Slack, Discord) with mocked clients
  → Suggestion: See the full review comment on the PR.
• [MEDIUM] [qa] gateway.deliver: No integration test for gateway.deliver tool handler validating param checks and error paths
  → Suggestion: See the full review comment on the PR.
• [MEDIUM] [quality] src/integrations/gateway/gateway-engine.ts:188: src/integrations/gateway/gateway-engine.ts:188 — Synchronous delivery logging blocks event loop under high throughput
  → Suggestion: See the full review comment on the PR.
• [MEDIUM] [quality] unknown: No metrics or counters for delivery success/failure rates, latency, or suppression rates across platforms
  → Suggestion: See the full review comment on the PR.
• [LOW] [quality] unknown: Configure TELEGRAM_BOT_TOKEN, SLACK_BOT_TOKEN, SLACK_APP_TOKEN in production environment before enabling GATEWAY_ENABLED
  → Suggestion: See the full review comment on the PR.
• [LOW] [quality] unknown: Review and approve Discord bot privileged intents (MessageContent) in Discord Developer Portal
  → Suggestion: See the full review comment on the PR.
• [LOW] [quality] unknown: Create Telegram bot via BotFather and obtain token before enabling Telegram adapter
  → Suggestion: See the full review comment on the PR.

A rework prompt has been added to the linked issue. AiRemoteCoder will pick it up.

[redsand]

Coding Prompt

Rework from PR Review

The following must be completed before merge:

Required Tests (do these first)

• Write tests for unknown: No unit tests for GatewayEngine (send, broadcast, session mapping, [SILENT] suppression)
• Write tests for unknown: No unit tests for any platform adapter (Telegram, Discord, Slack)
• Write tests for gateway.deliver: No integration test for gateway.deliver tool handler

Required Fixes

• Fix [high] security issue in tool-dispatcher.ts:5321: tool-dispatcher.ts:5321-5369 — No authorization check; any agent user can send messages to any platform user ID
• Fix [high] security issue in tool-dispatcher.ts:5333: tool-dispatcher.ts:5333 — Message content is not sanitized before delivery; could enable Discord @everyone pings or Telegram HTML injection
• Fix [high] quality issue in data/gateway/sessions.json: data/gateway/sessions.json format has no versioning; schema changes could break existing session data

Reviewer Notes

Good foundation for the messaging gateway, but a few things need attention before merge.

• Missing initialization: I don't see where adapters are registered and gatewayEngine.start() is called — the tool handler will always fail without this wiring. Can you point to where this happens?
• Risk level: gateway.deliver is riskLevel: 'low' but sends messages to external users — should be at least 'medium'.
• No rate limiting: A runaway agent could spam users across all platforms unchecked.
• No authz: Any agent user can message any platform user ID.
• Infinite reconnect: Telegram adapter retries forever with no max limit.
• Unbounded log: delivery-log.jsonl grows without rotation.
• Param validation: as string casts without runtime checks — numeric user IDs from JSON would pass as numbers.
• No tests: None of the new gateway code has unit or integration tests.

Reasoning

These findings were identified by the security, QA, code quality, and regression review agents. All critical and high severity issues must be resolved and all test gaps must be filled. Re-run the full implementation addressing each item.

[redsand]

Review Complete for MR !202

❌ Review Failed — Rework Required

Good foundation for the messaging gateway, but a few things need attention before merge.

• Missing initialization: I don't see where adapters are registered and gatewayEngine.start() is called — the tool handler will always fail without this wiring. Can you point to where this happens?
• Risk level: gateway.deliver is riskLevel: 'low' but sends messages to external users — should be at least 'medium'.
• No rate limiting: A runaway agent could spam users across all platforms unchecked.
• No authz: Any agent user can message any platform user ID.
• Infinite reconnect: Telegram adapter retries forever with no max limit.
• Unbounded log: delivery-log.jsonl grows without rotation.
• Param validation: as string casts without runtime checks — numeric user IDs from JSON would pass as numbers.
• No tests: None of the new gateway code has unit or integration tests.

Findings

• [HIGH] [security] tool-dispatcher.ts:5321: tool-dispatcher.ts:5321-5369 — No authorization check; any agent user can send messages to any platform user ID
  → Suggestion: See the full review comment on the PR.
• [HIGH] [security] tool-dispatcher.ts:5333: tool-dispatcher.ts:5333 — Message content is not sanitized before delivery; could enable Discord @everyone pings or Telegram HTML injection
  → Suggestion: See the full review comment on the PR.
• [HIGH] [quality] data/gateway/sessions.json: data/gateway/sessions.json format has no versioning; schema changes could break existing session data
  → Suggestion: See the full review comment on the PR.
• [MEDIUM] [quality] tool-registry.ts:7565: tool-registry.ts:7565 — gateway.deliver riskLevel is 'low' but sending arbitrary messages to external platform users should be at least 'medium'
  → Suggestion: See the full review comment on the PR.
• [MEDIUM] [quality] telegram-adapter.ts:92: telegram-adapter.ts:92-97 — reconnect() has no max retry limit; permanent failures cause infinite reconnection loops
  → Suggestion: See the full review comment on the PR.
• [MEDIUM] [quality] gateway-engine.ts:197: gateway-engine.ts:197-202 — delivery-log.jsonl grows unbounded with no rotation or size limit
  → Suggestion: See the full review comment on the PR.
• [MEDIUM] [quality] gateway-engine.ts:160: gateway-engine.ts:160 — saveSessions() uses synchronous fs.writeFileSync on every mapSession call; should be debounced or async
  → Suggestion: See the full review comment on the PR.
• [MEDIUM] [quality] tool-dispatcher.ts:5325: tool-dispatcher.ts:5325-5328 — params are cast with as string without runtime validation; numeric user_ids from JSON would pass as numbers, not strings
  → Suggestion: See the full review comment on the PR.
• [MEDIUM] [qa] unknown: No unit tests for GatewayEngine (send, broadcast, session mapping, [SILENT] suppression)
  → Suggestion: See the full review comment on the PR.
• [MEDIUM] [qa] unknown: No unit tests for any platform adapter (Telegram, Discord, Slack)
  → Suggestion: See the full review comment on the PR.
• [MEDIUM] [qa] gateway.deliver: No integration test for gateway.deliver tool handler
  → Suggestion: See the full review comment on the PR.
• [MEDIUM] [quality] gateway-engine.ts:197: gateway-engine.ts:197-202 — Delivery log is file-based JSONL with no structured metrics or alerting on failure rates
  → Suggestion: See the full review comment on the PR.
• [MEDIUM] [quality] unknown: No health check or status method to verify adapter connectivity at runtime
  → Suggestion: See the full review comment on the PR.
• [LOW] [quality] unknown: Configure TELEGRAM_BOT_TOKEN, SLACK_BOT_TOKEN, SLACK_APP_TOKEN as secure environment variables before enabling gateway
  → Suggestion: See the full review comment on the PR.
• [LOW] [quality] unknown: Create and configure bot accounts with minimum required permissions on each platform
  → Suggestion: See the full review comment on the PR.
• [LOW] [quality] unknown: Review Discord bot intent approvals (MessageContent intent requires verification for large guilds)
  → Suggestion: See the full review comment on the PR.

A rework prompt has been added to the linked issue. AiRemoteCoder will pick it up.

[redsand]

Coding Prompt

Rework from PR Review

The following must be completed before merge:

Required Tests (do these first)

• Write tests for unknown: No unit tests for GatewayEngine (send, broadcast, session mapping, [SILENT] suppression, adapter-not-found path)
• Write tests for unknown: No unit tests for any platform adapter (Telegram, Discord, Slack)
• Write tests for gateway.deliver: No integration test for the gateway.deliver tool handler in tool-dispatcher.ts

Required Fixes

• Fix [critical] quality issue in src/integrations/gateway/gateway-engine.ts:220: src/integrations/gateway/gateway-engine.ts:220 — The exported gatewayEngine singleton is never initialized: no adapters are registered and start() is never called anywhere in the diff. Every gateway.deliver call will fail with 'No adapter registered for platform'. Add bootstrap code that reads env config, instantiates adapters, registers them, and starts the engine.
• Fix [critical] quality issue in src/integrations/gateway/telegram-adapter.ts:95: src/integrations/gateway/telegram-adapter.ts:95 — The receive() async generator hangs forever on stop: when stop() sets stopped=true, any pending await new Promise(...) never resolves, leaking memory. Same issue in discord-gateway-adapter.ts:148 and slack-adapter.ts:128. Resolve or reject waiting consumers in stop().
• Fix [high] security issue in src/agent/tool-dispatcher.ts:5325: src/agent/tool-dispatcher.ts:5325 — No rate limiting on gateway.deliver; an agent could spam messages to external platform users. Add per-user/per-platform rate limits.
• Fix [high] security issue in src/integrations/gateway/gateway-engine.ts:89: src/integrations/gateway/gateway-engine.ts:89 — Message content is passed through to external platforms without sanitization, enabling potential injection of markdown/HTML in Telegram or Slack messages.
• Fix [high] quality issue in src/integrations/gateway/gateway-engine.ts:170: src/integrations/gateway/gateway-engine.ts:170 — New data/gateway/sessions.json file created at runtime; no migration needed but existing deployments must ensure the data directory is writable and persisted across restarts.

Reviewer Notes

The gateway architecture looks solid, but there's a critical initialization gap that will cause every gateway.deliver call to fail at runtime.

• Must fix: The gatewayEngine singleton is never bootstrapped — no adapters are registered and start() is never called. Add initialization code that reads env vars, creates adapter instances, registers them, and starts the engine.
• Must fix: The receive() async generators in all three adapters leak hanging Promises when stop() is called. Resolve waiting consumers in stop().
• Should fix: riskLevel: 'low' on gateway.deliver is too permissive for a tool that sends messages to arbitrary external users.
• Should fix: Delivery log grows unbounded; add rotation.
• No tests exist for any of the new gateway code.

Reasoning

These findings were identified by the security, QA, code quality, and regression review agents. All critical and high severity issues must be resolved and all test gaps must be filled. Re-run the full implementation addressing each item.