# Apps Companion

## O Que Sao Apps Companion?

Apps companion sao aplicativos nativos para iOS, Android e macOS que se conectam ao seu Gateway como **nodes**. Nodes expoe capacidades do dispositivo -- camera, canvas, gravacao de tela, localizacao, voz e execucao de sistema -- para seus agentes.

Pense da seguinte forma: o Gateway e o cerebro, e os apps companion sao as maos e olhos nos seus dispositivos.

## Como os Nodes Funcionam

1. **Conectar** -- O app companion se conecta ao seu Gateway via WebSocket
2. **Parear** -- Novos dispositivos passam por um processo de aprovacao de pareamento
3. **Registrar capacidades** -- O app informa ao Gateway o que pode fazer (camera, canvas, localizacao, etc.)
4. **Agentes invocam** -- Durante conversas, agentes podem solicitar ao node para tirar foto, gravar tela, renderizar canvas e mais

Nodes **nao sao gateways** -- eles nao executam sua propria IA. Sao dispositivos perifericos que estendem o que seus agentes podem fazer.

## App Companion macOS

O app macOS fica na barra de menus e serve tanto como node companion quanto como gerenciador de gateway.

### Capacidades
- **Canvas** -- Renderize conteudo web interativo em uma janela nativa
- **Camera** -- Tire fotos e grave videoclipes (frontal/traseira)
- **Gravacao de Tela** -- Gravacao de tela inteira ou por app
- **Execucao de Sistema** -- Execute comandos shell no Mac (controlado por aprovacoes de exec)
- **Notificacoes** -- Envie notificacoes nativas do macOS com opcoes de prioridade
- **Localizacao** -- GPS quando disponivel

### Recursos Adicionais
- **Gerenciamento de Gateway** -- Inicie, pare e monitore o Gateway
- **Propriedade de Permissoes** -- Gerencia permissoes TCC do macOS (Notificacoes, Acessibilidade, Gravacao de Tela, Microfone, Reconhecimento de Fala, AppleScript)
- **Deep Links** -- Esquema de URL `neotask://` para iniciar agentes com parametros
- **Instalacao CLI** -- Instala a ferramenta de linha de comando `neotask`

## App iOS

O app iOS se conecta como um node ao seu Gateway, trazendo capacidades moveis para seus agentes.

### Capacidades
- **Canvas** -- Renderizacao de conteudo interativo baseado em SwiftUI
- **Camera** -- Fotos e videoclipes (cameras frontal/traseira)
- **Gravacao de Audio** -- Captura de microfone
- **Localizacao** -- GPS com selecao de precisao
- **Notificacoes** -- Notificacoes push nativas do iOS

### Recursos
- **Descoberta** -- Encontra seu Gateway via Bonjour (LAN), Tailscale (VPN) ou entrada manual
- **Pareamento** -- Pareamento seguro de dispositivo com aprovacao do Gateway
- **Despertar por Voz** -- Ativacao por palavra de ativacao para interacao maos-livres
- **Modo de Conversa** -- Conversa por voz continua
- **Extensao de Compartilhamento** -- Compartilhe conteudo de outros apps diretamente para seu agente
- **A2UI** -- Renderizacao de UI dirigida por agente no canvas do dispositivo

### Limitacoes
- Design prioriza primeiro plano (iOS suspende conexoes WebSocket em segundo plano)
- Restricoes estritas de comandos em segundo plano
- Atualmente em preview interno

## App Android

O app Android se conecta como um node com capacidades similares ao iOS.

### Capacidades
- **Canvas** -- Renderizacao de UI baseada em Jetpack Compose
- **Camera** -- Fotos e video (frontal/traseira, controlado por permissao)
- **Gravacao de Tela** -- Captura de tela do sistema (Android 10+)
- **Localizacao** -- GPS com modos de precisao
- **Envio de SMS** -- Em dispositivos com suporte a telefonia
- **Chat e Historico** -- Visualize historico de conversas no dispositivo

### Recursos
- **Servico em Primeiro Plano** -- Notificacao persistente mantem a conexao ativa
- **Sessoes Compartilhadas** -- Mesma sessao em todos os nodes conectados
- **Android Moderno** -- Requer Android 12+ (API 31)

## Host de Node Headless

Execute um node sem nenhuma UI -- ideal para servidores de build, maquinas remotas ou caixas Linux headless.

### Capacidades
- **Execucao de Sistema** -- Execute comandos no host do node
- **Lista de Permissao de Comandos** -- Configure quais comandos o node pode executar
- **Servico Persistente** -- Instale como servico launchd/systemd

### Casos de Uso
- Agentes de build CI/CD -- Permita que seu agente de IA acione builds em um servidor remoto
- Automacao de home lab -- Execute comandos em um Raspberry Pi ou servidor domestico
- Orquestracao multi-maquina -- Coordene tarefas entre multiplas maquinas

## Pareamento de Dispositivos

### Fluxo de Pareamento
1. App companion apresenta sua identidade de dispositivo (fingerprint + chave publica)
2. Gateway emite uma solicitacao de aprovacao de pareamento
3. Voce aprova o dispositivo pelo app desktop ou dashboard
4. Gateway emite um token de dispositivo para conexoes futuras

### Modelo de Confianca
- **Dispositivos locais** (loopback) sao auto-aprovados por conveniencia
- **Dispositivos nao-locais** requerem aprovacao explicita
- Tokens de dispositivo sao armazenados localmente e reutilizados na reconexao

## Aprovacoes de Exec

Para nodes que podem executar comandos de sistema (macOS, hosts headless), aprovacoes de exec controlam o que e permitido:

- **Modo lista de permissao** -- Apenas comandos pre-aprovados podem executar
- **Modo perguntar** -- Comandos desconhecidos solicitam sua aprovacao
- **Modo completo** -- Sem restricoes (use com cautela)

Configure listas de permissao por node para controlar precisamente o que cada dispositivo pode fazer.