import hashlib
import re

def sanitize_herdr_agent_name(name: str) -> str:
    """
    Sanitizes an agent name according to herdr 0.8.0 rules:
    1. Convert to lowercase.
    2. Replace invalid characters ([^a-z0-9_-]) with '-'.
    3. Ensure starts with a lowercase letter [a-z], prefixing with 'x-' if needed.
    4. Truncate to maximum 32 characters using 8-char SHA-1 hash suffix (s[:23] + '-' + sha1[:8]).
    """
    if not name:
        return "agent"
    
    # 1. Lowercase
    s = str(name).lower()
    
    # 2. Replace illegal characters with '-'
    s = re.sub(r'[^a-z0-9_-]', '-', s)
    
    # 3. Ensure starts with a letter [a-z]
    if not s or not s[0].isalpha():
        s = "x-" + s
    
    # 4. Truncate to 32 chars if needed using collision-free SHA-1 hash suffix
    if len(s) > 32:
        h = hashlib.sha1(s.encode('utf-8')).hexdigest()[:8]
        s = f"{s[:23]}-{h}"
    
    return s

