# Inter-Agent Communication Protocol Design

## Overview
A robust communication protocol for 8 AI agents on a single VPS, featuring buddy systems, self-healing, and proactive task generation to prevent isolation and empty task queues.

## Architecture

### Agents & Roles
1. **Chief of Staff** - Coordination, priority management, conflict resolution
2. **Coder** - Development, technical implementation, code reviews
3. **Sales** - Customer acquisition, lead qualification, revenue generation
4. **Finance** - Budgeting, reporting, compliance, resource allocation
5. **Intel** - Research, market analysis, competitive intelligence
6. **DevOps** - Infrastructure, deployment, monitoring, security
7. **Comms** - Marketing, content, PR, customer communication
8. **Ops** - Operations, process optimization, project management

### Core Components

#### 1. Shared State Management
```
/shared/
├── agent-states/
│   ├── chief.json
│   ├── coder.json
│   ├── sales.json
│   ├── finance.json
│   ├── intel.json
│   ├── devops.json
│   ├── comms.json
│   └── ops.json
├── task-queues/
│   ├── global-queue.json
│   ├── urgent-queue.json
│   └── agent-specific/
│       ├── chief-tasks.json
│       ├── coder-tasks.json
│       └── [etc...]
├── communication/
│   ├── messages.json
│   ├── notifications.json
│   └── heartbeats.json
└── system/
    ├── protocol-state.json
    ├── buddy-assignments.json
    └── health-metrics.json
```

#### 2. Agent State Schema
```json
{
  "agentId": "chief",
  "status": "active|idle|busy|error|stalled",
  "lastHeartbeat": 1703275200,
  "currentTask": {
    "taskId": "task_123",
    "description": "Review weekly priorities",
    "startTime": 1703271600,
    "estimatedCompletion": 1703275200,
    "priority": "high|medium|low",
    "assignedBy": "system|chief|etc"
  },
  "taskQueue": [
    {
      "taskId": "task_124",
      "description": "Schedule team sync",
      "priority": "medium",
      "dependencies": ["task_123"],
      "createdBy": "ops",
      "createdAt": 1703271600
    }
  ],
  "buddyId": "ops",
  "lastBuddyCheck": 1703271600,
  "context": {
    "activeProjects": ["project_a", "project_b"],
    "recentDecisions": [],
    "contextSize": 1024,
    "maxContextSize": 8192
  },
  "metrics": {
    "tasksCompleted": 15,
    "averageTaskTime": 300,
    "lastActiveTime": 1703275200,
    "stallCount": 0
  }
}
```

## Communication Protocol

### 1. HTTP API Endpoints

Each agent runs a lightweight HTTP server on ports 8001-8008:

```
Chief of Staff: :8001
Coder:         :8002
Sales:         :8003
Finance:       :8004
Intel:         :8005
DevOps:        :8006
Comms:         :8007
Ops:           :8008
```

#### Core Endpoints
```
POST /message           - Send message to agent
GET  /status           - Get current agent status
POST /task             - Assign new task
GET  /health           - Health check
POST /buddy-check      - Buddy system check
POST /context-sync     - Synchronize context
GET  /metrics          - Performance metrics
POST /emergency-stop   - Emergency shutdown
```

### 2. Message Protocol

#### Standard Message Format
```json
{
  "messageId": "msg_12345",
  "from": "chief",
  "to": "coder",
  "type": "task|question|update|notification|buddy-check",
  "priority": "urgent|high|medium|low",
  "timestamp": 1703275200,
  "content": {
    "subject": "Code review required",
    "body": "Please review the authentication module",
    "data": {},
    "requiresResponse": true,
    "deadline": 1703278800
  },
  "context": {
    "threadId": "thread_123",
    "projectId": "project_a",
    "relatedTasks": ["task_123"]
  }
}
```

## Buddy System Implementation

### 1. Buddy Assignments
Strategic pairing based on complementary roles:

```json
{
  "buddyPairs": {
    "chief": "ops",
    "ops": "chief",
    "coder": "devops",
    "devops": "coder",
    "sales": "comms",
    "comms": "sales",
    "finance": "intel",
    "intel": "finance"
  }
}
```

### 2. Buddy Check Protocol

#### Hourly Cross-Check Process
```python
# Pseudo-code for buddy check
def buddy_check():
    buddy_id = get_buddy_id()
    buddy_status = http_get(f"http://localhost:800{buddy_id}/status")
    
    if buddy_status.last_heartbeat < (now() - 3600):  # 1 hour stale
        trigger_buddy_intervention(buddy_id)
    
    if buddy_status.task_queue_empty and buddy_status.status == "idle":
        generate_contextual_tasks(buddy_id)
    
    if buddy_status.context_size > max_context * 0.8:
        trigger_context_cleanup(buddy_id)
```

#### Buddy Intervention Actions
1. **Health Check**: Send health ping with response requirement
2. **Task Generation**: Create relevant tasks based on agent's role
3. **Context Refresh**: Help with context overflow management
4. **Escalation**: Notify Chief of Staff if buddy is unresponsive

## Self-Healing Mechanisms

