B2BCall-dialer/docs/AGENTS.md

# Agentes, Tiers e Pausas

Agente.md secao 45-49 e 52. Completa o Call Center: depois desta fase, um
usuário autenticado consegue logar como agente, entrar numa fila real, se
pausar e voltar — tudo refletido de verdade no FreeSWITCH.

## Modelo

- `agents` (tenant-scoped, RLS): liga `User` (login) → `Extension` (ramal
  SIP) → identidade de agente (`User`/`Agent`/`Extension` separados,
  agente.md secao 45). `state` espelha o estado real (secao 46), nunca
  escrito direto pela API — só via login/logout/pause/resume.
- `tiers`: Queue↔Agent (secao 52) — level/position espelham 1:1 o
  mod_callcenter.
- `agent_sessions`: uma linha por ciclo login→logout.
- `agent_state_events`: histórico de transições de estado (auditoria).
- `pause_reasons`/`agent_pause_events` (secao 48).

## Mecanismo: 100% dinâmico, sem arquivo

Confirmado na fase anterior (Queues) via `help callcenter_config`: agentes e
tiers não têm representação em XML — só comandos ESL diretos
(`agent add/del/set status/set contact`, `tier add/del`). Isso muda o padrão
de sincronização: em vez de "regenerar todos os arquivos" (Trunks/Queues),
`apps/api` publica uma mensagem **por ação, com payload** (`{tenantId,
agentId, action}` em `b2bcall:agents:sync`; `{tenantId, queueId, agentId,
level, position, action}` em `b2bcall:tiers:sync`) — `b2bcall-fs-config`
recebe e aplica o comando correspondente.

## Achados reais confirmados manualmente antes de codar

Rodei cada comando contra o FreeSWITCH real antes de escrever qualquer
lógica de sync (mesmo método usado nas fases anteriores):

- `agent add` em cima de um agente que já existe: **erro**
  ("Agent already exist!") — não é idempotente. `tier add` duplicado: mesmo
  erro ("Tier already exist!"). Ambos capturados e ignorados no sync
  (`.catch(() => undefined)`), já que essa condição é esperada em qualquer
  resync.
- `tier del`/`agent del` em algo que não existe: **não dá erro** (+OK) —
  seguro chamar sem checar existência antes.
- `agent set status` só aceita 3 valores exatos: `Available`, `On Break`,
  `Logged Out` — qualquer outro string dá `-ERR Invalid Agent Status!`
  (testado deliberadamente). Os estados derivados de chamada do nosso enum
  (RESERVED/RINGING/IN_CALL/WRAP_UP) não têm status próprio no
  mod_callcenter — mapeiam pra "Available" (só o `state`, campo separado,
  muda sozinho conforme a chamada progride — não escrevemos isso).
- **Achado de corrida real**, visto ao testar o fluxo completo: como um
  agente só passa a existir no FreeSWITCH no login (`agent add` roda ali,
  não na criação do registro `Agent`), atribuir um tier (`POST
  /queues/:id/agents`) **antes** do primeiro login do agente falha
  silenciosamente do lado do FreeSWITCH (`-ERR Agent not found!`, logado
  mas não propagado como erro HTTP). Por isso o login **sempre
  re-sincroniza todos os tiers do agente** depois de garantir que ele
  existe — a auto-correção aconteceu exatamente assim no teste real.

## Fluxo de login (agente.md secao 47)

```
POST /agents/me/login
  → valida usuário (JWT) e ramal (Agent.extensionId precisa existir)
  → cria agent_session
  → agent add (idempotente via catch) + set contact (dial-string do ramal)
  → set status Available
  → re-sincroniza todos os tiers do agente
  → Agent.state = AVAILABLE
```

`POST /agents/me/logout|pause|resume` seguem o mesmo padrão — sempre sobre
o agente do **próprio usuário autenticado** (nunca um `agentId` arbitrário
do client, mesmo princípio de nunca confiar em tenant_id/ids sensíveis vindo
do frontend sem checar contra o JWT).

## Verificado ponta a ponta

```
POST /extensions {"number":"2000",...}
POST /agents {userId, extensionId, name}
POST /queues {"name":"Suporte"}
POST /queues/:queueId/agents {agentId}          → tier add falha (agente ainda nao existe)
POST /agents/me/login                            → agent add + contact + status Available
                                                  → tier re-sync (dessa vez funciona)

callcenter_config agent list
→ status=Available, contact={ignore_early_media=true}user/2000@b2bcall.local ✓
callcenter_config tier list
→ queue|agent com state=Ready ✓

POST /agents/me/pause {pauseReasonId}  → status=On Break ✓
POST /agents/me/resume                 → status=Available ✓
POST /agents/me/logout                 → status=Logged Out ✓
```

Todos os 4 estados confirmados batendo entre o banco (`Agent.state`) e o
FreeSWITCH (`agent list`).

## O que falta

- Estados derivados de chamada (RINGING, IN_CALL, WRAP_UP, RESERVED) — o
  mecanismo de entrega do `callcenter::info` foi corrigido e confirmado
  funcionando (ver seção abaixo), mas gravar esses estados de volta em
  `Agent.state` ainda não foi implementado — hoje o campo só muda via
  login/logout/pause/resume. O estado real do mod_callcenter (`CC-Agent-State`:
  `Waiting`/`Receiving`/...) já está disponível em tempo real via WebSocket
  (docs/REALTIME.md); persistir isso em `Agent.state` fica pra quando o
  Predictive Engine/CDR precisarem consultar esse histórico.
