# Portability: UNIVERSAL
# Last validated: 2026-05-17
# Next review: 2027-05-17

HANDLER NAME
------------
multi_llm_protocol.py - Coordination of parallel LLM agents

DESCRIPTION
------------
Protocol V3 for secure parallel work of multiple AI agents (Claude, Gemini,
Copilot, Ollama, Perplexity, Mistral). Monitors presence, manages
exclusive file access and synchronizes agent activities
Presence files, locks and handshake signals. Additionally: DB-based
Stamp card system for live status in partner_presence table.

OPERATIONS
-----------
bach llm presence [dir] [task]      Create presence in the directory
bach llm check [dir]                Check other agents in the directory
bach llm lock <datei|ordner>        Acquire lock on file or directory
bach llm unlock [datei]             Release your own locks
bach llm handshake [dir]            Start handshake with other agents
bach llm status [dir]               Multi-LLM status + DB show live status

CORE PROTOCOL V3
-----------------
1. PRESENCE system (files)
   - .<agent>_presence: Heartbeat, status, work status
   - Timeout after 120 seconds of inactivity
   - Status: ACTIVE, FINISHED

2. LOCKING system (files + folders)
   - File: <file>.lock.<agent>
   - Folder: <folder>/.dirlock.<agent>
   - Lock timeout: 300 seconds (release stale locks)
   - Backoff: 5 seconds between attempts

3. BACKUP system
   - <file>.bak before change
   - Automatically in safe_write/safe_append

4. HANDSHAKE protocol
   - .handshake_<agent> files
   - Automatic agent discovery
   - Waits max. 30 seconds for confirmation

5. DB STAMP CARDS (v1.1.71)
   - partner_presence table
   - clock_in/clock_out at startup/shutdown
   - current_task + last_heartbeat for live status
   - Heartbeat timeout: 5 minutes (configurable)

EXAMPLES
---------
# Activate agent
bach llm presence /c/Users/User/project processing

# Check other agents
bach llm check /c/Users/User/project

# Acquire lock on file
bach llm lock /c/Users/User/project/results.txt

# Release lock
bach llm unlock /c/Users/User/project/results.txt

# Start handshake
bach llm handshake /c/Users/User/project

# Complete status (incl. DB live status)
bach llm status /c/Users/User/project

# Secure write operation (API)
protocol.safe_write(Path("data.txt"), "Content", timeout=60)

# Safe Append (API)
protocol.safe_append(Path("log.txt"), "New line\n", timeout=60)

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

# DB: Get live status
partners = db.get_online_partners(timeout_minutes=5)

FILES
-------
File access (relative to system/):
  hub/multi_llm_protocol.py Classes MultiLLMProtocol, MultiLLMHandler
  data/bach.db partner_presence table (stamp cards)

Generated files (in the working directory):
  .<agent>_presence Presence marker
  <file>.lock.<agent> File lock
  <folder>/.dirlock.<agent> Folder lock
  <file>.bak backup before change
  .handshake_<agent> Handshake signal/response

SEE ALSO
----------
bach --help                 General help page
hub/base.py BaseHandler class
data/schema.sql partner_presence table definition
Lesson #62, #63 Development History (Claude + Gemini Experiment)
