# Додатки-компаньйони

## Що таке додатки-компаньйони?

Додатки-компаньйони, це нативні застосунки для iOS, Android та macOS, які підключаються до вашого Gateway як **вузли**. Вузли надають агентам можливості пристрою, камеру, полотно, запис екрана, геолокацію, голос та виконання системних команд.

Думайте про це так: Gateway, це мозок, а додатки-компаньйони, це руки та очі на ваших пристроях.

## Як працюють вузли

1. **Підключення**, Додаток-компаньйон підключається до вашого Gateway через WebSocket
2. **Спарювання**, Нові пристрої проходять процес затвердження спарювання
3. **Реєстрація можливостей**, Застосунок повідомляє Gateway, що він може робити (камера, полотно, геолокація тощо)
4. **Виклики агентів**, Під час розмов агенти можуть запитувати вузол зробити фото, записати екран, відрендерити полотно тощо

Вузли, це **не Gateway**, вони не запускають власний AI. Це периферійні пристрої, що розширюють можливості ваших агентів.

## Застосунок для macOS

Застосунок для macOS живе у рядку меню і слугує одночасно компаньйонним вузлом і менеджером Gateway.

### Можливості
- **Полотно**, Рендеринг інтерактивного веб-контенту у нативному вікні
- **Камера**, Фото та відеокліпи (передня/задня)
- **Запис екрана**, Запис повного екрана або окремих застосунків
- **Виконання системних команд**, Запуск команд оболонки на Mac (з перевіркою дозволів)
- **Сповіщення**, Відправка нативних сповіщень macOS з параметрами пріоритету
- **Геолокація**, GPS при наявності

### Додаткові функції
- **Управління Gateway**, Запуск, зупинка та моніторинг Gateway
- **Управління дозволами**, Керування дозволами macOS TCC (сповіщення, доступність, запис екрана, мікрофон, розпізнавання мовлення, AppleScript)
- **Глибокі посилання**, Схема URL `neotask://` для запуску агентів з параметрами
- **Встановлення CLI**, Встановлює інструмент командного рядка `neotask`

## iOS-застосунок

iOS-застосунок підключається як вузол до вашого Gateway, надаючи агентам можливості мобільного пристрою.

### Можливості
- **Полотно**, Рендеринг інтерактивного контенту на основі SwiftUI
- **Камера**, Фото та відеокліпи (передня/задня камери)
- **Запис аудіо**, Захоплення мікрофону
- **Геолокація**, GPS з вибором точності
- **Сповіщення**, Нативні push-сповіщення iOS

### Функції
- **Виявлення**, Знаходить ваш Gateway через Bonjour (локальна мережа), Tailscale (VPN) або ручне введення
- **Спарювання**, Безпечне спарювання пристрою із затвердженням від Gateway
- **Активація ключовим словом**, Активація ключовим словом для роботи без рук
- **Режим розмови**, Безперервна голосова розмова
- **Розширення для обміну**, Ділення контентом з інших застосунків безпосередньо з вашим агентом
- **A2UI**, Рендеринг UI, керований агентом, на полотні пристрою

### Обмеження
- Дизайн, орієнтований на передній план (iOS призупиняє WebSocket-з'єднання у фоновому режимі)
- Жорсткі обмеження фонових команд
- Наразі у внутрішньому попередньому перегляді

## Android-застосунок

Android-застосунок підключається як вузол з можливостями, схожими на iOS.

### Можливості
- **Полотно**, Рендеринг UI на основі Jetpack Compose
- **Камера**, Фото та відео (передня/задня, з дозволу)
- **Запис екрана**, Захоплення системного екрана (Android 10+)
- **Геолокація**, GPS з режимами точності
- **Надсилання SMS**, На пристроях з підтримкою телефонії
- **Чат та історія**, Перегляд історії розмов на пристрої

### Функції
- **Служба переднього плану**, Постійне сповіщення підтримує з'єднання активним
- **Спільні сесії**, Одна сесія для всіх підключених вузлів
- **Сучасний Android**, Вимагає Android 12+ (API 31)

## Безголовий хост вузла

Запускайте вузол без будь-якого інтерфейсу, ідеально для серверів збірки, віддалених машин або безголових Linux-систем.

### Можливості
- **Виконання системних команд**, Запуск команд на хості вузла
- **Дозволений список команд**, Налаштування дозволених для виконання команд
- **Постійна служба**, Встановлення як служби launchd/systemd

### Сценарії використання
- Агенти збірки CI/CD, Дозвольте вашому AI-агенту ініціювати збірки на віддаленому сервері
- Автоматизація домашньої лабораторії, Виконуйте команди на Raspberry Pi або домашньому сервері
- Оркестрація кількох машин, Координуйте задачі між кількома машинами

## Спарювання пристроїв

### Процес спарювання
1. Додаток-компаньйон надає своє ідентифікаційне підтвердження (відбиток + відкритий ключ)
2. Gateway видає запит на затвердження спарювання
3. Ви затверджуєте пристрій через настільний застосунок або панель
4. Gateway видає токен пристрою для майбутніх підключень

### Модель довіри
- **Локальні пристрої** (зворотна петля) автоматично затверджуються для зручності
- **Нелокальні пристрої** вимагають явного затвердження
- Токени пристроїв зберігаються локально та повторно використовуються при перепідключенні

## Дозволи на виконання

Для вузлів, що можуть запускати системні команди (macOS, безголові хости), дозволи на виконання контролюють, що дозволено:

- **Режим дозволеного списку**, Виконуватися можуть лише попередньо схвалені команди
- **Режим запиту**, Невідомі команди запитують ваше затвердження
- **Повний режим**, Без обмежень (використовуйте обережно)

Налаштовуйте дозволені списки для кожного вузла, щоб точно контролювати, що може робити кожен пристрій.