# Portabilität: UNIVERSAL
# Version: 1.1.0
# Zuletzt validiert: 2026-02-08
# Nächste Prüfung: 2026-08-08

MESSAGES - Nachrichtensystem
============================

BESCHREIBUNG
Internes Nachrichtensystem für Kommunikation zwischen User,
System und Agenten. Erreichbar über CLI und Web-GUI.

Ohne --from wird automatisch der eingestempelte Partner verwendet.

CLI-BEFEHLE
-----------
bach msg list              Alle Nachrichten anzeigen
bach msg list --inbox      Nur Inbox
bach msg list --outbox     Nur Gesendete
bach msg list --limit 20   Mit Limit (Standard: 10)

bach msg inbox             Inbox anzeigen (Kurzform)
bach msg outbox            Outbox anzeigen (Kurzform)

bach msg unread            Ungelesene Nachrichten anzeigen
bach msg count             Nachrichtenzaehler

bach msg send <to> <text>  Nachricht senden (als user/aktiver Partner)
bach msg send <to> <text> --from <partner>  Von Partner senden

bach msg read <id>         Nachricht lesen (markiert als gelesen)
bach msg read <id> --ack   Lesen mit automatischer Lesebestaetigung

bach msg ping              Ungelesene Nachrichten AN mich anzeigen
bach msg ping --from <p>   Nachrichten an spezifischen Partner

bach msg watch             Polling-Modus: Auf neue Nachrichten warten (Ctrl+C)
bach msg watch --from <p>  Polling für spezifischen Partner

bach msg delete <id>       Nachricht(en) löschen
bach msg delete 1 2 3      Mehrere Nachrichten löschen
bach msg delete <id> --dry-run  Vorschau (ohne Änderung)

bach msg archive <id>      Nachricht(en) archivieren
bach msg archive 1 2 3     Mehrere Nachrichten archivieren
bach msg archive <id> --dry-run  Vorschau (ohne Änderung)

bach msg help              Hilfe anzeigen

MULTI-PARTNER-SUPPORT
---------------------
Partner senden mit eigener Identitaet:

  bach msg send user "Bericht fertig" --from gemini
  bach msg send user "Task erledigt" --from claude
  bach msg send user "Verarbeitung abgeschlossen" --from ollama

Logik:
  --from user    -> Nachricht in User OUTBOX (Standard)
  --from <other> -> Nachricht in User INBOX (unread)

Partner-Identitaeten:
  user      User (Mensch)
  claude    Claude (Operating AI)
  gemini    Gemini (External AI via Antigravity)
  ollama    Ollama (Local AI)
  system    System-Nachrichten

EMPFAENGER
----------
system                     System-Nachrichten
user                       User-Nachrichten
agent:<name>               Spezifischer Agent (z.B. agent:coder)

STATUS-WERTE
------------
unread                     Ungelesen
read                       Gelesen
archived                   Archiviert
deleted                    Gelöscht

WEB-GUI
-------
http://127.0.0.1:8000/messages

Features:
- Inbox/Outbox/Archiv Ansicht
- Neue Nachricht verfassen
- Als gelesen markieren
- Nachricht-Detail anzeigen

DATENBANK
---------
Tabelle: messages (in data/bach.db)

Felder:
- id             INTEGER PRIMARY KEY
- direction      TEXT (inbox/outbox)
- sender         TEXT
- recipient      TEXT
- subject        TEXT (geplant - derzeit nicht verwendet)
- body           TEXT
- status         TEXT (unread/read/archived/deleted)
- priority       INTEGER
- created_at     TIMESTAMP
- read_at        TIMESTAMP
- archived_at    TIMESTAMP

BEISPIELE
---------
# Nachricht senden
bach msg send system "Backup abgeschlossen"

# Ungelesene anzeigen
bach msg unread

# Nachricht lesen
bach msg read 5

# Nachricht lesen mit Bestaetigung
bach msg read 5 --ack

# Alle Outbox-Nachrichten
bach msg list --outbox

# Auf neue Nachrichten warten
bach msg watch

# Status prüfen
bach msg count

CONNECTOR-INTEGRATION (v1.1.0)
------------------------------
Nachrichten von externen Connectors (Telegram, Discord, etc.)
werden automatisch in die Inbox geroutet:

  connector_messages (in) → route_incoming() → messages (inbox)

Sender-Format: "connector:sender_id" (z.B. "telegram:123456")
Kontext-Hints werden automatisch als metadata gespeichert.

Ausgehende Nachrichten werden über die Queue versendet:

  bach connector send <name> <empfaenger> <text>

Zuverlaessige Zustellung mit Retry/Backoff via Daemon:

  bach connector setup-daemon    # Jobs registrieren
  bach daemon start --bg         # Daemon starten

Siehe: bach --help connector

REST-API (Port 8001)
--------------------
Verfügbar wenn Headless API läuft:

  POST /api/v1/messages/send      Nachricht in Queue einreihen
  GET  /api/v1/messages/queue     Queue-Status
  GET  /api/v1/messages/inbox     Inbox lesen (Paginierung, Filter)
  POST /api/v1/messages/route     Routing manuell auslösen

Beispiel:
  curl localhost:8001/api/v1/messages/inbox?status=unread&limit=10

HANDLER
-------
hub/messages.py            CLI-Handler (Inbox/Outbox)
hub/connector.py           Connector-Handler (Queue, Routing)
gui/api/messages_api.py    REST-API Endpoints
gui/server.py              GUI-Endpunkte (/api/messages)

SIEHE AUCH
----------
bach --help connector      Connector-System (Queue, Retry, Circuit Breaker)
bach --help gui            Web-Dashboard
bach --help daemon         Hintergrund-Jobs
bach --help injectors      Kontext-Injektoren
bach --help wartung        Wartungs-Jobs (automatische Aufgaben)
