# Aplikacje towarzyszące

## Czym są aplikacje towarzyszące?

Aplikacje towarzyszące to natywne aplikacje dla iOS, Android i macOS, które łączą się z Twoją bramą jako **węzły**. Węzły udostępniają możliwości urządzeń -- kamera, kanwa, nagrywanie ekranu, lokalizacja, głos i wykonywanie systemowe -- Twoim agentom.

Pomyśl o tym w ten sposób: brama to mózg, a aplikacje towarzyszące to ręce i oczy na Twoich urządzeniach.

## Jak działają węzły

1. **Połącz** -- Aplikacja towarzysząca łączy się z Twoją bramą przez WebSocket
2. **Paruj** -- Nowe urządzenia przechodzą przez proces zatwierdzania parowania
3. **Rejestruj możliwości** -- Aplikacja informuje bramę, co może robić (kamera, kanwa, lokalizacja itp.)
4. **Agenci wywołują** -- Podczas rozmów agenci mogą prosić węzeł o zrobienie zdjęcia, nagranie ekranu, renderowanie kanwy i więcej

Węzły **nie są bramami** -- nie uruchamiają własnego AI. To urządzenia peryferyjne, które rozszerzają możliwości Twoich agentów.

## Aplikacja towarzysząca macOS

Aplikacja macOS żyje na pasku menu i służy zarówno jako towarzyszący węzeł, jak i menedżer bramy.

### Możliwości
- **Kanwa** -- Renderuj interaktywne treści sieciowe w natywnym oknie
- **Kamera** -- Rób zdjęcia i klipy wideo (przód/tył)
- **Nagrywanie ekranu** -- Nagrywanie pełnoekranowe lub per aplikacja
- **Wykonywanie systemowe** -- Uruchamiaj polecenia powłoki na Macu (bramkowane przez zatwierdzenia exec)
- **Powiadomienia** -- Wysyłaj natywne powiadomienia macOS z opcjami priorytetów
- **Lokalizacja** -- GPS gdy dostępny

### Dodatkowe funkcje
- **Zarządzanie bramą** -- Uruchamiaj, zatrzymuj i monitoruj bramę
- **Własność uprawnień** -- Zarządza uprawnieniami TCC macOS (Powiadomienia, Dostępność, Nagrywanie ekranu, Mikrofon, Rozpoznawanie mowy, AppleScript)
- **Głębokie linki** -- Schemat URL `neotask://` do uruchamiania agentów z parametrami
- **Instalacja CLI** -- Instaluje narzędzie wiersza poleceń `neotask`

## Aplikacja iOS

Aplikacja iOS łączy się jako węzeł z Twoją bramą, bringing mobilne możliwości do Twoich agentów.

### Możliwości
- **Kanwa** -- Renderowanie interaktywnych treści oparte na SwiftUI
- **Kamera** -- Zdjęcia i klipy wideo (kamery przednia/tylna)
- **Nagrywanie audio** -- Przechwytywanie mikrofonu
- **Lokalizacja** -- GPS z wyborem dokładności
- **Powiadomienia** -- Natywne powiadomienia push iOS

### Funkcje
- **Odkrywanie** -- Znajduje Twoją bramę przez Bonjour (LAN), Tailscale (VPN) lub ręczne wprowadzanie
- **Parowanie** -- Bezpieczne parowanie urządzeń z zatwierdzeniem z bramy
- **Przebudzenie głosem** -- Aktywacja słowem aktywacyjnym dla interakcji bez użycia rąk
- **Tryb mówienia** -- Ciągła rozmowa głosowa
- **Rozszerzenie udostępniania** -- Udostępniaj treści z innych aplikacji bezpośrednio do agenta
- **A2UI** -- Renderowanie interfejsu użytkownika kierowanego przez agenta na kanwie urządzenia

### Ograniczenia
- Projekt z priorytetem dla pierwszego planu (iOS zawiesza połączenia WebSocket w tle)
- Ścisłe ograniczenia poleceń w tle
- Obecnie w wewnętrznym podglądzie

## Aplikacja Android

Aplikacja Android łączy się jako węzeł z możliwościami podobnymi do iOS.

### Możliwości
- **Kanwa** -- Renderowanie interfejsu użytkownika oparte na Jetpack Compose
- **Kamera** -- Zdjęcia i wideo (przód/tył, bramkowane uprawnieniami)
- **Nagrywanie ekranu** -- Przechwytywanie ekranu systemowego (Android 10+)
- **Lokalizacja** -- GPS z trybami dokładności
- **Wysyłanie SMS** -- Na urządzeniach z obsługą telefonii
- **Czat i historia** -- Wyświetlaj historię rozmów na urządzeniu

### Funkcje
- **Usługa w pierwszym planie** -- Trwałe powiadomienie utrzymuje aktywne połączenie
- **Udostępnione sesje** -- Ta sama sesja we wszystkich połączonych węzłach
- **Nowoczesny Android** -- Wymaga Android 12+ (API 31)

## Headless Node Host

Uruchamiaj węzeł bez żadnego interfejsu użytkownika -- idealny dla serwerów budowania, zdalnych maszyn lub bezgłowych skrzynek Linux.

### Możliwości
- **Wykonywanie systemowe** -- Uruchamiaj polecenia na hoście węzła
- **Lista dozwolonych poleceń** -- Konfiguruj, które polecenia węzeł może wykonywać
- **Usługa trwała** -- Instaluj jako usługę launchd/systemd

### Przypadki użycia
- Agenci CI/CD -- Pozwól agentowi AI wyzwalać kompilacje na zdalnym serwerze
- Automatyzacja domowego laboratorium -- Uruchamiaj polecenia na Raspberry Pi lub domowym serwerze
- Orkiestracja wielu maszyn -- Koordynuj zadania na wielu maszynach

## Parowanie urządzeń

### Przepływ parowania
1. Aplikacja towarzysząca prezentuje swoją tożsamość urządzenia (odcisk + klucz publiczny)
2. Brama wydaje żądanie zatwierdzenia parowania
3. Zatwierdzasz urządzenie przez aplikację desktopową lub panel sterowania
4. Brama wydaje token urządzenia dla przyszłych połączeń

### Model zaufania
- **Urządzenia lokalne** (pętla zwrotna) są automatycznie zatwierdzane dla wygody
- **Urządzenia nielokalne** wymagają wyraźnego zatwierdzenia
- Tokeny urządzeń są przechowywane lokalnie i ponownie używane przy ponownym połączeniu

## Zatwierdzenia Exec

Dla węzłów, które mogą uruchamiać polecenia systemowe (macOS, hosty headless), zatwierdzenia exec kontrolują, co jest dozwolone:

- **Tryb listy dozwolonych** -- Tylko wcześniej zatwierdzone polecenia mogą się wykonywać
- **Tryb pytania** -- Nieznane polecenia wymagają zatwierdzenia
- **Tryb pełny** -- Brak ograniczeń (używaj ostrożnie)

Konfiguruj listy dozwolonych per węzeł, aby precyzyjnie kontrolować, co każde urządzenie może robić.