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.