# Gateway

## O Que E o Gateway?

O Gateway e o coracao do Neotask -- um unico servico de longa execucao que gerencia todas as sessoes de agente, canais de mensagens, execucao de ferramentas e conexoes de dispositivos. Tudo flui atraves do Gateway.

E um servidor WebSocket que escuta conexoes de clientes (app desktop, apps moveis, dashboard web) e gerencia todo o ciclo de vida do assistente de IA.

## Arquitetura

### Componentes

- **Servidor WebSocket** -- Aceita conexoes de clientes (porta padrao 18789)
- **Servidor HTTP** -- Serve a UI de Controle, host do canvas e endpoints de saude
- **Adaptadores de Canal** -- Mantem conexoes com plataformas de mensagens (WhatsApp, Telegram, Discord, etc.)
- **Gerenciador de Sessoes** -- Persiste e gerencia o estado de conversa dos agentes
- **Agendador Cron** -- Executa jobs agendados e despertares por heartbeat
- **Runtime de Plugins** -- Carrega e gerencia o ciclo de vida de plugins
- **Servico de Navegador** -- Controla instancias Chromium para automacao web

### Modos de Vinculacao

| Modo | Descricao |
|------|-----------|
| **Loopback** | Padrao. Acessivel apenas do localhost (127.0.0.1) |
| **LAN** | Acessivel na sua rede local. Descoberta automatica via Bonjour/mDNS |
| **Tailnet** | Acessivel atraves de VPN Tailscale com MagicDNS |
| **Personalizado** | Vincule a um endereco especifico |

### Autenticacao

| Metodo | Descricao |
|--------|-----------|
| **Token** | Token bearer WebSocket (UUID ou string personalizada) |
| **Senha** | Autenticacao baseada em senha (hash bcrypt) |
| **Proxy Confiavel** | Para proxies reversos com headers pre-autenticados |
| **Confianca Local** | Conexoes loopback auto-aprovadas |

## Configuracao

O Gateway e configurado via `neotask.json` (formato JSON5). Secoes principais:

| Secao | Controla |
|-------|----------|
| `agents` | Lista de agentes, padroes, workspaces |
| `gateway` | Porta, modo de vinculacao, autenticacao, comportamento de reload |
| `channels` | Configuracao por canal e credenciais |
| `tools` | Permissoes de ferramentas, perfis, seguranca |
| `plugins` | Carregamento de plugins, habilitacao, configuracao por plugin |
| `models` | Autenticacao de provedores, fallbacks, configuracoes de provedores |
| `skills` | Diretorios de skills, configuracao por skill |
| `browser` | Perfis de navegador, portas, modo headless |
| `cron` | Configuracao do agendador |
| `session` | Regras de reset, limiares de compactacao |
| `messages` | Configuracoes TTS, politicas de midia |
| `memory` | Configuracao de indexacao de memoria |
| `security` | Sandboxing, modo elevado, aprovacoes |

### Hot Reload

Mudancas de configuracao podem ser aplicadas sem reiniciar:

| Modo | Comportamento |
|------|---------------|
| **Hibrido** (padrao) | Aplica mudancas seguras a quente, reinicia para outras |
| **Hot** | Aplica apenas mudancas seguras a quente, ignora outras |
| **Reiniciar** | Reinicia em qualquer mudanca que requer reload |
| **Desligado** | Sem reload automatico |

## Acesso Remoto

### Tailscale (Recomendado)

Tailscale fornece acesso remoto seguro, sem configuracao:

- Vincule o Gateway ao seu Tailnet
- Acesse de qualquer dispositivo na mesma rede Tailscale
- DNS automatico via MagicDNS
- Tailscale Serve pode expor o dashboard com HTTPS

### Tunel SSH

Encaminhe a porta do Gateway atraves de SSH:

- Simples, seguro, sem mudancas de configuracao necessarias
- Funciona com qualquer maquina capaz de SSH
- Suporta o protocolo WebSocket completo e a UI de Controle

### Regras de Seguranca

- **Loopback + SSH/Tailscale** e a combinacao mais segura
- Vinculacao nao-loopback requer configuracao de token de autenticacao
- Fixacao de fingerprint TLS disponivel para seguranca adicional
- Controle de navegador e desabilitado para conexoes remotas por padrao

## Monitoramento de Saude

### Endpoint de Saude

O endpoint HTTP `/health` retorna:

- Status do Gateway
- Liveness RPC
- Saude por canal (conectado, status de autenticacao, contagem de contas)
- Prontidao do navegador
- Agentes ativos e nodes conectados
- Uptime

### Probes

- **Liveness RPC** -- Conexao WebSocket + teste de eco
- **Saude do canal** -- Verificacao de autenticacao + ping de API por canal
- **Prontidao do navegador** -- Verificacao de porta, verificacao de processo
- **Conectividade do node** -- Timestamp do ultimo heartbeat

## Descoberta

### Bonjour/mDNS

Quando vinculado a LAN, o Gateway se anuncia via DNS multicast:

- Tipo de servico: `_neotask-gw._tcp`
- Inclui porta, transporte, status TLS e info DNS do Tailscale
- Apps companion descobrem o Gateway automaticamente

### Descoberta de Area Ampla

Descubra gateways pela sua rede com timeouts configuraveis. Suporta tanto Bonjour local quanto descoberta DNS do Tailscale.

## Multiplos Gateways

Voce pode executar multiplas instancias de Gateway na mesma maquina usando perfis:

- Cada perfil tem configuracao, workspace, sessoes e estado separados
- Portas diferentes para cada Gateway
- Util para isolamento (pessoal vs trabalho) ou testes

## Diagnosticos

### Doctor

A ferramenta de diagnostico integrada verifica:

- Validade da configuracao
- Permissoes de arquivo
- Conectividade de canais
- Status de autenticacao de modelos
- Compatibilidade de versao do Node.js
- Configuracoes incorretas comuns

Pode corrigir automaticamente muitos problemas quando dada permissao.

### Logging

Logs do Gateway sao escritos em arquivos JSONL diarios:

- Rastreamento de uso de tokens por completion
- Logs de eventos de canal
- Log de erros com contexto estruturado
- Niveis de log configuraveis