docs: update project state through Phase 3

Phase 2: memory, session search, git worktree configured Phase 3: Telegram gateway connected, DM pairing approved Phase 4: custom skills created (aws-diagnostics, jira-query, confluence-search, bitbucket-pr)
2026-06-14 12:02:04 +08:00
parent 5911cbdad0
commit 0355858596
26 changed files with 762 additions and 1 deletions
--- a/.planning/research/hermes/GATEWAY.md
+++ b/.planning/research/hermes/GATEWAY.md
@@ -0,0 +1,105 @@
+# Hermes Agent: Gateway System (Messaging)
+
+## Platform Support
+
+Hermes supports 20+ messaging platforms. Key ones for ngn-agent:
+
+| Platform | Voice | Images | Files | Threads | Reactions | Typing | Streaming |
+|----------|-------|--------|-------|---------|-----------|--------|-----------|
+| **Telegram** | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ |
+| **Discord** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| **Slack** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| **Microsoft Teams** | — | ✅ | — | ✅ | — | ✅ | — |
+| **Email** | — | ✅ | ✅ | ✅ | — | — | — |
+
+## Telegram Setup
+
+```bash
+# Interactive wizard
+hermes gateway setup
+
+# Or manual:
+# 1. Create bot via @BotFather → get token
+# 2. Set TELEGRAM_BOT_TOKEN in ~/.hermes/.env
+# 3. Set TELEGRAM_ALLOWED_USERS or use DM pairing
+# 4. Start gateway: hermes gateway
+# 5. Register as service: hermes gateway install
+```
+
+## Security & User Authorization
+
+**Default: deny all.** Every user must be in an allowlist or paired via DM.
+
+```yaml
+# Allowlist (recommended for known users)
+TELEGRAM_ALLOWED_USERS=123456789
+
+# DM pairing (alternative — users get pairing codes)
+# User DMs bot → gets code "XKGH5N7P"
+# Admin approves: hermes pairing approve telegram XKGH5N7P
+# Code expires 1hr, cryptographic randomness, rate-limited
+
+# Admin vs Regular user split
+gateway:
+  platforms:
+    telegram:
+      extra:
+        allow_from: ["111", "222"]
+        allow_admin_from: ["111"]
+        user_allowed_commands: [status, model]
+```
+
+## Session Management
+
+```yaml
+session_reset:
+  mode: both           # both | idle | daily | none
+  idle_minutes: 1440   # 24 hours
+  at_hour: 4           # 4 AM daily
+```
+
+Per-platform overrides:
+```json
+{
+  "reset_by_platform": {
+    "telegram": { "mode": "idle", "idle_minutes": 240 }
+  }
+}
+```
+
+## Gateway Commands
+
+```
+hermes gateway               # Run in foreground
+hermes gateway setup         # Configure platforms interactively
+hermes gateway install       # Install as service (launchd/systemd)
+hermes gateway start/stop/status
+```
+
+## Gateway Slash Commands (inside chat)
+
+`/new /reset /model /retry /undo /status /stop /approve /deny /sethome`
+`/compress /background /platform /skills /cron /help`
+
+## Multi-Platform Operations
+
+- `/platform list|pause|resume` — manage individual adapters without restart
+- Automatic circuit breaker — pauses adapter on repeated failures
+- Restart notifications — sends "agent is back" to home channels
+- Session resume across restarts — auto-recovers interrupted sessions
+
+## Admin vs Regular Users
+
+Two tiers: admin (full access) and user (restricted slash commands). Configured per platform per scope (DM vs group). Use `/whoami` to check your access.
+
+## Background Sessions
+
+`/background Check all servers` spawns isolated async agent. Results delivered to originating chat when done. Non-blocking — main chat stays interactive.
+
+## Key ngn-agent Considerations
+
+- **Start with Telegram** — most accessible, mobile-friendly
+- **Use DM pairing** for initial setup, switch to allowlist for stability
+- **Set session_reset.mode: idle** with longer timeout for infra context retention
+- **Background sessions** perfect for `"Check all prod servers"` type commands
+- **Circuit breaker** auto-pauses Telegram if API goes down — monitor gateway logs