### 1. Stall Detection
```python
def detect_stall(agent_state):
    current_time = time.now()
    
    # Check if agent has been on same task too long
    if agent_state.current_task:
        task_duration = current_time - agent_state.current_task.start_time
        expected_duration = agent_state.current_task.estimated_completion
        
        if task_duration > expected_duration * 2:
            return "task_timeout"
    
    # Check if agent has been idle too long
    if agent_state.status == "idle":
        idle_duration = current_time - agent_state.last_active_time
        if idle_duration > 1800:  # 30 minutes
            return "excessive_idle"
    
    # Check heartbeat freshness
    if current_time - agent_state.last_heartbeat > 1800:
        return "heartbeat_stale"
    
    return None
```

### 2. Auto-Recovery Actions
```python
def auto_recover(agent_id, stall_type):
    if stall_type == "task_timeout":
        # Break down current task into smaller chunks
        break_down_task(agent_id)
        # Or reassign to another agent
        reassign_task(agent_id)
    
    elif stall_type == "excessive_idle":
        # Generate new tasks based on agent role and context
        generate_role_appropriate_tasks(agent_id)
    
    elif stall_type == "heartbeat_stale":
        # Attempt restart
        restart_agent(agent_id)
        # Redistribute current tasks
        redistribute_tasks(agent_id)
```

## Auto-Task Generation

### 1. Role-Based Task Templates
```json
{
  "chief": [
    "Review team productivity metrics",
    "Prioritize pending tasks across agents",
    "Check for resource conflicts",
    "Plan next sprint objectives"
  ],
  "coder": [
    "Code review pending PRs",
    "Update technical documentation",
    "Refactor legacy code modules",
    "Run automated tests"
  ],
  "sales": [
    "Follow up on warm leads",
    "Update CRM with recent interactions",
    "Research competitor pricing",
    "Prepare sales reports"
  ],
  "finance": [
    "Update financial projections",
    "Review expense reports",
    "Monitor cash flow",
    "Prepare budget analysis"
  ],
  "intel": [
    "Market research on industry trends",
    "Competitor analysis update",
    "Customer feedback analysis",
    "Technology trend assessment"
  ],
  "devops": [
    "Monitor system health",
    "Update deployment scripts",
    "Security audit",
    "Performance optimization"
  ],
  "comms": [
    "Draft newsletter content",
    "Social media engagement",
    "PR opportunity research",
    "Content calendar planning"
  ],
  "ops": [
    "Process optimization review",
    "Project timeline updates",
    "Resource allocation analysis",
    "Workflow documentation"
  ]
}
```

### 2. Context-Aware Task Generation
```python
def generate_contextual_tasks(agent_id):
    agent_state = load_agent_state(agent_id)
    role = agent_state.agent_id
    
    # Get available task templates for role
    templates = TASK_TEMPLATES[role]
    
    # Filter based on current context
    relevant_tasks = []
    for template in templates:
        if is_task_relevant(template, agent_state.context):
            task = create_task_from_template(template, agent_state)
            relevant_tasks.append(task)
    
    # Add cross-functional tasks
    cross_functional = generate_cross_functional_tasks(agent_id)
    
    # Prioritize and add to queue
    prioritized_tasks = prioritize_tasks(relevant_tasks + cross_functional)
    add_tasks_to_queue(agent_id, prioritized_tasks[:3])  # Max 3 at a time
```

## Context Overflow Prevention

### 1. Context Management Strategy
```python
class ContextManager:
    def __init__(self, max_size=8192):
        self.max_size = max_size
        self.warning_threshold = max_size * 0.8
    
    def check_context_size(self, agent_id):
        agent_state = load_agent_state(agent_id)
        current_size = agent_state.context.context_size
        
        if current_size > self.warning_threshold:
            self.compress_context(agent_id)
        
        if current_size > self.max_size:
            self.emergency_context_cleanup(agent_id)
    
    def compress_context(self, agent_id):
        # Summarize old decisions and completed tasks
        # Keep only essential recent context
        # Archive detailed history to separate files
        pass
    
    def emergency_context_cleanup(self, agent_id):
        # Aggressive cleanup
        # Keep only current task and immediate priorities
        # Notify buddy to help reconstruct if needed
        pass
```

### 2. Context Rotation Strategy
- **Hot Context**: Last 2 hours of activity (kept in memory)
- **Warm Context**: Last 24 hours (compressed summaries)
- **Cold Context**: Older than 24 hours (archived to files)

## Implementation Scripts

