# Gateway

## Cos'è il Gateway?

Il Gateway è il cuore di Neotask, un singolo servizio a lunga esecuzione che gestisce tutte le sessioni degli agenti, i canali di messaggistica, l'esecuzione degli strumenti e le connessioni dei dispositivi. Tutto passa attraverso il Gateway.

È un server WebSocket che ascolta le connessioni dai client (app desktop, app mobili, dashboard web) e gestisce l'intero ciclo di vita dell'assistente AI.

## Architettura

### Componenti

- **WebSocket Server**, Accetta le connessioni dei client (porta predefinita 18789)
- **HTTP Server**, Serve la Control UI, il canvas host e gli endpoint di health
- **Channel Adapters**, Mantengono le connessioni alle piattaforme di messaggistica (WhatsApp, Telegram, Discord, ecc.)
- **Session Manager**, Persiste e gestisce lo stato delle conversazioni degli agenti
- **Cron Scheduler**, Esegue i job pianificati e i risveglio tramite heartbeat
- **Plugin Runtime**, Carica e gestisce il ciclo di vita dei plugin
- **Browser Service**, Controlla le istanze Chromium per l'automazione web

### Modalità di Binding

| Modalità | Descrizione |
|------|-------------|
| **Loopback** | Predefinita. Accessibile solo da localhost (127.0.0.1) |
| **LAN** | Accessibile sulla rete locale. Auto-scopribile tramite Bonjour/mDNS |
| **Tailnet** | Accessibile tramite Tailscale VPN con MagicDNS |
| **Custom** | Lega a un indirizzo specifico |

### Autenticazione

| Metodo | Descrizione |
|--------|-------------|
| **Token** | Bearer token WebSocket (UUID o stringa personalizzata) |
| **Password** | Autenticazione basata su password (hash bcrypt) |
| **Trusted Proxy** | Per proxy inversi con header pre-autenticati |
| **Local Trust** | Connessioni loopback approvate automaticamente |

## Configurazione

Il Gateway è configurato tramite `neotask.json` (formato JSON5). Sezioni principali:

| Sezione | Controlla |
|---------|----------|
| `agents` | Elenco agenti, valori predefiniti, workspace |
| `gateway` | Porta, modalità di binding, autenticazione, comportamento di ricarica |
| `channels` | Configurazione e credenziali per canale |
| `tools` | Permessi degli strumenti, profili, sicurezza |
| `plugins` | Caricamento plugin, abilitazione, configurazione per plugin |
| `models` | Autenticazione provider, fallback, impostazioni provider |
| `skills` | Directory delle skill, configurazione per skill |
| `browser` | Profili browser, porte, modalità headless |
| `cron` | Configurazione dello scheduler |
| `session` | Regole di reset, soglie di compattazione |
| `messages` | Impostazioni TTS, policy media |
| `memory` | Configurazione dell'indicizzazione della memoria |
| `security` | Sandboxing, modalità elevata, approvazioni |

### Hot Reload

Le modifiche alla configurazione possono essere applicate senza riavvio:

| Modalità | Comportamento |
|------|----------|
| **Hybrid** (predefinita) | Applica immediatamente le modifiche sicure, riavvia per le altre |
| **Hot** | Applica solo le modifiche hot-safe, ignora le altre |
| **Restart** | Riavvia per qualsiasi modifica che richiede ricarica |
| **Off** | Nessun ricaricamento automatico |

## Accesso Remoto

### Tailscale (Consigliato)

Tailscale fornisce accesso remoto sicuro e zero-config:

- Lega il Gateway al tuo Tailnet
- Accedi da qualsiasi dispositivo sulla stessa rete Tailscale
- DNS automatico tramite MagicDNS
- Tailscale Serve può esporre la dashboard con HTTPS

### SSH Tunnel

Inoltra la porta del Gateway tramite SSH:

- Semplice, sicuro, nessuna modifica alla configurazione necessaria
- Funziona con qualsiasi macchina con supporto SSH
- Supporta il protocollo WebSocket completo e la Control UI

### Regole di Sicurezza

- **Loopback + SSH/Tailscale** è la combinazione più sicura
- Il binding non-loopback richiede la configurazione del token di autenticazione
- TLS fingerprint pinning disponibile per sicurezza extra
- Il controllo del browser è disabilitato per le connessioni remote per default

## Monitoraggio della Salute

### Endpoint di Health

L'endpoint HTTP `/health` restituisce:

- Stato del Gateway
- Liveness RPC
- Salute per canale (connesso, stato auth, numero di account)
- Disponibilità del browser
- Agenti attivi e nodi connessi
- Uptime

### Probe

- **RPC liveness**, Connessione WebSocket + test echo
- **Channel health**, Controllo auth + ping API per canale
- **Browser readiness**, Controllo porta, controllo processo
- **Node connectivity**, Timestamp dell'ultimo heartbeat

## Scoperta

### Bonjour/mDNS

Quando legato alla LAN, il Gateway si annuncia tramite DNS multicast:

- Tipo di servizio: `_neotask-gw._tcp`
- Include porta, trasporto, stato TLS e informazioni DNS Tailscale
- Le app companion scoprono automaticamente il Gateway

### Scoperta Wide-Area

Scopri i gateway sulla tua rete con timeout configurabili. Supporta sia Bonjour locale che scoperta DNS Tailscale.

## Gateway Multipli

Puoi eseguire più istanze del Gateway sulla stessa macchina usando i profili:

- Ogni profilo ha configurazione, workspace, sessioni e stato separati
- Porte diverse per ogni Gateway
- Utile per l'isolamento (personale vs lavoro) o il testing

## Diagnostica

### Doctor

Lo strumento di diagnostica integrato controlla:

- Validità della configurazione
- Permessi dei file
- Connettività dei canali
- Stato dell'autenticazione dei modelli
- Compatibilità della versione Node.js
- Configurazioni errate comuni

Può correggere automaticamente molti problemi quando glielo viene permesso.

### Logging

I log del Gateway vengono scritti in file JSONL giornalieri:

- Tracciamento dell'utilizzo dei token per completamento
- Log degli eventi dei canali
- Log degli errori con contesto strutturato
- Livelli di log configurabili