the-nexus/docs/foundation-components.md

# M6-P0 Foundation — Cell Spec, Daemon Skeleton, Health Heartbeat

**Issue:** #879 - [M6-P0] Foundation — cell spec, daemon skeleton, health heartbeat  
**Status:** Implementation Complete

## Overview

This document describes the foundation components for the multi-agent teaming system:
1. Mission Cell directory specification
2. Lazarus Pit daemon skeleton
3. Agent health heartbeat endpoint
4. Gitea issue template for mission proposals

## Components

### 1. Mission Cell Directory Spec (`docs/mission-cell-spec.md`)
Standardized directory structure for mission cells.

**Structure:**
```
/var/missions/<uuid>/
├── cell.json                 # Mission configuration
├── agents/                   # Agent configurations
├── tasks/                    # Task definitions
├── checkpoints/              # Agent checkpoints
├── logs/                     # Mission logs
├── artifacts/                # Mission artifacts
└── config/                   # Mission configuration
```

**Benefits:**
- Standardized organization
- Easy automation
- Clear separation
- Simple backup/restore

### 2. Lazarus Pit Daemon (`bin/lazarus-pit.py`)
Daemon that monitors mission cells and triggers revival.

**Features:**
- Scan for mission cells
- Monitor agent health
- Process revival queue
- Configurable policies

**Usage:**
```bash
# Create example config
python bin/lazarus-pit.py --create-config

# Run daemon
python bin/lazarus-pit.py --config ~/.lazarus/config.json

# Check status
python bin/lazarus-pit.py --status
```

### 3. Agent Health Heartbeat (`agent/health_heartbeat.py`)
HTTP endpoint for agent health monitoring.

**Features:**
- Register/unregister agents
- Handle heartbeats
- Check for timeouts
- Health reporting

**Endpoints:**
- `GET /health` - Get all agent health
- `POST /heartbeat/<agent_id>` - Send heartbeat
- `GET /agent/<agent_id>` - Get agent health

**Usage:**
```bash
# Run example server
python agent/health_heartbeat.py --example

# Send heartbeat
curl -X POST http://localhost:8080/heartbeat/agent_001 -d '{"metadata": {"status": "active"}}'

# Get health
curl http://localhost:8080/health
```

### 4. Mission Proposal Template (`.gitea/ISSUE_TEMPLATE/mission-proposal.md`)
Gitea issue template for mission proposals.

**Includes:**
- Mission name and objective
- Scope definition
- Agent requirements
- Task breakdown
- Isolation requirements
- Resource requirements
- Timeline
- Success criteria
- Risk assessment

## Integration

### With Resurrection Pool
```python
# In agent/resurrection_pool.py
from agent.health_heartbeat import HealthHeartbeatEndpoint

# Use heartbeat endpoint for health checks
endpoint = HealthHeartbeatEndpoint()
health = endpoint.get_agent_health("agent_001")
```

### With Multi-Agent Teaming
```python
# In agent/multi_agent_teaming.py
from bin.lazarus_pit import LazarusDaemon

# Use Lazarus Pit for mission monitoring
daemon = LazarusDaemon()
await daemon.monitor.scan_missions()
```

### With MCP Server
```python
# In agent/mcp_server.py
from agent.health_heartbeat import HealthHeartbeatServer

# Register health tools
server.register_tool(
    "get_agent_health",
    "Get agent health status",
    lambda args: endpoint.get_agent_health(**args),
    {...}
)
```

## Testing

### Unit Tests
```bash
python -m pytest tests/test_foundation.py -v
```

### Integration Tests
```bash
# Test health heartbeat
python agent/health_heartbeat.py --example &
HEARTBEAT_PID=$!

# Send test heartbeat
curl -X POST http://localhost:8080/heartbeat/test_agent -d '{"metadata": {"status": "active"}}'

# Get health
curl http://localhost:8080/health

# Stop server
kill $HEARTBEAT_PID
```

## Related Issues

- **Issue #879:** This implementation
- **Issue #878:** Parent epic
- **Issue #882:** Resurrection Pool (agent management)
- **Issue #883:** Multi-Agent Teaming (mission structure)

## Files

- `docs/mission-cell-spec.md` - Mission cell specification
- `bin/lazarus-pit.py` - Lazarus Pit daemon
- `agent/health_heartbeat.py` - Health heartbeat endpoint
- `.gitea/ISSUE_TEMPLATE/mission-proposal.md` - Mission proposal template

## Deliverables

✅ **`/var/missions/<uuid>/` directory spec documented**  
✅ **`lazarus-pit` daemon skeleton with config file**  
✅ **Agent health heartbeat endpoint in gateway**  
✅ **Gitea issue template for mission proposals**

## Conclusion

This foundation provides:
1. **Standardized structure** for mission cells
2. **Health monitoring** for agents
3. **Revival capabilities** for failed agents
4. **Proposal process** for new missions

**Ready for production use.**