# Gateway

## Que Es el Gateway?

El Gateway es el corazon de Neotask -- un unico servicio de larga ejecucion que gestiona todas las sesiones de agentes, canales de mensajeria, ejecucion de herramientas y conexiones de dispositivos. Todo fluye a traves del Gateway.

Es un servidor WebSocket que escucha conexiones de clientes (aplicacion de escritorio, aplicaciones moviles, panel web) y gestiona todo el ciclo de vida del asistente de IA.

## Arquitectura

### Componentes

- **Servidor WebSocket** -- Acepta conexiones de clientes (puerto por defecto 18789)
- **Servidor HTTP** -- Sirve la UI de Control, host del canvas y endpoints de salud
- **Adaptadores de Canal** -- Mantienen conexiones a plataformas de mensajeria (WhatsApp, Telegram, Discord, etc.)
- **Gestor de Sesiones** -- Persiste y gestiona el estado de conversacion de agentes
- **Programador Cron** -- Ejecuta trabajos programados y activaciones de latido
- **Runtime de Plugins** -- Carga y gestiona el ciclo de vida de plugins
- **Servicio de Navegador** -- Controla instancias de Chromium para automatizacion web

### Modos de Vinculacion

| Modo | Descripcion |
|------|-------------|
| **Loopback** | Por defecto. Solo accesible desde localhost (127.0.0.1) |
| **LAN** | Accesible en su red local. Auto-descubrible via Bonjour/mDNS |
| **Tailnet** | Accesible a traves de VPN Tailscale con MagicDNS |
| **Custom** | Vincular a una direccion especifica |

### Autenticacion

| Metodo | Descripcion |
|--------|-------------|
| **Token** | Token bearer de WebSocket (UUID o cadena personalizada) |
| **Password** | Autenticacion basada en contrasena (hash bcrypt) |
| **Trusted Proxy** | Para proxies inversos con headers pre-autenticados |
| **Local Trust** | Conexiones loopback aprobadas automaticamente |

## Configuracion

El Gateway se configura via `neotask.json` (formato JSON5). Secciones clave:

| Seccion | Controla |
|---------|----------|
| `agents` | Lista de agentes, valores por defecto, espacios de trabajo |
| `gateway` | Puerto, modo de vinculacion, autenticacion, comportamiento de recarga |
| `channels` | Configuracion por canal y credenciales |
| `tools` | Permisos de herramientas, perfiles, seguridad |
| `plugins` | Carga de plugins, habilitacion, configuracion por plugin |
| `models` | Autenticacion de proveedores, respaldos, ajustes de proveedores |
| `skills` | Directorios de skills, configuracion por skill |
| `browser` | Perfiles de navegador, puertos, modo headless |
| `cron` | Configuracion del programador |
| `session` | Reglas de reinicio, umbrales de compactacion |
| `messages` | Ajustes de TTS, politicas de media |
| `memory` | Configuracion de indexacion de memoria |
| `security` | Sandboxing, modo elevado, aprobaciones |

### Recarga en Caliente

Los cambios de configuracion pueden aplicarse sin reiniciar:

| Modo | Comportamiento |
|------|----------|
| **Hybrid** (por defecto) | Aplicar en caliente cambios seguros, reiniciar para otros |
| **Hot** | Solo aplicar cambios seguros en caliente, ignorar otros |
| **Restart** | Reiniciar ante cualquier cambio que requiera reinicio |
| **Off** | Sin recarga automatica |

## Acceso Remoto

### Tailscale (Recomendado)

Tailscale proporciona acceso remoto seguro y sin configuracion:

- Vincule el Gateway a su Tailnet
- Acceda desde cualquier dispositivo en la misma red Tailscale
- DNS automatico via MagicDNS
- Tailscale Serve puede exponer el panel con HTTPS

### Tunel SSH

Reenvie el puerto del Gateway a traves de SSH:

- Simple, seguro, sin cambios de configuracion necesarios
- Funciona con cualquier maquina con capacidad SSH
- Soporta el protocolo WebSocket completo y la UI de Control

### Reglas de Seguridad

- **Loopback + SSH/Tailscale** es la combinacion mas segura
- La vinculacion no loopback requiere configuracion de token de autenticacion
- Fijacion de huella digital TLS disponible para seguridad adicional
- El control del navegador esta deshabilitado para conexiones remotas por defecto

## Monitoreo de Salud

### Endpoint de Salud

El endpoint HTTP `/health` retorna:

- Estado del Gateway
- Vivacidad RPC
- Salud por canal (conectado, estado de autenticacion, conteo de cuentas)
- Disponibilidad del navegador
- Agentes activos y nodos conectados
- Tiempo de actividad

### Sondeos

- **Vivacidad RPC** -- Conexion WebSocket + prueba de eco
- **Salud del canal** -- Verificacion de autenticacion + ping de API por canal
- **Disponibilidad del navegador** -- Verificacion de puerto, verificacion de proceso
- **Conectividad de nodos** -- Marca de tiempo del ultimo latido

## Descubrimiento

### Bonjour/mDNS

Cuando esta vinculado a LAN, el Gateway se anuncia via DNS multicast:

- Tipo de servicio: `_neotask-gw._tcp`
- Incluye puerto, transporte, estado TLS e informacion DNS de Tailscale
- Las aplicaciones companion descubren el Gateway automaticamente

### Descubrimiento de Area Amplia

Descubra gateways a traves de su red con tiempos de espera configurables. Soporta tanto descubrimiento local Bonjour como DNS de Tailscale.

## Multiples Gateways

Puede ejecutar multiples instancias de Gateway en la misma maquina usando perfiles:

- Cada perfil tiene configuracion, espacio de trabajo, sesiones y estado separados
- Puertos diferentes para cada Gateway
- Util para aislamiento (personal vs trabajo) o pruebas

## Diagnosticos

### Doctor

La herramienta de diagnostico integrada verifica:

- Validez de la configuracion
- Permisos de archivos
- Conectividad de canales
- Estado de autenticacion de modelos
- Compatibilidad de version de Node.js
- Configuraciones incorrectas comunes

Puede corregir automaticamente muchos problemas cuando se le da permiso.

### Registro (Logging)

Los logs del Gateway se escriben en archivos JSONL diarios:

- Seguimiento de uso de tokens por completacion
- Logs de eventos de canal
- Registro de errores con contexto estructurado
- Niveles de log configurables