ClawdDotNet/docs/RocketChat-Nextcloud-Konzept.md

Rocket.Chat und Nextcloud — Konzept

Zwei neue Tools, ein gemeinsamer Zweck: Rocket.Chat wird der Ort, an dem wir mit den Agenten reden; Nextcloud wird der Ort, an dem die Agenten uns Ergebnisse hinlegen. Der typische Ablauf ist die Kombination aus beidem — „schreib mir die Auswertung und leg sie in die Cloud" im Chat, Datei in Nextcloud, Link zurück in den Chat.

Dieses Dokument prüft die Machbarkeit, legt den Schnitt fest und benennt die Punkte, die vor der Umsetzung entschieden werden müssen.

Stand 2026-08-23: Der Rocket.Chat-Teil ist umgesetzt — src/ClawdDotNet.Tools.RocketChat, im AppHost registriert, send_file freigabepflichtig. Der Befund unten bleibt als Begründung stehen; Abschnitt 2.0 hält fest, was die Messung gegen die echte Instanz an den Annahmen korrigiert hat. Offen: der Nextcloud-Teil und die Kollision mit Roadmap A5 (Matrix) — die ist eine Entscheidung, keine Umsetzung.

Verwandt: Taskboard-Konzept (Scanner/Wake), Staging-Konzept (Freigaben), Audit-Konzept, Roadmap (A5 — siehe Konflikt unten).

---

0 — Kurzfassung des Befunds

Frage	Antwort
Ist es umsetzbar?	Ja, beides. Ohne neue Architektur — die vorhandenen Bausteine tragen.
Braucht es Änderungen am Core?	Für Phase 1: nein, nur zwei neue Tool-Projekte + Staging-Defaults. Für den automatischen Rückweg (Antwort landet ohne Zutun des Modells im Raum) und den Notfallkanal: ja, zwei kleine Core-Ergänzungen.
Größtes technisches Risiko	Nicht die API — sondern Antwort-Schleifen zwischen Agenten und Kosten durch zu häufiges Wecken.
Größte Konzeptkollision	Roadmap A5 sieht Matrix/Element für genau diesen Zweck vor. Rocket.Chat ersetzt A5, oder wir haben zwei Chat-Wege. Muss entschieden werden.
„Agent erstellt Dokument direkt über die Nextcloud-API"	So nicht. Nextcloud hat keine API, die Inhalte erzeugt. Der Weg ist: Datei lokal im Workspace erzeugen → hochladen. Für PDF/XLSX kann Collabora als Konverter dienen — das ist der elegante Teil, siehe 5.4.

---

1 — Was schon da ist (und deshalb nicht neu gebaut wird)

Der Rückkanal von außen nach innen existiert vollständig:

TaskScanner (60-s-Takt)
   └─ Task vom Typ tool_job
        └─ EngineTaskDispatcher.DispatchToolJobAsync
             └─ IToolJobProvider.ExecuteJobAsync   ← kein LLM, kostenlos
                  └─ ToolJobResult.Wake(text)      ← nur wenn wirklich etwas da ist
                       └─ AgentEngine.ChatAsync    ← hier erst kostet es Tokens

Das Telegram-Tool nutzt genau das (telegram_poll). Rocket.Chat bekommt dieselbe Bauform — rocketchat_poll. Damit gilt automatisch:

• Zustand (letzter gesehener Zeitpunkt) über IStateStore, überlebt Neustarts.
• Ein Takt ohne neue Nachricht kostet nichts.
• Kein eigener Thread, kein eigener Scheduler, keine Sonderbehandlung beim Start.
• Jeder Tool-Aufruf läuft ohnehin durch StagingGate (A2) und Audit (A3).

Ebenso vorhanden und wiederverwendbar:

• Pro-Agent-Konfiguration (AgentConfig.Tools["RocketChat"]) — jeder Agent bekommt seine eigenen Zugangsdaten, ohne dass ein Agent die eines anderen sehen kann.
• ConfigSecrets verschlüsselt Felder nach Namen (token, password, apikey …) — ein Feld namens authToken bzw. appPassword ist automatisch geschützt.
• Workspace-Prefixe personal: / shared: samt Path-Traversal-Prüfung — aus dem FTP-Tool wortgleich übernehmbar für Nextcloud-Uploads.

---

2 — Rocket.Chat: Machbarkeit

Geprüft gegen die REST- und Realtime-API von Rocket.Chat. Alles Folgende ist Standardfunktion einer selbstgehosteten Instanz, kein Enterprise-Feature.

2.0 Prüfung gegen die echte Instanz (Rocket.Chat 8.7, August 2026)

Alles unten Stehende wurde gegen die Testinstanz gemessen, nicht aus der Dokumentation übernommen. Drei Annahmen waren falsch — sie sind hier korrigiert.

Bestätigt:

Prüfung	Ergebnis
subscriptions.get als Sammelabruf	liefert je Raum rid, t, name, unread, userMentions, groupMentions, alert — genau der Vorfilter, auf dem der Poll steht
chat.postMessage, auch mit tmid (Thread)	funktioniert
channels.history / groups.history / im.history mit oldest	funktioniert; Raumart bestimmt den Endpunkt
subscriptions.read	funktioniert; danach steht ls und unread fällt auf 0
im.create, groups.create, Senden in privaten Gruppen	funktioniert
Erwähnungen	kommen als mentions[]-Feld mit Benutzernamen — der Erwähnungsfilter braucht kein Textparsen
Unbekannter Raum	400 [invalid-channel]
users.create mit Rolle bot	funktioniert (Admin)

Korrekturen:

