# Refactor Plan

## Objetivo

Fazer um refactor incremental da camada de runtime de voz sem quebrar:
- contrato do bridge websocket
- integracao com LiveKit
- pipeline atual de negocio
- comportamento de interrupcao, idle nudge e finalizacao

## Problema atual

Hoje o arquivo `app/livekit/main.py` concentra responsabilidades demais:
- wiring do AgentSession
- timers
- politica de interrupcao
- idle nudge
- finalizacao
- chamada da pipeline
- speak / wait_for_playout
- notificacao ao bridge

Isso dificulta manutencao, teste e evolucao para alternativas futuras como:
- `llm_node`
- agente remoto via API
- politica de chamada mais previsivel

## Direcao arquitetural

Separar o runtime em camadas:
- adapters: wrappers dos componentes atuais (pipeline, speech, bridge, export)
- runtime: coordenacao da chamada
- domain: estado, eventos e comandos
- policies: regras puras de interrupcao, idle e finalizacao
- engine: reducer e scheduler

## Principios

- preservar comportamento antes de trocar mecanismo
- extrair boundaries antes de mudar a orquestracao
- isolar side effects
- tornar finalizacao idempotente
- introduzir estado explicito da chamada

## Fases sugeridas

### Fase 1: Boundaries

Extrair sem mudar comportamento:
- `PipelineAdapter`
- `SpeechService`
- `BridgeGateway`
- `ExportService`

Saida esperada:
- `app/livekit/main.py` menor
- regras ainda iguais as de hoje

### Fase 2: Runtime explicito

Introduzir:
- `CallState`
- `CallRuntime`
- comandos e eventos

Saida esperada:
- menor uso de `nonlocal`
- caminhos de execucao mais faceis de seguir

### Fase 3: Policies e scheduler

Migrar:
- interrupcao
- idle nudge
- idle close
- finalize once

Saida esperada:
- regras de chamada isoladas e testaveis

### Fase 4: Evolucao de IA

Avaliar depois da estabilizacao:
- `llm_node`
- agente remoto via API
- SSE / websocket para agente externo

Saida esperada:
- STT / IA / TTS com fronteiras mais limpas

## Fora de escopo inicial

- reescrever bridge
- substituir pipeline de negocio
- trocar protocolo websocket externo
- mudar contrato de audio

## Definition of done por fase

### Fase 1
- sem mudanca de contrato externo
- sem mudanca de fluxo de audio
- classes novas usadas pelo `main.py`

### Fase 2
- estado da chamada centralizado
- menos logica de coordenacao inline

### Fase 3
- timers centralizados
- finalizacao unica e previsivel
- regras de interrupcao sem duplicacao

### Fase 4
- nova integracao de IA desacoplada do fluxo manual atual
- comparacao controlada com comportamento anterior