the-nexus/docs/mission-cell-spec.md

Mission Cell Directory Specification

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

Overview

This document specifies the directory structure and layout for Mission Cells in the Hermes fleet.

Directory Structure

/var/missions/<uuid>/
├── cell.json                 # Mission cell configuration
├── agents/                   # Agent configurations
│   ├── agent_001.json
│   ├── agent_002.json
│   └── ...
├── tasks/                    # Task definitions
│   ├── task_001.json
│   ├── task_002.json
│   └── ...
├── checkpoints/              # Agent checkpoints
│   ├── agent_001/
│   │   ├── state.json
│   │   ├── context.json
│   │   └── artifacts/
│   └── ...
├── logs/                     # Mission logs
│   ├── mission.log
│   ├── agent_001.log
│   ├── agent_002.log
│   └── ...
├── artifacts/                # Mission artifacts
│   ├── code/
│   ├── docs/
│   ├── reports/
│   └── ...
└── config/                   # Mission configuration
    ├── isolation.json
    ├── policies.json
    └── permissions.json

File Specifications

cell.json

{
  "cell_id": "uuid-v4",
  "mission_name": "Mission Name",
  "created_at": "ISO-8601 timestamp",
  "created_by": "agent_id",
  "status": "active|paused|completed|failed",
  "isolation_level": "none|level_1|level_2|level_3",
  "max_agents": 10,
  "timeout": 3600,
  "policies": {
    "auto_revive": "yes|no|ask",
    "handoff_allowed": true,
    "checkpoint_interval": 300
  }
}

agent_001.json

{
  "agent_id": "agent_001",
  "name": "Agent Name",
  "role": "lead|write|read|audit",
  "capabilities": ["coding", "testing", "review"],
  "gateway": "gateway_hostname",
  "status": "idle|active|paused|failed",
  "current_task": "task_001",
  "checkpoint": {
    "last_checkpoint": "ISO-8601",
    "context_hash": "sha256",
    "artifacts": ["file1.py", "file2.py"]
  }
}

task_001.json

{
  "task_id": "task_001",
  "title": "Task Title",
  "description": "Task description",
  "assigned_to": "agent_001",
  "status": "pending|in_progress|completed|failed",
  "priority": "high|medium|low",
  "dependencies": ["task_002"],
  "timeout": 1800,
  "artifacts": ["file1.py", "file2.py"],
  "created_at": "ISO-8601",
  "completed_at": "ISO-8601"
}

isolation.json

{
  "level": "none|level_1|level_2|level_3",
  "mount_namespaces": true,
  "network_isolation": true,
  "resource_limits": {
    "cpu": "2 cores",
    "memory": "4GB",
    "disk": "10GB"
  },
  "security_context": {
    "user": "agent_001",
    "group": "agents",
    "capabilities": ["NET_BIND_SERVICE"]
  }
}

policies.json

{
  "auto_revive": "yes|no|ask",
  "revive_timeout": 300,
  "substitute_agents": ["agent_003", "agent_004"],
  "handoff_allowed": true,
  "handoff_approval": "auto|manual",
  "checkpoint_required": true,
  "max_retries": 3
}

permissions.json

{
  "agent_001": {
    "read": ["task_001", "task_002"],
    "write": ["task_001"],
    "execute": ["task_001"],
    "handoff_to": ["agent_002"],
    "handoff_from": ["agent_002"]
  },
  "agent_002": {
    "read": ["task_001", "task_002"],
    "write": ["task_002"],
    "execute": ["task_002"],
    "handoff_to": ["agent_001"],
    "handoff_from": ["agent_001"]
  }
}

Usage

Create Mission Cell

# Create directory structure
mkdir -p /var/missions/$(uuidgen)
cd /var/missions/$(uuidgen)

# Create configuration files
cat > cell.json << EOF
{
  "cell_id": "$(uuidgen)",
  "mission_name": "Example Mission",
  "created_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
  "created_by": "admin",
  "status": "active",
  "isolation_level": "level_1",
  "max_agents": 4,
  "timeout": 3600
}
EOF

# Create subdirectories
mkdir -p agents tasks checkpoints artifacts config logs

Add Agent

cat > agents/agent_001.json << EOF
{
  "agent_id": "agent_001",
  "name": "Lead Agent",
  "role": "lead",
  "capabilities": ["planning", "coordination"],
  "gateway": "gateway_1",
  "status": "idle",
  "current_task": null,
  "checkpoint": null
}
EOF

Add Task

cat > tasks/task_001.json << EOF
{
  "task_id": "task_001",
  "title": "Code Review",
  "description": "Review pull request #123",
  "assigned_to": "agent_001",
  "status": "pending",
  "priority": "high",
  "dependencies": [],
  "timeout": 1800,
  "artifacts": [],
  "created_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
}
EOF

Integration with Hermes

Loading Mission Cell

# In agent/mission_cell.py
from pathlib import Path
import json

class MissionCell:
    def __init__(self, cell_path: Path):
        self.cell_path = cell_path
        self.config = self._load_config()
        self.agents = self._load_agents()
        self.tasks = self._load_tasks()
    
    def _load_config(self):
        config_path = self.cell_path / "cell.json"
        with open(config_path) as f:
            return json.load(f)
    
    def _load_agents(self):
        agents = {}
        agents_dir = self.cell_path / "agents"
        if agents_dir.exists():
            for agent_file in agents_dir.glob("*.json"):
                with open(agent_file) as f:
                    agent = json.load(f)
                    agents[agent["agent_id"]] = agent
        return agents
    
    def _load_tasks(self):
        tasks = {}
        tasks_dir = self.cell_path / "tasks"
        if tasks_dir.exists():
            for task_file in tasks_dir.glob("*.json"):
                with open(task_file) as f:
                    task = json.load(f)
                    tasks[task["task_id"]] = task
        return tasks

Exposing via MCP

# In agent/mcp_server.py
server.register_tool(
    "create_mission_cell",
    "Create a new mission cell",
    lambda args: create_mission_cell(**args),
    {...}
)

server.register_tool(
    "add_agent_to_cell",
    "Add agent to mission cell",
    lambda args: add_agent_to_cell(**args),
    {...}
)

Benefits

1. Standardized structure for all mission cells
2. Isolation through directory-based separation
3. Persistence through file-based storage
4. Auditability through logs and artifacts
5. Portability through JSON configuration

Related Issues

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

Files

• docs/mission-cell-spec.md - This specification
• templates/cell.json - Template for cell configuration
• templates/agent.json - Template for agent configuration
• templates/task.json - Template for task configuration

Conclusion

This specification provides a standardized directory structure for Mission Cells, enabling:

1. Consistent organization across all missions
2. Easy automation through JSON configuration
3. Clear separation between agents, tasks, and artifacts
4. Simple backup/restore through directory operations

Ready for implementation.