# Portabilität: UNIVERSAL
# Version: 1.0.0
# Zuletzt validiert: 2026-03-04

HANDLER-NAME
============
multi_llm_protocol.py - Koordination paralleler LLM-Agenten

BESCHREIBUNG
============
Protokoll V3 für sichere parallele Arbeit mehrerer KI-Agenten (Claude, Gemini,
Copilot, Ollama, Perplexity, Mistral). Überwacht Praesenz, verwaltet
exklusive Dateizugriffe und synchronisiert Agent-Aktivitäten über
Presence-Dateien, Locks und Handshake-Signale. Zusätzlich: DB-basiertes
Stempelkarten-System für Live-Status in partner_presence Tabelle.

OPERATIONEN
===========
bach llm presence [dir] [task]      Presence im Verzeichnis erstellen
bach llm check [dir]                Andere Agenten in Verzeichnis prüfen
bach llm lock <datei|ordner>        Lock auf Datei oder Verzeichnis erwerben
bach llm unlock [datei]             Eigene Locks freigeben
bach llm handshake [dir]            Handshake mit anderen Agenten starten
bach llm status [dir]               Multi-LLM Status + DB Live-Status anzeigen

KERN-PROTOKOLL V3
=================
1. PRESENCE-System (Dateien)
   - .<agent>_presence: Heartbeat, Status, Arbeitsstand
   - Timeout nach 120 Sekunden Inaktivitaet
   - Status: ACTIVE, FINISHED

2. LOCKING-System (Dateien + Ordner)
   - Datei: <datei>.lock.<agent>
   - Ordner: <ordner>/.dirlock.<agent>
   - Lock-Timeout: 300 Sekunden (stale locks freigeben)
   - Backoff: 5 Sekunden zwischen Versuchen

3. BACKUP-System
   - <datei>.bak vor Änderung
   - Automatisch in safe_write/safe_append

4. HANDSHAKE-Protokoll
   - .handshake_<agent> Dateien
   - Automatische Agent-Discovery
   - Wartet max. 30 Sekunden auf Bestaetigung

5. DB-STEMPELKARTEN (v1.1.71)
   - partner_presence Tabelle
   - clock_in/clock_out bei Startup/Shutdown
   - current_task + last_heartbeat für Live-Status
   - Heartbeat-Timeout: 5 Minuten (konfigurierbar)

BEISPIELE
=========
# Agent aktivieren
bach llm presence /c/Users/User/project processing

# Andere Agenten prüfen
bach llm check /c/Users/User/project

# Lock auf Datei erwerben
bach llm lock /c/Users/User/project/results.txt

# Lock freigeben
bach llm unlock /c/Users/User/project/results.txt

# Handshake starten
bach llm handshake /c/Users/User/project

# Kompletter Status (inkl. DB Live-Status)
bach llm status /c/Users/User/project

# Sichere Schreiboperation (API)
protocol.safe_write(Path("data.txt"), "Inhalt", timeout=60)

# Sichere Append (API)
protocol.safe_append(Path("log.txt"), "Neue Zeile\n", timeout=60)

# DB: Clock In bei Startup
db = PartnerPresenceDB(Path("data/bach.db"), agent_name='claude')
db.clock_in(task="Forschung", working_dir="/project", session_id="uuid-123")

# DB: Live-Status holen
partners = db.get_online_partners(timeout_minutes=5)

DATEIEN
=======
Dateizugriff (relativ zu system/):
  hub/multi_llm_protocol.py          Klassen MultiLLMProtocol, MultiLLMHandler
  data/bach.db                       partner_presence Tabelle (stempelkarten)

Generierte Dateien (im Arbeitsverzeichnis):
  .<agent>_presence                  Praesenz-Marker
  <datei>.lock.<agent>               Datei-Lock
  <ordner>/.dirlock.<agent>          Ordner-Lock
  <datei>.bak                        Backup vor Änderung
  .handshake_<agent>                 Handshake-Signal/Response

SIEHE AUCH
==========
bach --help                 Allgemeine Hilfeseite
hub/base.py                 BaseHandler-Klasse
data/schema.sql             partner_presence Tabelle-Definition
Lesson #62, #63             Entwicklungshistorie (Claude + Gemini Experiment)
