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:

# 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:

# 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

# 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

# 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

# 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

python -m pytest tests/test_foundation.py -v

Integration Tests

# 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.