Supervisor Trees

Supervisors can supervise other supervisors, creating hierarchical fault-tolerance trees.

Why Trees?

A single supervisor handles one group of agents. For complex systems, you need multiple levels of supervision:

root-supervisor (one-for-one)
├── api-supervisor (one-for-all)
│   ├── auth-agent
│   └── data-agent
└── worker-supervisor (one-for-one)
    ├── processor-1
    ├── processor-2
    └── processor-3

How It Works

1. If processor-1 crashes → worker-supervisor restarts it
2. If worker-supervisor crashes → root-supervisor restarts it (and all its children)
3. If auth-agent crashes → api-supervisor restarts ALL API agents (one-for-all)

Creating a Tree

# Create supervisors
naos supervisor create root --strategy one-for-one
naos supervisor create api --strategy one-for-all
naos supervisor create workers --strategy one-for-one

# Build the tree
naos supervisor add-child root api
naos supervisor add-child root workers
naos supervisor add-child api auth-agent data-agent
naos supervisor add-child workers processor-1 processor-2 processor-3

Via Configuration

supervisors:
  root:
    strategy: one-for-one
    children:
      - api
      - workers
  api:
    strategy: one-for-all
    children:
      - auth-agent
      - data-agent
  workers:
    strategy: one-for-one
    maxRestarts: 5
    children:
      - processor-1
      - processor-2
      - processor-3

Depth Limits

Supervisor trees can be up to 10 levels deep. Beyond that, consider restructuring your system.