# App Companion

## Cosa Sono le App Companion?

Le app companion sono applicazioni native per iOS, Android e macOS che si connettono al tuo Gateway come **nodi**. I nodi espongono le funzionalità del dispositivo, fotocamera, canvas, registrazione dello schermo, posizione, voce ed esecuzione di sistema, ai tuoi agenti.

Pensala in questo modo: il Gateway è il cervello, e le app companion sono le mani e gli occhi sui tuoi dispositivi.

## Come Funzionano i Nodi

1. **Connetti**, L'app companion si connette al tuo Gateway tramite WebSocket
2. **Abbina**, I nuovi dispositivi passano attraverso un processo di approvazione dell'abbinamento
3. **Registra le funzionalità**, L'app dice al Gateway cosa può fare (fotocamera, canvas, posizione, ecc.)
4. **Gli agenti invocano**, Durante le conversazioni, gli agenti possono richiedere al nodo di scattare una foto, registrare lo schermo, renderizzare un canvas e altro ancora

I nodi **non sono gateway**, non eseguono il proprio AI. Sono dispositivi periferici che estendono ciò che i tuoi agenti possono fare.

## App Companion macOS

L'app macOS vive nella barra dei menu e funge sia da nodo companion che da gestore del gateway.

### Funzionalità
- **Canvas**, Renderizza contenuto web interattivo in una finestra nativa
- **Fotocamera**, Scatta foto e clip video (frontale/posteriore)
- **Registrazione Schermo**, Registrazione a schermo intero o per app
- **Esecuzione di Sistema**, Esegui comandi shell sul Mac (con approvazione dell'esecuzione)
- **Notifiche**, Invia notifiche macOS native con opzioni di priorità
- **Posizione**, GPS quando disponibile

### Funzionalità Aggiuntive
- **Gestione del Gateway**, Avvia, arresta e monitora il Gateway
- **Gestione delle Autorizzazioni**, Gestisce le autorizzazioni TCC di macOS (Notifiche, Accessibilità, Registrazione Schermo, Microfono, Riconoscimento Vocale, AppleScript)
- **Deep Link**, Schema URL `neotask://` per avviare gli agenti con parametri
- **Installazione CLI**, Installa lo strumento da riga di comando `neotask`

## App iOS

L'app iOS si connette come nodo al tuo Gateway, portando le funzionalità mobili ai tuoi agenti.

### Funzionalità
- **Canvas**, Rendering di contenuto interattivo basato su SwiftUI
- **Fotocamera**, Foto e clip video (fotocamere frontale/posteriore)
- **Registrazione Audio**, Acquisizione del microfono
- **Posizione**, GPS con selezione della precisione
- **Notifiche**, Notifiche push iOS native

### Caratteristiche
- **Scoperta**, Trova il tuo Gateway tramite Bonjour (LAN), Tailscale (VPN) o inserimento manuale
- **Abbinamento**, Abbinamento sicuro del dispositivo con approvazione dal Gateway
- **Wake vocale**, Attivazione con parola di attivazione per interazione a mani libere
- **Modalità Talk**, Conversazione vocale continua
- **Estensione Condivisione**, Condividi contenuto da altre app direttamente al tuo agente
- **A2UI**, Rendering dell'interfaccia utente guidato dall'agente sul canvas del dispositivo

### Limitazioni
- Design principalmente in primo piano (iOS sospende le connessioni WebSocket in background)
- Rigide restrizioni ai comandi in background
- Attualmente in anteprima interna

## App Android

L'app Android si connette come nodo con funzionalità simili a iOS.

### Funzionalità
- **Canvas**, Rendering dell'interfaccia utente basato su Jetpack Compose
- **Fotocamera**, Foto e video (frontale/posteriore, con autorizzazione)
- **Registrazione Schermo**, Acquisizione dello schermo di sistema (Android 10+)
- **Posizione**, GPS con modalità di precisione
- **Invio SMS**, Sui dispositivi con supporto telefonico
- **Chat e Cronologia**, Visualizza la cronologia delle conversazioni sul dispositivo

### Caratteristiche
- **Servizio in Primo Piano**, La notifica persistente mantiene attiva la connessione
- **Sessioni Condivise**, Stessa sessione su tutti i nodi connessi
- **Android Moderno**, Richiede Android 12+ (API 31)

## Nodo Headless

Esegui un nodo senza alcuna interfaccia utente, ideale per server di build, macchine remote o box Linux headless.

### Funzionalità
- **Esecuzione di Sistema**, Esegui comandi sull'host del nodo
- **Elenco di Comandi Consentiti**, Configura quali comandi il nodo può eseguire
- **Servizio Persistente**, Installa come servizio launchd/systemd

### Casi d'Uso
- Agenti di build CI/CD, Lascia che il tuo agente AI attivi le build su un server remoto
- Automazione home lab, Esegui comandi su un Raspberry Pi o server domestico
- Orchestrazione multi-macchina, Coordina i compiti su più macchine

## Abbinamento dei Dispositivi

### Flusso di Abbinamento
1. L'app companion presenta la propria identità del dispositivo (impronta digitale + chiave pubblica)
2. Il Gateway emette una richiesta di approvazione dell'abbinamento
3. Tu approvi il dispositivo tramite l'app desktop o la dashboard
4. Il Gateway emette un token del dispositivo per le connessioni future

### Modello di Fiducia
- I **dispositivi locali** (loopback) vengono approvati automaticamente per comodità
- I **dispositivi non locali** richiedono l'approvazione esplicita
- I token del dispositivo vengono archiviati localmente e riutilizzati alla riconnessione

## Approvazioni di Esecuzione

Per i nodi in grado di eseguire comandi di sistema (macOS, host headless), le approvazioni di esecuzione controllano cosa è consentito:

- **Modalità elenco di ammissione**, Solo i comandi pre-approvati possono essere eseguiti
- **Modalità Ask**, I comandi sconosciuti richiedono la tua approvazione
- **Modalità completa**, Nessuna restrizione (usa con cautela)

Configura gli elenchi di ammissione per nodo per controllare con precisione cosa può fare ogni dispositivo.