# Roster Agentics — Nomes, acções e janelas de contexto

**Spec 029 · Secção agentes**

---

## Mapa A0–A7 (nomes operacionais)

| ID | Nome | Codename | Operador humano principal |
|----|------|----------|---------------------------|
| **A0** | **Maestro** | orchestrator | agentic_operator / ops_lead |
| **A1** | **Pulso** | node_health | ops_lead (restart) |
| **A2** | **Trilho** | infra_mail | devops / ops_lead |
| **A3** | **Carta** | deliverability | seo / technician |
| **A4** | **Escudo Mail** | security_mail | security_analyst |
| **A5** | **Sentinela SOC** | wazuh_soc | security_analyst / noc |
| **A6** | **Copiloto** | support_copilot | technician (envia) |
| **A7** | **Remediador** | remediation | agentic_operator (obrigatório) |

### Auxiliares (implementação T0)

| ID | Nome | Função |
|----|------|--------|
| **Vigia** | sentinel | Health checks APIs/VM123 |
| **Curador** | curator | Indexação RAG das specs |

---

## Acções tocadas por cada agente

### A0 — Maestro
- Dispara tick 24/7 (worker 5 min)
- Indexa KB via Curador
- Delega cenários ao Vigia/Pulso/Copiloto
- Abre threads de coordenação inter-agente
- Regista `tick.complete` no audit log

### A1 — Pulso
- `wizard.vm112.bundle` — API + portal onboard
- `proxmox.cluster` — VMs 112/122/123/104 running
- Cria finding → inbox ops_lead se VM parada

### A2 — Trilho
- `pfsense.api.system` — firewall via Traefik
- (futuro) validação DNS/LE pós-onboard
- Propõe fix — **nunca aplica** sem devops

### A3 — Carta
- (futuro) audit SPF/DKIM/DMARC por tenant
- Relatórios entregabilidade → inbox seo

### A4 — Escudo Mail
- (futuro) filas amavis/clamav
- Quarentena sugerida → security_analyst

### A5 — Sentinela SOC
- (futuro) correlacionar Wazuh L≥10 com ticket
- Enriquecer timeline CH-*

### A6 — Copiloto
- `funnel.stuck.onboarding` — tickets >24h
- **Janela /chat** — responde operadores humanos
- Ecoa confirmação quando humano responde num thread
- Rascunho resposta ticket (futuro)

### A7 — Remediador
- (futuro) runbooks R0–R3
- Execução **só após** OK agentic_operator
- Auditoria `action_executed`

### Vigia (sentinel)
- desk, pfSense, webhook gap, Ollama, FOSS, Odoo, OpenPanel bridge
- E-mail + inbox em high/critical

### Curador
- Indexa `specs/**/*.md` no tick
- Alimenta RAG do Copiloto/Advisor

---

## Janelas de contexto (como conversam)

```text
                    ┌─────────────────────────────────────┐
                    │  A0 Maestro (orchestrator)          │
                    │  tick → delega → sintetiza          │
                    └──────────┬──────────────────────────┘
                               │
         ┌─────────────────────┼─────────────────────┐
         ▼                     ▼                     ▼
    A1 Pulso              A6 Copiloto           Vigia
    finding               /chat humano          cenários T0
         │                     │                     │
         └──────────┬──────────┴──────────┬──────────┘
                    ▼                     ▼
              agent_threads         agent_messages
                    │                     │
                    └──────────┬──────────┘
                               ▼
                    Inbox operadores humanos
                    (agentic_operator, ops_lead, …)
```

### Regras de conversa

1. **Agente → Humano:** finding warn+ cria `agent_thread` + mensagem `requires_human=1` na **Inbox**.
2. **Agente → Agente:** Maestro (A0) regista coordenação no mesmo thread («aguardando acção humana»).
3. **Humano → Agente:** operador responde no painel «Janela de contexto» → Copiloto (A6) confirma e encaminha ao agente primary.
4. **Humano ↔ Copiloto:** chat livre via `/chat` com `target_agent` — grava thread persistente.

### Papéis que veem a Inbox

| Role Desk | Vê mensagens destinadas a |
|-----------|---------------------------|
| super_admin | todos |
| agentic_operator | agentic_operator, ops_lead |
| ops_lead | ops_lead, agentic_operator, technician |
| technician | technician |
| security_analyst | security_analyst, agentic_operator |
| devops | devops, ops_lead |

---

## API de mensagens

| Endpoint | Descrição |
|----------|-----------|
| GET `/roster` | Catálogo nomeado |
| GET `/inbox` | Pendências humanas |
| GET `/threads` | Todas as conversas |
| GET `/threads/{id}/messages` | Histórico thread |
| POST `/threads/{id}/reply` | Humano responde |
| POST `/messages/{id}/ack` | Arquivar inbox |
| POST `/chat` | Nova conversa com agente |

---

## UI Desk — painel Agentic Ops

1. **Coluna esquerda:** cards A0–A7 (clique selecciona agente destino)
2. **Coluna centro:** Inbox operadores + findings abertos
3. **Coluna direita:** Janela de contexto (thread + reply + chat Copiloto)