### 1. System Controller (system-controller.py)
```python
#!/usr/bin/env python3
"""
Main system controller - orchestrates the entire protocol
"""

import time
import json
import requests
from datetime import datetime, timedelta

class AgentProtocolController:
    def __init__(self):
        self.agents = {
            'chief': 8001, 'coder': 8002, 'sales': 8003, 'finance': 8004,
            'intel': 8005, 'devops': 8006, 'comms': 8007, 'ops': 8008
        }
        self.buddy_pairs = {
            'chief': 'ops', 'ops': 'chief',
            'coder': 'devops', 'devops': 'coder',
            'sales': 'comms', 'comms': 'sales',
            'finance': 'intel', 'intel': 'finance'
        }
    
    def run_protocol_cycle(self):
        """Main protocol execution cycle"""
        while True:
            self.check_all_agents_health()
            self.run_buddy_checks()
            self.detect_and_heal_stalls()
            self.generate_tasks_for_idle_agents()
            self.manage_context_overflow()
            time.sleep(300)  # 5-minute cycles
    
    def check_all_agents_health(self):
        """Check health of all agents"""
        for agent_id, port in self.agents.items():
            try:
                response = requests.get(f"http://localhost:{port}/health", timeout=5)
                if response.status_code != 200:
                    self.handle_unhealthy_agent(agent_id)
            except Exception as e:
                self.handle_unresponsive_agent(agent_id, str(e))
    
    def run_buddy_checks(self):
        """Execute buddy system checks"""
        for agent_id, buddy_id in self.buddy_pairs.items():
            self.execute_buddy_check(agent_id, buddy_id)
    
    # Additional methods...
```

### 2. Agent Base Class (agent-base.py)
```python
#!/usr/bin/env python3
"""
Base class for all agents with protocol implementation
"""

import json
import time
from flask import Flask, request, jsonify
from threading import Thread, Lock

class BaseAgent:
    def __init__(self, agent_id, port):
        self.agent_id = agent_id
        self.port = port
        self.app = Flask(__name__)
        self.state_lock = Lock()
        self.setup_routes()
        self.load_state()
    
    def setup_routes(self):
        """Setup HTTP API routes"""
        @self.app.route('/health', methods=['GET'])
        def health():
            return jsonify({"status": "healthy", "timestamp": time.time()})
        
        @self.app.route('/status', methods=['GET'])
        def status():
            with self.state_lock:
                return jsonify(self.state)
        
        @self.app.route('/message', methods=['POST'])
        def receive_message():
            message = request.json
            return self.handle_message(message)
        
        @self.app.route('/task', methods=['POST'])
        def receive_task():
            task = request.json
            return self.handle_new_task(task)
        
        @self.app.route('/buddy-check', methods=['POST'])
        def buddy_check():
            return self.handle_buddy_check(request.json)
    
    def run(self):
        """Start the agent"""
        # Start background threads
        Thread(target=self.heartbeat_loop, daemon=True).start()
        Thread(target=self.task_processor, daemon=True).start()
        
        # Start HTTP server
        self.app.run(host='localhost', port=self.port, debug=False)
    
    # Additional base methods...
```

### 3. Deployment Configuration (docker-compose.yml)
```yaml
version: '3.8'
services:
  chief:
    build: .
    command: python agents/chief.py
    ports:
      - "8001:8001"
    volumes:
      - ./shared:/shared
      - ./logs:/logs
    environment:
      - AGENT_ID=chief
      - PORT=8001
  
  coder:
    build: .
    command: python agents/coder.py
    ports:
      - "8002:8002"
    volumes:
      - ./shared:/shared
      - ./logs:/logs
    environment:
      - AGENT_ID=coder
      - PORT=8002
  
  # Repeat for all 8 agents...
  
  protocol-controller:
    build: .
    command: python system-controller.py
    volumes:
      - ./shared:/shared
      - ./logs:/logs
    depends_on:
      - chief
      - coder
      - sales
      - finance
      - intel
      - devops
      - comms
      - ops
```

## Monitoring & Logging

### 1. System Metrics Dashboard
Track key metrics:
- Agent response times
- Task completion rates
- Buddy check success rates
- Context overflow incidents
- Stall detection and recovery

### 2. Log Structure
```
/logs/
├── system/
│   ├── protocol-controller.log
│   └── health-checks.log
├── agents/
│   ├── chief.log
│   ├── coder.log
│   └── [etc...]
├── communication/
│   ├── messages.log
│   └── buddy-checks.log
└── performance/
    ├── task-metrics.log
    └── context-metrics.log
```

## Failure Scenarios & Responses

### 1. Agent Crashes
- Buddy detects missing heartbeat
- System controller restarts agent
- Tasks redistributed to available agents
- Context restored from last checkpoint

### 2. Network Partitions
- Agents continue with cached tasks
- Buddy system provides redundancy
- Auto-reconnection attempts
- State synchronization on recovery

### 3. Resource Exhaustion
- Context cleanup triggered automatically
- Non-critical tasks paused
- Priority queue management
- Resource monitoring alerts

## Getting Started

1. **Setup Environment**
```bash
cd /shared
mkdir -p {agent-states,task-queues,communication,system}
mkdir -p task-queues/agent-specific
mkdir -p logs/{system,agents,communication,performance}
```

2. **Deploy Agents**
```bash
docker-compose up -d
```

3. **Monitor System**
```bash
# Check all agent health
curl http://localhost:8001/health

# View system metrics
tail -f logs/system/protocol-controller.log

# Check agent status
curl http://localhost:8002/status
```

This protocol ensures your 8 AI agents maintain active communication, prevent isolation through the buddy system, automatically generate relevant tasks, and include robust self-healing mechanisms. The system is designed to be resilient, observable, and easily maintainable.