- Tela do agente (secao 49) — fase Frontend.
- ~~Quota de agentes~~ — implementada na fase Plans/Entitlements (ver
  docs/ENTITLEMENTS.md), `assertQuota` chamado antes de criar.
- `PauseReason.maxDuration` existe no modelo mas não é aplicado
  automaticamente ainda (ninguém força o fim da pausa ao expirar).
- **Achado ao testar a fase Realtime Monitoring, sistêmico (não é só
  Agent)**: `@@unique([tenantId, userId])` em `Agent` não exclui
  `deletedAt` — apagar um agente (soft delete) e tentar criar outro pro
  mesmo usuário no mesmo tenant falha com `Unique constraint failed`,
  porque a linha apagada continua ocupando o slot único indefinidamente.
  Confirmado ao vivo durante o teste desta fase. O mesmo padrão
  (`@@unique` combinado com soft delete, sem excluir `deletedAt`) existe
  em pelo menos mais 4 models: `Extension` (`tenantId, number`), `Trunk`
  (`tenantId, name`), `Queue` (`tenantId, name`), `PauseReason`
  (`tenantId, code`) — todos vão ter o mesmo problema (não dá pra reusar
  um número/nome/código depois de apagar). Precisa de um índice único
  parcial (`WHERE deleted_at IS NULL`) em cada um — não corrigido nesta
  fase (é uma migration própria tocando 5 tabelas, fora do escopo de
  Realtime Monitoring); fica registrado aqui pra não se perder.

## Correção: eventos CUSTOM (`callcenter::info`) nunca chegavam

Achado ao testar esta fase ponta a ponta com uma chamada real de teste
(`originate null/dummy &callcenter(fila@dominio)`): nenhum evento CUSTOM
aparecia em `b2bcall-fs-events`, apesar do agente ser ofertado a chamada de
verdade (`agent list` mostrava `last_offered_call` mudando). Causa raiz:
`event_json(...SUBSCRIBED_EVENTS)` mandava `"CUSTOM"` como último argumento
do comando `event json`, sem nenhum subclass depois — o mod_event_socket do
FreeSWITCH exige que os subclasses (`callcenter::info`, `sofia::register`,
`sofia::gateway_state`, ...) venham logo depois do token `CUSTOM` no mesmo
comando, senão zero eventos CUSTOM são entregues (de qualquer subclass).
Afetava também `sofia::gateway_state` (ver correção equivalente em
docs/TRUNKS.md).

Corrigido separando `PLAIN_EVENTS` (nomes normais, cada um vira um listener
`.on()`) de `CUSTOM_SUBCLASSES` (só compõem o comando `event json`, nunca
viram listener — o client ESL sempre emite `"CUSTOM"` como nome de evento,
com o subclass real no header `Event-Subclass`).

De quebra, corrigido também o nome de campo errado em
`normalizeCustomEvent`: o código lia `CC-Agent-Status`, que não existe — o
campo real é `CC-Agent-State`. Os `CC-Action` reais observados no teste
(úteis pro monitoramento de filas, agente.md secao 54): `agent-offering`,
`agent-state-change`, `bridge-agent-fail`, `member-queue-end` (com
`CC-Cause`/`CC-Cancel-Reason` e timestamps de entrada/saída — abandono vs.
atendida), `members-count` (contagem ao vivo de chamadas esperando por
fila). Ver `packages/telephony/src/normalize-event.ts`.

## Widget de status na topbar (PHASE 62)

Achado real reportado pelo usuário: "não achei como deixar o agente
online, tem algum perfil ou tipo de usuário específico?" — não era
permissão nenhuma: `POST /agents/me/login|pause|resume|logout`
(`apps/api/src/agents/agents-me.controller.ts`) sempre funcionaram sem
exigir permissão nenhuma (só `JwtAuthGuard`, resolvem "meu agente" via
`userId` do próprio token — nunca aceitam um `agentId` do client). O
problema era que NENHUMA tela chamava esses endpoints — só existia o CRUD
admin de Agentes (criar o vínculo usuário+ramal em Call Center >
Agentes).

Adicionado `GET /agents/me` (404 = usuário sem Agent neste tenant, não um
erro) e `GET /agents/me/pause-reasons` (motivos de pausa sem exigir
`agents.view`, que listaria TODOS os agentes do tenant — permissão que o
role "agent" nunca teve e não devia ganhar só pra isso). `AgentStatusWidget`
na topbar (visível em qualquer página do app do tenant, `apps/app/layout.tsx`
busca `/agents/me` uma vez por request) só aparece pra quem tem Agent
vinculado: Offline → "Entrar" → Disponível → "Pausar" (escolhe motivo) →
Em pausa → "Retomar"/"Sair".

Testado ponta a ponta com Playwright, logado como um agente de teste
real (usuário novo, role "agent", Agent vinculado a um ramal real): o
fluxo completo (entrar/pausar/retomar/sair) funciona pela tela, sem
nenhuma chamada de API manual.