1. Berechtigungsnamen. Sie heißen create-personal-access-tokens (Rollen: admin, user) und user-generate-access-token (Rolle: admin) — nicht wie zuvor notiert.
2. Ein Admin kann kein Token für einen fremden Benutzer prägen. users.generatePersonalAccessToken lehnt userId ab („must NOT have additional properties") — der Endpunkt gilt nur für den aufrufenden Benutzer. users.createToken verlangt ein secret, für das es in dieser Instanz keine Einstellung gibt. Beide Wege sind zu.
3. Systemnachrichten. Die Historie liefert auch Ereignisse wie „Benutzer beigetreten" (Feld t, z. B. uj). Ohne Filter antwortet ein Agent auf einen Raumbeitritt. Im Tool umgesetzt und geprüft.

Offen geblieben: Das Ratenlimit (API_Enable_Rate_Limiter = an, 10 Aufrufe/60 s) griff bei 14 schnellen Aufrufen nicht — Administratoren umgehen es. Für einen Benutzer mit reiner bot-Rolle ist es damit nicht gemessen. Der Entwurf bleibt mit einem Sammelabruf je Takt weit darunter; nachzumessen, sobald ein Agenten-Benutzer nutzbar ist.

2.0.1 Der Stolperstein: 2FA verhindert die automatische Bereitstellung

Ein frisch per API angelegter Benutzer kann sich nicht anmelden: Rocket.Chat antwortet mit totp-required und schickt einen Code per E-Mail. Ursache ist Accounts_TwoFactorAuthentication_By_Email_Auto_Opt_In (in der Testinstanz aktiv) — jeder neue Benutzer bekommt E-Mail-2FA automatisch.

Geprüft und ausgeschlossen: users.update kennt kein Feld dafür („must NOT have additional properties"), users.resetTOTP betrifft nur App-basiertes TOTP. Es gibt keinen Weg über die Admin-API, das E-Mail-2FA eines einzelnen Benutzers abzuschalten.

Damit stehen drei Wege offen — die Entscheidung gehört dir, weil sie eine Sicherheitseinstellung berührt:

Weg	Ablauf	Preis
A (empfohlen)	Auto_Opt_In global auf aus, dann Benutzer anlegen (Rollen bot + user), als dieser anmelden, PAT erzeugen, Passwort verwerfen	Neue menschliche Benutzer bekommen E-Mail-2FA dann nicht mehr automatisch. Bestehende Konten und TOTP bleiben unberührt
B	Setting bleibt; jeder Agent braucht ein echtes Postfach, ClawdDotNet holt den 2FA-Code per IMAP (das Mail-Tool kann das)	Funktioniert, ist aber ein zerbrechlicher Umweg
C	Halbautomatisch: API legt den Benutzer an, ein Mensch erzeugt das PAT einmalig in der Oberfläche	Kein „HR-Agent" möglich — bei jedem neuen Agenten Handarbeit

Weg A ist umgesetzt und gemessen (August 2026): Nach dem Abschalten von Auto_Opt_In läuft die Kette vollständig durch —

users.create (Rollen bot + user)  →  login als dieser Benutzer  →
users.generatePersonalAccessToken  →  PAT

Damit ist ein „HR-Agent", der einen neuen Agenten samt Chat-Konto einrichtet, technisch möglich. Die Rolle user ist dabei nötig, nicht nur bot: Nur sie bringt die Berechtigung create-personal-access-tokens mit.

Ein Benutzer, der vor der Umstellung angelegt wurde, behält sein 2FA-Flag dauerhaft — er lässt sich nicht nachträglich retten und muss neu angelegt werden.

Ob sich Auto_Opt_In nach der Bereitstellung wieder einschalten lässt, ohne die bestehenden Agenten zu verlieren, ist plausibel (das Flag wird beim Anlegen gesetzt), aber weiterhin nicht gemessen.

Für das Tool selbst ist die Frage folgenlos: Es nimmt userId und authToken aus der Konfiguration entgegen, gleich woher sie stammen.

2.0.2 Zwei Fehler, die erst der Live-Test zeigte

Beide wären in keinem Schreibtischtest aufgefallen und sind behoben:

1. unread zählt in dieser Instanz nur Erwähnungen. Eine gewöhnliche Nachricht setzt allein alert=true. Schwerer wiegt: userMentions ist ein Zähler über ungelesene Erwähnungen und bleibt stehen, solange nichts gelesen wurde. Ein einziger alter, ungelesener Ruf machte den Raum damit dauerhaft „heiß" — und anschließend wurde jede weitere Nachricht ausgeliefert, auch ohne Erwähnung. Behoben: Die Erwähnungsprüfung sitzt jetzt an der einzelnen Nachricht; der Raum-Zähler ist nur noch ein billiger Vorfilter. Zusätzlich wird jeder geprüfte Raum als gelesen markiert, auch wenn nichts zu wecken war — sonst veralten die Zähler.
2. Die Startmarke verschluckte die erste echte Nachricht. Ein Raum wird erst dann zum Kandidaten, wenn Verkehr da ist — genau dann setzte der alte Code aber „Marke auf jetzt, nichts wecken". Die auslösende Nachricht ging verloren. Behoben: Beim ersten Abruf eines Raums wird begrenzt zurückgeschaut (initialLookbackMinutes, Standard 5) statt zu überspringen.

2.1 Identität — ein echter Benutzer je Agent

Die Anforderung „jeder Agent mit eigenem Benutzer, in Gruppen und im Direktkontakt" ist der richtige Ansatz und wird von Rocket.Chat direkt unterstützt.

• Admin legt je Agent einen Benutzer an: POST /api/v1/users.create ({ name, username, email, password, roles: ["bot"] }).
• Die Rolle bot ist wichtig: Sie markiert den Benutzer als Maschine (relevant für Schleifenschutz, siehe 2.5) und wird in neueren Versionen bei der Sitzplatzzählung nicht als normaler Nutzer gewertet. Gegen die eigene Version zu prüfen.
• Für jeden Agenten wird ein Personal Access Token erzeugt (POST /api/v1/users.generatePersonalAccessToken, oder im Konto des Benutzers). Dauerhaft gültig, einzeln widerrufbar — deutlich besser als Login mit Passwort, weil kein Session-Ablauf und keine gespeicherten Passwörter im Spiel sind.
• Authentifiziert wird jeder Aufruf über zwei Header: X-Auth-Token und X-User-Id.

Entscheidung, die ich empfehle: Das Anlegen der Benutzer ist kein Agenten-Tool. Es ist eine einmalige Einrichtungsfunktion in der Oberfläche (Instanz-Einstellungen → Rocket.Chat → „Agenten-Benutzer anlegen"). Sonst müsste ein Agent ein Admin-Token halten — und ein Admin-Token in Reichweite einer Prompt-Injection ist genau das, was A2 verhindern soll. Der Admin-Token liegt in der Instanz-Konfiguration, nicht in einer Agenten-Tool-Konfiguration.

2.2 Ausgang — Nachrichten senden

Zweck	Endpunkt
In Kanal/Gruppe/DM schreiben	POST /api/v1/chat.postMessage (roomId oder channel)
Auf eine Nachricht antworten (Thread)	dasselbe, mit tmid
Datei anhängen	POST /api/v1/rooms.upload/{roomId} (multipart)
Reaktion setzen	POST /api/v1/chat.react

Gesendet wird als der Agenten-Benutzer — Direktnachrichten funktionieren dadurch echt und nicht als „Bot mit Alias".

2.3 Eingang — der Poll-Weg (Phase 1)

Der sparsame Weg, ohne jede neue Infrastruktur:

1. GET /api/v1/subscriptions.get?updatedSince=<zeitstempel> — ein einziger Aufruf liefert für diesen Agenten alle Räume mit Ungelesen-Zähler, Erwähnungs-Zähler und „zuletzt gesehen"-Marke. Auch bei 50 Räumen bleibt es ein Aufruf.
2. Nur für Räume mit relevanten Neuigkeiten wird die Historie geholt: channels.history (öffentlich) / groups.history (privat) / im.history (DM), jeweils mit oldest=<letzte gesehene Zeit>.
3. POST /api/v1/subscriptions.read markiert gelesen — der Zähler geht zurück auf null.

Zustand im IStateStore: rocketchat:{agentId}:lastCheck sowie je Raum die zuletzt verarbeitete Nachrichtenzeit.

Rate-Limits: Rocket.Chat begrenzt REST-Aufrufe (Standard in der Größenordnung von 10 Aufrufen je Minute und Endpunkt). Bei einem Takt von 30–60 Sekunden und einem Sammelaufruf pro Takt ist das unkritisch — es ist aber der Grund, warum der Entwurf über subscriptions.get sammelt statt jeden Raum einzeln zu pollen.

Latenz: Bei 60-Sekunden-Takt antwortet ein Agent im Mittel nach ~30 s plus Laufzeit. Für Gespräche mit Agenten ist das spürbar, aber tragbar. Der Takt lässt sich pro Job setzen (*/1 * * * * ist das Minimum des Cron-Modells; feiner ginge nur über die Realtime-API).

2.4 Eingang — die Realtime-Variante (Phase 3, optional)

Rocket.Chat bietet eine WebSocket-/DDP-Schnittstelle (wss://host/websocket): nach login mit dem Token abonniert man stream-notify-user/{userId}/notification und bekommt DMs und Erwähnungen sofort gepusht, ohne Polling.

Das ist die richtige Endstufe (Antwortzeit ~1 s statt ~30 s), aber es ist eine dauerhafte Verbindung je Agent mit Wiederverbindungs-Logik — also eine echte Komponente, keine Ergänzung eines Tools. Vorschlag: erst nachrüsten, wenn Phase 1 im Alltag steht und sich die Verzögerung tatsächlich stört.

Eine dritte Möglichkeit — Rocket.Chats Outgoing Webhook auf unsere vorhandene ClawdDotNetApi (Port 5082) — wäre die einfachste Push-Lösung, setzt aber voraus, dass der Rocket.Chat-Server den Windows-Rechner über das Netz erreicht. Das ist eine Frage deiner Netztopologie und keine der Software. Falls erreichbar: der kürzeste Weg zu niedriger Latenz.

2.5 Die zwei echten Fallen

Diese beiden Punkte sind wichtiger als jede API-Frage.

(a) Mehrere Agenten im selben Raum. Wenn drei Agenten denselben Gruppenchat pollen, antworten drei Agenten auf jede Nachricht. Regel im Entwurf:

Ein Agent wird nur geweckt bei (1) Direktnachrichten an ihn oder (2) Nachrichten, die ihn per @name erwähnen. Alles andere liest er nicht einmal.

Ein Raum kann per Konfiguration auf respondToAll: true gestellt werden — das ist die bewusste Ausnahme für einen Raum mit genau einem Agenten.

(b) Agenten-Schleifen. Agent A schreibt, Agent B wird geweckt, antwortet, weckt A — und das läuft, bis das Tagesbudget greift. Der LoopGuard schützt nur innerhalb eines Laufs, nicht über Agenten hinweg. Regel im Entwurf:

Nachrichten von Benutzern mit der Rolle bot werden ignoriert, außer der Agent ist namentlich erwähnt. Zusätzlich eine Drossel: höchstens N Weckvorgänge je Raum und Stunde (Zähler im IStateStore), danach schweigt der Agent in diesem Raum bis zur nächsten Stunde und protokolliert das.

Das Tagesbudget (K5) ist das letzte Netz, nicht das erste.

2.6 Der Rückweg der Antwort

Der Wake-Mechanismus liefert die Nachricht in den Agenten. Seine Antwort geht heute in den Chat-Verlauf, nicht zurück nach Rocket.Chat. Zwei Wege:

• (a) Der Agent antwortet selbst — die Weck-Nachricht enthält die roomId und die Anweisung, mit RocketChat.send_message zu antworten. Kein Core-Eingriff, funktioniert sofort. Schwäche: Es hängt daran, dass das Modell es tut. Erfahrungsgemäß klappt das gut, aber nicht in 100 % der Fälle.
• (b) Automatischer Rückweg — der Tool-Job merkt sich „Antwort gehört nach Raum X", und der Dispatcher schickt die Abschlussnachricht des Laufs dorthin. Zuverlässig, aber es braucht einen kleinen Haken in ToolJobResult/EngineTaskDispatcher (etwa ein ReplyTo-Feld, das der Dispatcher nach dem Lauf an dasselbe Tool zurückgibt).

Empfehlung: (a) in Phase 1, (b) in Phase 2 nachziehen — denn (b) ist der Unterschied zwischen „meistens antwortet er" und „er antwortet". Für die Hauptkommunikationsschiene ist das am Ende nicht optional.

2.7 Sicherheit

• Nachrichten aus Rocket.Chat sind fremder Text. Sie müssen als <untrusted_content> gerahmt in den Kontext (Roadmap K2-Rest). Bei Telegram fehlt das bis heute; hier sollte es von Anfang an drin sein, weil Gruppenchats mehrere Absender haben.
• Raum-Allowlist je Agent (allowedRooms), analog allowedChatIds beim Telegram-Tool.
• Staging-Vorschlag (siehe 6): Senden in erlaubte Räume auto, alles darüber hinaus approve.
• Zugangsdaten heißen im Konfigurationsfeld authToken → ConfigSecrets verschlüsselt sie automatisch. Der Admin-Token der Instanz muss in ConfigSecrets.Apply(InstanceConfig) ergänzt werden.
• TLS ist Pflicht; selbstsignierte Zertifikate ausdrücklich konfigurieren müssen statt Validierung generell abschalten.

2.8 Tool-Zuschnitt

Umgesetzt (src/ClawdDotNet.Tools.RocketChat, gegen die Testinstanz geprüft):

Tool: RocketChat
Aktionen: send_message | reply | send_file | list_rooms | read_room | mark_read
Job:      rocketchat_poll

Noch nicht umgesetzt: search.

Dateiversand. send_file schickt eine Datei aus dem Workspace direkt in einen Raum oder als Direktnachricht — der kurze Weg für „stell mir das zusammen und schick es rüber", ohne Umweg über die Cloud. Pfade tragen dieselben Prefixe wie bei FileRW und FTP (personal: / shared: / ohne Prefix), samt Prüfung gegen einen Ausbruch aus dem Verzeichnis. Grenze über maxUploadMb (Standard 25, Serverseite erlaubt 100).

Dabei zeigte sich die dritte Doku-Korrektur: Der Ein-Schritt-Endpunkt rooms.upload existiert in 8.7 nicht mehr — er antwortet mit einem nackten HTML-404. Aktuell ist ein zweistufiger Ablauf:

1. rooms.media/:rid nimmt die Datei als multipart/form-data und liefert eine Datei-Id; sichtbar ist damit noch nichts.
2. rooms.mediaConfirm/:rid/:fileId veröffentlicht sie als Nachricht.

Ohne den zweiten Schritt liegt die Datei hochgeladen, aber unsichtbar auf dem Server. Voraussetzung ist damit Rocket.Chat 6.x oder neuer; einen Rückfall auf rooms.upload für ältere Instanzen gibt es bewusst nicht, weil er sich hier nicht prüfen ließe.

Anders als send_message steht RocketChat.send_file in der Staging-Policy auf approve: Eine Nachricht formuliert der Agent, eine Datei verlässt den Workspace als Ganzes. Wer das im Alltag als zu hinderlich empfindet, streicht die eine Zeile in StagingPolicy.DefaultRules — dann schützt weiterhin die Raum-Allowlist.

Geprüft gegen die Testinstanz (8 von 8): Markdown aus dem persönlichen Workspace · CSV aus dem geteilten mit abweichendem Dateinamen · Datei per Direktnachricht · Ausbruchsversuch ../ abgewiesen · absoluter Pfad abgewiesen · fehlende Datei · fehlender localPath · nicht freigegebener Raum.

2.9 Eingehende Dateien und Links

Was hereinkommt, ist genauso wichtig wie das, was hinausgeht — und stand anfangs nicht im Entwurf.

Dateien. Eine Dateisendung trägt den Begleittext in msg, die Datei selbst aber daneben in files[]. Wer nur msg liest, sieht bei einer reinen Dateisendung einen leeren Beitrag. Weckmeldung und read_room führen Anhänge deshalb eigens auf:

[20:06] @richard (messageId: rD68…): schau dir die Zahlen bitte an.
    Datei: auswertung.csv (text/csv, 77 B) — fileId: 6a821828ea0ad1bcab878f74

Mit dieser fileId holt download_file die Datei in den Workspace. Der Abruf geht gegen /file-upload/{fileId}/download mit denselben Kopfzeilen wie die API — ohne sie antwortet der Server mit 403 (FileUpload_ProtectFiles ist aktiv).

Schutzmaßnahmen, weil Name und Inhalt vom Absender bestimmt sind:

• Der Zielname wird auf den reinen Dateinamen reduziert; Pfadangaben darin verfallen. Nur das Verzeichnis (personal: / shared:) darf der Agent wählen.
• Ausführbare Endungen (.exe, .ps1, .bat, .jar, …) werden abgelehnt, sofern nicht allowDangerousDownloads gesetzt ist.
• Größengrenze maxDownloadMb (Standard 25) — geprüft an Content-Length und während des Schreibens, da die Angabe fehlen darf.
• Geschrieben wird über eine .part-Nebendatei; bricht der Abruf ab, bleibt keine halbe Datei liegen, die der Agent für vollständig hält.

Dabei fiel ein Windows-Fehler auf, der leicht zu übersehen ist: Path.GetFileName behält "shared:kopie.csv" unverändert bei, weil : dort kein Pfadtrenner ist, sondern ein NTFS-Alternativdatenstrom eingeleitet wird. Die Datei landete als Datenstrom am Verzeichnis statt als eigene Datei. Der Präfix wird jetzt vor der Namensbereinigung abgetrennt, und WorkspaceFile weist Doppelpunkte grundsätzlich ab.

Links. Rocket.Chat entpackt Links selbst und legt in urls[].meta Titel und Beschreibung der Zielseite ab. Der Agent bekommt das mitgeliefert:

    Link: https://www.rocket.chat/ — Rocket.Chat | Secure CommsOS™ …

Das erspart oft einen eigenen Seitenabruf. Wichtig: Diese Vorschau ist Text der verlinkten Seite, also fremdbestimmt — sie steht deshalb wie alles andere innerhalb der <untrusted_content>-Rahmung. Ein tatsächlicher Abruf der Seite bleibt Sache des WebFetch-Tools und damit eine bewusste Entscheidung des Agenten, keine Nebenwirkung des Empfangens.

Geprüft (9 von 9): Datei in der Weckmeldung samt fileId · Link mit Titel · Download in den persönlichen und in den geteilten Workspace · Inhalt stimmt · Ausbruch über den Dateinamen entschärft · gefährliche Endung abgelehnt · unbekannte fileId · fehlende fileId.

Der Weckpfad ist gegen die Testinstanz durchgespielt (6 von 6 Erwartungen): ruhiger Takt weckt nicht · Nachricht ohne Erwähnung weckt nicht · Erwähnung weckt · Direktnachricht weckt auch ohne Erwähnung · eigene Nachricht weckt nicht · private Gruppe weckt.

Konfiguration je Agent:

"RocketChat": {
  "baseUrl": "https://chat.example.org",
  "userId": "aBcD…",
  "authToken": "…",              // von ConfigSecrets geschützt (Schlüssel "authtoken")
  "username": "agent-hermes",    // für den Erwähnungsfilter
  "allowedRooms": ["GENERAL", "finanz-team", "richard"],
  "defaultRoom": "finanz-team",
  "mentionOnly": true,
  "agentUsernames": ["agent-hermes", "agent-atlas"],
  "maxWakesPerRoomPerHour": 12,
  "maxMessagesPerRoom": 20,
  "initialLookbackMinutes": 5,
  "maxUploadMb": 25
}

allowedRooms gilt auch für Direktnachrichten. Ein DM-Raum trägt den Namen des Gegenübers — wer per DM erreichbar sein soll, steht dort mit seinem Benutzernamen (oben "richard"). Ohne Eintrag ignoriert der Agent die Direktnachricht. Eine leere Liste erlaubt alles; das Tool erfindet keine Allowlist.

Mit "@benutzername" als room beginnt der Agent auch ein neues Gespräch (im.create) — nur bei ausdrücklicher @-Schreibweise, damit ein vertippter Kanalname nicht stillschweigend zur Direktnachricht wird.

Zum Verhalten des Abrufs:

• Erster Takt je Raum setzt nur die Marke und weckt nicht — sonst käme beim Einrichten die gesamte Raumgeschichte auf einmal in den Kontext.
• Die Marke wandert auf die jüngste gesehene Nachricht, auch auf gefilterte. Sonst würde eine ignorierte Agentennachricht bei jedem Takt erneut geprüft.
• Gelesen-Markierung erst nach dem Einsammeln — bricht der Takt vorher ab, bleibt der Zähler stehen und nichts geht verloren.
• Der Schleifenschutz vergleicht gegen agentUsernames, nicht gegen ein Server-Flag: Wir wissen selbst am besten, welche Konten unsere Agenten sind.
• Kein Eintrag in der Staging-Policy — RocketChat.send_message bleibt bewusst auto (Standard). Der Schutz sitzt an allowedRooms, nicht an einer Einzelfreigabe.

---

3 — Redundanz: was passiert, wenn Rocket.Chat ausfällt

Das ist die Anforderung, die die Architektur bestimmt — nicht der Chat selbst. Der Kern: Rocket.Chat darf ein Kanal sein, nicht der Kanal.

3.1 Was heute schon unabhängig funktioniert

Kanal	Unabhängig von Rocket.Chat?	Richtung
Chat-Seite in der App (ChatPageView)	vollständig — läuft in der App selbst	beide
Telegram-Bot-Tool	ja — fremde Infrastruktur	beide
Mail-Tool	ja, sofern der Mailserver anderswo läuft	beide
Web-Chat / ClawdDotNetApi	ja, aber nur im lokalen Netz	beide

Wir sind also nicht bei null. Was fehlt, ist die Umschaltung — heute muss ein Mensch merken, dass nichts mehr ankommt.

3.2 Vorschlag: ChannelRouter im Core

Eine kleine Komponente im Core (kein neues Tool, keine Tool-zu-Tool-Abhängigkeit — sie löst Tools über die vorhandene ToolRegistry nach Namen auf, wie es der Dispatcher schon tut):

• Je Agent eine geordnete Kanalliste, z. B. ["RocketChat", "Telegram", "Mail"].
• Eine Methode „stelle dem Menschen diese Nachricht zu": versucht der Reihe nach, bis einer erfolgreich ist, und protokolliert im Audit-Log, über welchen Kanal zugestellt wurde — inklusive des Hinweises „Primärkanal war nicht erreichbar".
• Genutzt von: Agenten (notify_user), aber vor allem von systemseitigen Meldungen, die heute keinen Weg nach außen haben: Staging-Vorschlag wartet auf Freigabe, Budget überschritten, Watchdog-Alarm, Task blockiert.

Der zweite Teil ist der wichtigere: Gerade wenn etwas kaputt ist, ist die Meldung darüber diejenige, die ankommen muss.

3.3 Gesundheitsprüfung und Eskalation

Ein Tool-Job rocketchat_health (Takt ~5 Minuten, GET /api/info):

• Nach drei aufeinanderfolgenden Fehlschlägen: einmalige Meldung über den nächsten Kanal der Liste — „Rocket.Chat ist seit HH:MM nicht erreichbar, ich melde mich hier." Einmalig, nicht je Takt.
• Bei Rückkehr: „Rocket.Chat ist wieder da", und der Zustand wird zurückgesetzt.
• Nachrichten, die während des Ausfalls nicht gesendet werden konnten, werden nicht in einer eigenen Warteschlange gehalten — sie gehen über den Ersatzkanal raus. Eine zweite Zustellwarteschlange wäre eine zweite Fehlerquelle.

Eingehend während des Ausfalls: Der Telegram-Poll-Job bleibt dauerhaft aktiv, nur mit langsamem Takt (z. B. alle 5 Minuten). Er kostet nichts, wenn nichts kommt — und ist im Ernstfall der Weg, auf dem du die Agenten erreichst. Die eingebaute Chat-Seite ist ohnehin immer da, solange die App läuft.

Entschieden (August 2026): Telegram ist der Notfallkanal. Die Kanalliste lautet damit ["RocketChat", "Telegram"]. Konsequenzen:

• Das Telegram-Tool wird nicht abgebaut und geht nicht in Rocket.Chat auf. Es behält seine Rolle, verliert aber die Rolle als Alltagskanal.
• Telegram.send_message bleibt in der Staging-Policy auf approve — mit einer Ausnahme: Meldungen, die der ChannelRouter selbst erzeugt (Ausfall, Budget, Watchdog, offene Freigabe), laufen ohne Freigabe. Sonst bliebe die Warnung, dass eine Freigabe aussteht, selbst in der Freigabewarteschlange hängen — ein Ringschluss, der genau im Ernstfall zuschlägt.
• Der Telegram-Poll bleibt dauerhaft eingerichtet, aber mit langsamem Takt. Ein Kanal, der erst im Notfall eingeschaltet wird, ist im Notfall ungetestet.
• Mail bleibt außen vor. Zwei Ersatzkanäle zu pflegen lohnt nicht; das Mail-Tool behält seinen fachlichen Zweck.

3.4 Was das für die Prompts heißt

Ein Agent soll seinen Kanal nicht selbst wählen. Er sagt „ich möchte dem Nutzer das hier mitteilen", der Router entscheidet. Sonst muss das Modell im Fehlerfall improvisieren — und genau dann ist Improvisation das Letzte, was man will.

---

4 — Konflikt mit Roadmap A5 (Matrix)

Roadmap-Punkt A5 legt fest: „Die Kommunikation (Benachrichtigungen, Berichte, Chat mit Agenten) wird auf Element/Matrix umgestellt", und der gestrichene Tool-Kandidat Notify geht darin auf.

Rocket.Chat besetzt exakt dieselbe Rolle. Drei mögliche Auflösungen:

1. Rocket.Chat ersetzt A5. A5 wird umgeschrieben, Matrix entfällt. Vorteil: eine Schiene, ein Betriebsaufwand, die Instanz läuft bereits.
2. A5 bleibt, Rocket.Chat ist nur ein weiteres Tool. Dann bauen wir zweimal dasselbe. Schwer zu begründen.
3. Rocket.Chat primär, Matrix als späterer Zweitkanal. Passt formal zur Redundanz-Anforderung, verdoppelt aber den Wartungsaufwand für einen Fall, den Telegram schon abdeckt.

Meine Empfehlung: (1). Der ChannelRouter aus 3.2 ist ohnehin die Verallgemeinerung, die A5 gebraucht hätte — mit ihm ist ein späterer Matrix-Kanal ein zusätzlicher Eintrag in der Liste, keine Migration. Das ist eine Entscheidung für dich, keine technische Sachfrage.

---

5 — Nextcloud: Machbarkeit

5.1 Der Zugriffsweg

Nextcloud hat zwei Schnittstellen, beide brauchen wir:

Zweck	Schnittstelle
Dateien lesen/schreiben/auflisten/verschieben	WebDAV: /remote.php/dav/files/{benutzer}/{pfad}
Öffentlichen Link erzeugen	OCS: /ocs/v2.php/apps/files_sharing/api/v1/shares

Authentifiziert wird mit App-Passwörtern (Nextcloud → Einstellungen → Sicherheit → „Neues App-Passwort erstellen") per Basic-Auth. Ein App-Passwort ist einzeln widerrufbar und lässt das eigentliche Kontopasswort unangetastet — dieselbe Logik wie das Personal Access Token bei Rocket.Chat.

WebDAV braucht keine Bibliothek: HttpClient mit den Methoden PUT, GET, MKCOL, PROPFIND, MOVE, DELETE. Nur PROPFIND liefert XML (Multistatus), das geparst werden muss — überschaubar, und es erspart uns eine weitere Abhängigkeit.

5.2 Ein Benutzer je Agent — oder ein Sammelkonto?

Zwei Modelle:

• Je Agent ein Nextcloud-Benutzer. Sauber nachvollziehbar („wer hat das abgelegt"), passt zum Rocket.Chat-Modell, kostet je nach Lizenzmodell Nutzer.
• Ein Dienstkonto clawd-agents mit Unterordnern je Agent. Einfacher zu verwalten, Herkunft steht dann im Pfad statt im Konto.

Empfehlung: Ein Dienstkonto mit Ordnerstruktur /ClawdDotNet/{Agent}/…, plus einen mit dir geteilten Ordner /ClawdDotNet/Berichte/. Begründung: Bei Rocket.Chat ist die eigene Identität funktional zwingend (DMs, Erwähnungen), bei Dateien ist sie es nicht — und ein Ordnerbaum ist leichter aufzuräumen als zehn Konten. Falls du die Trennung dennoch willst, ändert das am Tool nichts, nur an der Konfiguration.

Die Ordnerdurchsetzung gehört ins Tool: eine konfigurierte rootPath, aus der der Agent nicht ausbrechen kann — dieselbe Prüfung wie in FTPTool.ResolveLocalPath.

5.3 Die ehrliche Antwort zu „direkt über die API erstellen"

Nextcloud hat keine API, die Dokumenteninhalte erzeugt. Es ist ein Dateiablage- und Freigabesystem; Collabora ist ein Editor im Browser (über WOPI angebunden), kein Generator, den man von außen mit „erstelle eine Tabelle mit diesen Zahlen" beauftragen kann.

Der tatsächliche Weg ist deshalb der, den du selbst schon beschrieben hast:

Agent erzeugt die Datei im eigenen Workspace   (FileRW-Tool, schon vorhanden)
   → Nextcloud.upload                          (WebDAV PUT)
   → Nextcloud.share  (optional)               (OCS, liefert Link)
   → RocketChat.send_message mit dem Link

Das ist kein Umweg, sondern die richtige Aufteilung: Der Agent kann seine Datei lokal prüfen und korrigieren, bevor sie irgendwo landet.

5.4 Formate — und wo Collabora doch nützlich wird

Was ein Agent von sich aus gut schreiben kann: Markdown (Nextcloud rendert .md direkt in der Weboberfläche — für Berichte oft die beste Wahl), CSV, HTML, JSON.

Was er nicht von sich aus schreiben kann: .xlsx, .docx, .pdf.

Hier gibt es einen eleganten Weg, weil du Collabora ohnehin betreibst: Collabora Online bringt einen Konvertierungs-Endpunkt mit (POST /cool/convert-to/{format}, multipart). Damit gilt:

Ziel	Weg
PDF	Agent schreibt HTML oder ODT → Collabora → PDF
XLSX	Agent schreibt CSV → Collabora → XLSX
DOCX	Agent schreibt HTML/ODT → Collabora → DOCX

Vorteil: keine zusätzliche PDF- oder Excel-Bibliothek im Projekt (und keine Lizenzfrage, die wir uns damit einhandeln — mehrere verbreitete .NET-Bibliotheken für XLSX und PDF sind für kommerzielle Nutzung nicht frei).

Zu prüfen, bevor wir darauf bauen:

• Ist der Endpunkt in deiner Collabora-Installation erreichbar? Er muss in coolwsd.xml für die IP des ClawdDotNet-Rechners freigegeben sein (net/post_allow-Allowlist). Standardmäßig ist das eng gefasst.
• Der Pfad heißt je nach Version /cool/convert-to/… (neu) oder /lool/convert-to/… (alt).

Falls der Endpunkt nicht freigegeben werden soll: Rückfallebene ist Markdown/CSV — für den Alltag völlig ausreichend, PDF wäre dann ein späterer eigener Punkt.

5.5 Freigabe-Links

POST /ocs/v2.php/apps/files_sharing/api/v1/shares (Header OCS-APIRequest: true), shareType=3 = öffentlicher Link. Optional password, expireDate, permissions=1 (nur lesen). Die Antwort enthält die fertige URL.

Zwei Hinweise:

• Manche Instanzen erzwingen Passwortschutz für öffentliche Links — dann muss das Tool ein Passwort mitgeben und zurückliefern.
• Ein öffentlicher Link ist irreversibel im Sinne von A2: Einmal geteilt, kann er weitergegeben worden sein, auch wenn man ihn danach löscht. Deshalb steht er unten in der Staging-Tabelle auf approve.

Innerhalb der eigenen Instanz ist die freundlichere Variante shareType=0 (an einen konkreten Nextcloud-Benutzer) — kein öffentlicher Link nötig, wenn du ohnehin ein Konto hast. Das sollte der Standard sein, öffentlich die Ausnahme.

5.6 Fallstricke

• Dateisperren (HTTP 423). Wenn du eine Datei gerade in Collabora offen hast, kann ein Upload auf dieselbe Datei scheitern. Das Tool muss 423 sauber melden statt kryptisch zu scheitern — und beim Überschreiben eines Berichts lieber einen neuen Dateinamen mit Zeitstempel vergeben.
• Überschreiben ist nicht destruktiv, solange die Versionierung aktiv ist (Nextcloud legt automatisch eine Vorversion an). Das ist der Grund, warum Nextcloud.upload unten auf auto steht, FTP.upload aber auf approve.
• Größenbegrenzung. Ein einfaches PUT reicht für Berichte problemlos; erst bei sehr großen Dateien bräuchte es den Chunked-Upload (/remote.php/dav/uploads/…). Für den angedachten Zweck (Berichte, Tabellen, PDFs) nicht nötig — und wenn doch, meldet der Server einen klaren Fehler.
• Quota. Ein Agent, der stündlich Berichte ablegt, füllt das Konto. Ein Aufräum-Task („Berichte älter als 90 Tage") gehört mittelfristig ins Taskboard.

5.7 Tool-Zuschnitt

Tool: Nextcloud
Aktionen: upload | download | list | mkdir | move | delete
          | share | unshare | convert   (convert nur falls Collabora freigegeben)

Konfiguration je Agent:

"Nextcloud": {
  "baseUrl": "https://cloud.example.org",
  "username": "clawd-agents",
  "appPassword": "…",             // von ConfigSecrets geschützt
  "rootPath": "/ClawdDotNet/Hermes",
  "allowPublicShares": false,
  "collaboraUrl": "https://collabora.example.org"
}

appPassword muss der Schlüsselliste in ConfigSecrets hinzugefügt werden — password allein greift nicht, weil dort auf ganze Feldnamen verglichen wird.

---

6 — Verzahnung mit Staging (A2) und Audit (A3)

Vorschlag für die StagingPolicy.DefaultRules:

Aktion	Standard	Begründung
RocketChat.send_message (erlaubter Raum)	auto	Sonst ist Chat unbenutzbar — jede Antwort bräuchte einen Klick
RocketChat.send_message (Raum nicht in allowedRooms)	deny	Wird vom Tool selbst abgewiesen, gar nicht erst vorgelegt
RocketChat.send_file	approve	Dateiabfluss in einen Chatraum
Nextcloud.upload, mkdir, move	auto	Versioniert, im eigenen Ordner, umkehrbar
Nextcloud.delete	approve	wie FileRW.delete
Nextcloud.share (an Benutzer)	auto	bleibt innerhalb der Instanz
Nextcloud.share (öffentlicher Link)	approve	nicht zurückholbar

Der Unterschied zu Telegram.send_message (heute approve) ist Absicht: Telegram ist ein Benachrichtigungskanal nach außen, Rocket.Chat ist der Arbeitsraum. Ein Arbeitsraum, in dem jede Antwort eine Freigabe braucht, ist kein Arbeitsraum. Der Schutz sitzt hier an der Raum-Allowlist statt an der Einzelfreigabe.

Für das Audit-Log entstehen keine Sonderfälle — die Tool-Aufrufe laufen ohnehin durch.

---

7 — Was dieses Konzept nicht vorsieht

Damit der Zuschnitt klar ist:

• Keine Rocket.Chat-App (Apps-Engine, TypeScript im Server) — wir bleiben Client.
• Keine Verwaltung von Rocket.Chat durch Agenten (Benutzer anlegen, Räume erstellen, Rechte vergeben). Das ist Admin-Arbeit in der Oberfläche.
• Keine Sprach-/Videofunktionen, keine Nextcloud Talk-Anbindung.
• Kein Ersatz für die eingebaute Chat-Seite — die bleibt und ist die unterste Rückfallebene.
• Keine Ende-zu-Ende-Verschlüsselung. Rocket.Chat kann das, aber verschlüsselte Räume sind über die REST-API nicht lesbar. Agenten arbeiten in unverschlüsselten Räumen — das ist eine bewusste Einschränkung, die du kennen solltest.

---

8 — Vorschlag für den Schnitt

Phase	Inhalt	Ergebnis
1	Nextcloud-Tool: upload/download/list/mkdir/move/delete/share	Agent kann Berichte ablegen und einen Link liefern
2	RocketChat-Tool: senden, lesen, rocketchat_poll-Job, Raum-Allowlist, Erwähnungsfilter, Schleifendrossel	Gespräch mit Agenten über Rocket.Chat, Antwort per Prompt
3	Automatischer Rückweg (ReplyTo in ToolJobResult)	Antwort landet zuverlässig im richtigen Raum/Thread
4	ChannelRouter + rocketchat_health + Eskalation	Der Notfallkanal — Ausfall wird erkannt und umschifft
5	Collabora-Konvertierung (PDF/XLSX)	Berichte in Büroformaten
6 (optional)	Realtime/DDP statt Polling	Antwortzeit ~1 s statt ~30 s

Nextcloud zuerst, weil es das kleinere, in sich abgeschlossene Stück ist und sofort Nutzen bringt — und weil es sich unabhängig vom Ausgang der A5-Entscheidung lohnt.

Phase 4 ist kein Nice-to-have: Ohne sie ist Rocket.Chat ein Einzelpunkt, dessen Ausfall niemand meldet. Sie sollte nicht hinter Phase 5 rutschen.

Zur Modell-Einstufung im Sinne der Roadmap: Phasen 1, 2 und 5 sind klar spezifizierbare Tool-Arbeit (4.6-tauglich). Phase 3 und 4 fassen Engine bzw. Zustellwege an und sollten mit vorheriger Festlegung der Invarianten und mit Tests gebaut werden.

---

9 — Offene Punkte für die Diskussion

1. A5/Matrix — ersetzt Rocket.Chat den Punkt, oder bleibt Matrix als Ziel bestehen? (Abschnitt 4; das entscheidet, ob der ChannelRouter Pflicht oder Kür ist.)
2. Nextcloud-Identität — ein Dienstkonto mit Ordnern je Agent (mein Vorschlag) oder je Agent ein eigener Nextcloud-Benutzer?
3. Rückweg der Antwort — reicht Phase 2 (Agent antwortet selbst) für den Anfang, oder soll Phase 3 direkt mitgebaut werden?
4. Notfallkanal — Telegram oder Mail? Entschieden: Telegram (siehe 3.3). Offen bleibt nur die Kleinigkeit, ob die Reihenfolge instanzweit gilt (mein Vorschlag) oder pro Agent einstellbar sein soll.
5. Collabora-Konvertierung — ist der convert-to-Endpunkt für den ClawdDotNet-Rechner freigebbar? Falls nein, bleibt es bei Markdown/CSV.
6. Versionen — welche Rocket.Chat- und welche Nextcloud-Version läuft bei dir? Einzelne Endpunkte und Rollennamen sind versionsabhängig; das prüfe ich vor der Umsetzung gegen deine Instanz statt gegen die Dokumentation.
7. Öffentliche Links — grundsätzlich erlauben (mit Freigabe) oder ganz sperren (allowPublicShares: false als harte Voreinstellung)?