# Companion Apps

## Companion Apps क्या हैं?

Companion apps iOS, Android, और macOS के लिए native applications हैं जो आपके Gateway से **nodes** के रूप में connect होते हैं। Nodes device capabilities expose करते हैं, camera, canvas, screen recording, location, voice, और system execution, आपके agents को।

इसे इस तरह समझें: Gateway brain है, और companion apps आपके devices पर hands और eyes हैं।

## Nodes कैसे काम करते हैं

1. **Connect**, Companion app आपके Gateway से WebSocket पर connect होता है
2. **Pair**, नए devices एक pairing approval process से गुजरते हैं
3. **Register capabilities**, App Gateway को बताता है कि वह क्या कर सकता है (camera, canvas, location, आदि)
4. **Agents invoke**, Conversations के दौरान, agents node से photo लेने, screen record करने, canvas render करने, और अधिक करने का request कर सकते हैं

Nodes **gateways नहीं हैं**, वे अपना AI नहीं चलाते। वे peripheral devices हैं जो आपके agents क्या कर सकते हैं उसे extend करते हैं।

## macOS Companion App

macOS app आपके menu bar में रहता है और companion node और gateway manager दोनों के रूप में serve करता है।

### Capabilities
- **Canvas**, एक native window में interactive web content render करें
- **Camera**, Photos और video clips लें (front/back)
- **Screen Recording**, Full-screen या per-app recording
- **System Execution**, Mac पर shell commands run करें (exec approvals द्वारा gated)
- **Notifications**, Priority options के साथ native macOS notifications भेजें
- **Location**, उपलब्ध होने पर GPS

### Additional Features
- **Gateway Management**, Gateway start, stop, और monitor करें
- **Permission Ownership**, macOS TCC permissions manage करता है (Notifications, Accessibility, Screen Recording, Microphone, Speech Recognition, AppleScript)
- **Deep Links**, Parameters के साथ agents launch करने के लिए `neotask://` URL scheme
- **CLI Install**, `neotask` command-line tool install करता है

## iOS App

iOS app आपके Gateway से node के रूप में connect होता है, आपके agents को mobile capabilities लाता है।

### Capabilities
- **Canvas**, SwiftUI-based interactive content rendering
- **Camera**, Photos और video clips (front/back cameras)
- **Audio Recording**, Microphone capture
- **Location**, Accuracy selection के साथ GPS
- **Notifications**, Native iOS push notifications

### Features
- **Discovery**, Bonjour (LAN), Tailscale (VPN), या manual entry के माध्यम से आपका Gateway ढूंढता है
- **Pairing**, Gateway से approval के साथ secure device pairing
- **Voice Wake**, Hands-free interaction के लिए wake word activation
- **Talk Mode**, Continuous voice conversation
- **Share Extension**, दूसरे apps से directly आपके agent को content share करें
- **A2UI**, Device canvas पर Agent-driven UI rendering

### Limitations
- Foreground-first design (iOS background में WebSocket connections suspend करता है)
- Strict background command restrictions
- वर्तमान में internal preview में

## Android App

Android app iOS के समान capabilities के साथ node के रूप में connect होता है।

### Capabilities
- **Canvas**, Jetpack Compose-based UI rendering
- **Camera**, Photos और video (front/back, permission-gated)
- **Screen Recording**, System screen capture (Android 10+)
- **Location**, Accuracy modes के साथ GPS
- **SMS Sending**, Telephony support वाले devices पर
- **Chat & History**, Device पर conversation history देखें

### Features
- **Foreground Service**, Persistent notification connection alive रखता है
- **Shared Sessions**, सभी connected nodes में same session
- **Modern Android**, Android 12+ (API 31) आवश्यक

## Headless Node Host

बिना किसी UI के node run करें, build servers, remote machines, या headless Linux boxes के लिए ideal।

### Capabilities
- **System Execution**, Node host पर commands run करें
- **Command Allowlist**, Configure करें कि node कौन से commands execute कर सकता है
- **Persistent Service**, launchd/systemd service के रूप में install करें

### Use Cases
- CI/CD build agents, अपने AI agent को remote server पर builds trigger करने दें
- Home lab automation, Raspberry Pi या home server पर commands run करें
- Multi-machine orchestration, Multiple machines में tasks coordinate करें

## Device Pairing

### Pairing Flow
1. Companion app अपनी device identity (fingerprint + public key) present करता है
2. Gateway एक pairing approval request issue करता है
3. आप desktop app या dashboard के माध्यम से device approve करते हैं
4. Gateway future connections के लिए device token issue करता है

### Trust Model
- **Local devices** (loopback) सुविधा के लिए auto-approved होते हैं
- **Non-local devices** को explicit approval आवश्यक है
- Device tokens locally stored होते हैं और reconnect पर reuse होते हैं

## Exec Approvals

उन nodes के लिए जो system commands run कर सकते हैं (macOS, headless hosts), exec approvals control करते हैं कि क्या allowed है:

- **Allowlist mode**, केवल pre-approved commands execute हो सकते हैं
- **Ask mode**, Unknown commands आपसे approval के लिए prompt करते हैं
- **Full mode**, कोई restrictions नहीं (सावधानी के साथ उपयोग करें)

Per-node allowlists configure करें precisely control करने के लिए कि प्रत्येक device क्या कर सकता है।