# Hermes Rocket.Chat Plugin — Community Release

> **Nützliches Add-on für [Hermes Agent](https://hermes-agent.nousresearch.com/)**  
> Verbindet Hermes Agent mit einem selbst-gehosteten Rocket.Chat-Server.

---

## Was ist das?

Dieses Plugin verwandelt Hermes Agent in einen **nativen Rocket.Chat-Benutzer** — mit Echtzeit-Nachrichten, Präsenz-Status und interaktiven Buttons.

Statt über ein separates Gateway-Binary zu kommunizieren, spricht Hermes Agent direkt mit Rocket.Chat:
- **Eingehend**: WebSocket/DDP für sofortige Nachrichten
- **Ausgehend**: REST-API für Antworten, Buttons, Dateien

---

## Features

| Feature | Beschreibung |
|---------|-------------|
| 🚀 Echtzeit-Streaming | DDP/WebSocket für instant eingehende Nachrichten |
| 🟢 Präsenz | Grüner Online-Status im Rocket.Chat |
| ✍️ Markdown | Fett, kursiv, `Code`, Blöcke, Links |
| 🔘 Interaktive Buttons | Ja/Nein, Bestätigen/Abbrechen, Mehrfachauswahl |
| 📢 Räume | Kanäle, private Gruppen, Direktnachrichten |
| 🔒 Allowlist | Nur erlaubte Benutzer dürfen den Bot nutzen |
| 📦 Zero-Dependency | Nutzt ausschließlich Python-Standardbibliothek |

---

## Schnellstart

### 1. Voraussetzungen

- Hermes Agent installiert ([Setup-Guide](https://hermes-agent.nousresearch.com/docs))
- Laufender Rocket.Chat-Server (v5+ empfohlen)
- Bot-Benutzer auf Rocket.Chat mit Login-Daten

### 2. Plugin herunterladen

```bash
git clone https://gitea.thomander.de/andreas/Hermes_rocket.chat_Plugin.git
cd Hermes_rocket.chat_Plugin
```

### 3. Interaktive Installation (empfohlen)

```bash
./install.sh
```

Das Script führt dich durch alle Schritte, fragt deine Zugangsdaten ab, testet die Verbindung und schreibt die Konfiguration. Fertig in unter 2 Minuten.

**Nicht sicher?** Probiere erst die Simulation:

```bash
./install.sh --dry-run
```

Zeigt alles an, ändert nichts.

**Hilfe anzeigen:**

```bash
./install.sh --help
```

### 4. Manuelles Setup (für Experten)

Wer lieber per Hand konfigurieren möchte:

```bash
mkdir -p ~/.hermes/hermes-agent/plugins/platforms/rocketchat
cp plugin.yaml __init__.py adapter.py \
  ~/.hermes/hermes-agent/plugins/platforms/rocketchat/
```

Dann `~/.hermes/.env` oder `config.yaml` bearbeiten.

### 5. Konfigurieren

Falls du manuell konfigurierst, hier die zwei Varianten:

**Variante A — Umgebungsvariablen:**
export ROCKETCHAT_BASE_URL="https://rocketchat.example.com"
export ROCKETCHAT_USER="bernd"
export ROCKETCHAT_PASSWORD="dein-passwort"
export ROCKETCHAT_ROOM_ID="J3jvMyrKTMzKvKHSh"      # optional
export ROCKETCHAT_ALLOWED_USERS="andreas,max"       # optional
export ROCKETCHAT_ALLOW_ALL_USERS="false"           # default
```

**Variante B — `config.yaml`:**

```yaml
plugins:
  platforms:
    rocketchat:
      enabled: true
      base_url: "https://rocketchat.example.com"
      user: "bernd"
      password: "dein-passwort"
      room_id: "J3jvMyrKTMzKvKHSh"
      allowed_users: ["andreas", "max"]
      allow_all_users: false
```

### 4. Starten

```bash
hermes gateway start
```

Hermes Agent verbindet sich automatisch mit Rocket.Chat und erscheint als Online-Benutzer.

---

## Architektur

```
┌─────────────┐      DDP/WebSocket      ┌─────────────────┐
│ Hermes Agent│  ◄────────────────────► │  Rocket.Chat    │
│  (Plugin)   │                         │   Server        │
│             │      REST API           │                 │
│             │  ─────────────────────► │  (v5+)          │
└─────────────┘                         └─────────────────┘
```

- **Adapter.py** (~20 k LOC): DDP-Client, Session-Handling, Nachrichten-Parsing, Button-Rendering
- **__init__.py**: Plugin-Registrierung, Template-Definitionen für Buttons
- **plugin.yaml**: Metadaten, Env-Vars, Dependency-Check

---

## Button-Templates

Das Plugin bringt vordefinierte Interaktionen mit — kein YAML, keine Extra-Config:

| Template | Nutzung |
|----------|---------|
| `yes_no` | ✅ Ja / ❌ Nein |
| `confirm_cancel` | ✅ Bestätigen / 🚫 Abbrechen |
| `ok` | 👍 OK |
| `multi_choice_3` | 1. Links / 2. Rechts / 3. Zwei Runden |

Custom-Buttons werden aus reinen Label-Strings generiert (Rocket.Chat schneidet nach ~11–12 Zeichen ab — daher kurze Labels mit Emoji).

---

## Aktueller Status

- **Version**: 1.0.0
- **Stabilität**: Produktiv im Einsatz (seit Mai 2026)
- **Getestet mit**: Rocket.Chat v5.x, Hermes Agent Gateway
- **Lizenz**: [Unlicense](LICENSE) — Public Domain

---

## Roadmap / Offen

- [ ] OAuth / Token-Auth neben Passwort-Login
- [ ] Threading-Unterstützung für Kanäle
- [ ] Datei-Upload (Bilder, Dokumente)
- [ ] Slash-Command-Integration auf Rocket.Chat-Seite
- [ ] Mehrsprachige Button-Templates

---

## Mitmachen

Da das Plugin reines Python und nur Standardbibliothek nutzt, ist der Einstieg niedrig:

1. Repo clonen
2. `adapter.py` bearbeiten
3. Testen mit `hermes gateway start --debug`
4. Pull Request oder Patch schicken

Kein Build-Step, keine Node-Dependencies, kein Docker nötig.

---

## Links

- **Hermes Agent**: https://hermes-agent.nousresearch.com/
- **Rocket.Chat**: https://www.rocket.chat/
- **Dieses Repo**: `https://gitea.thomander.de/andreas/Hermes_rocket.chat_Plugin`

---

> *Erstellt von der Hermes Agent Community — für die Rocket.Chat Community.*