# 동반 앱

## 동반 앱이란 무엇인가?

동반 앱은 **노드**로서 게이트웨이에 연결하는 iOS, Android, macOS용 네이티브 애플리케이션입니다. 노드는 기기 기능, 카메라, 캔버스, 화면 녹화, 위치, 음성, 시스템 실행, 을 에이전트에 노출합니다.

이렇게 생각하면 됩니다: 게이트웨이는 두뇌이고, 동반 앱은 기기의 손과 눈입니다.

## 노드 작동 방식

1. **연결**, 동반 앱이 WebSocket을 통해 게이트웨이에 연결합니다
2. **페어링**, 새 기기는 페어링 승인 과정을 거칩니다
3. **기능 등록**, 앱이 할 수 있는 것(카메라, 캔버스, 위치 등)을 게이트웨이에 알립니다
4. **에이전트 호출**, 대화 중에 에이전트는 노드에게 사진 촬영, 화면 녹화, 캔버스 렌더링 등을 요청할 수 있습니다

노드는 **게이트웨이가 아닙니다**, 자체 AI를 실행하지 않습니다. 에이전트가 할 수 있는 것을 확장하는 주변 기기입니다.

## macOS 동반 앱

macOS 앱은 메뉴 바에 위치하며 동반 노드와 게이트웨이 관리자 역할을 모두 합니다.

### 기능
- **캔버스**, 네이티브 창에서 인터랙티브 웹 콘텐츠를 렌더링합니다
- **카메라**, 사진 및 비디오 클립 촬영 (전면/후면)
- **화면 녹화**, 전체 화면 또는 앱별 녹화
- **시스템 실행**, Mac에서 셸 명령 실행 (실행 승인으로 제한)
- **알림**, 우선순위 옵션이 있는 네이티브 macOS 알림 전송
- **위치**, 가능한 경우 GPS

### 추가 기능
- **게이트웨이 관리**, 게이트웨이 시작, 중지, 모니터링
- **권한 소유권**, macOS TCC 권한 관리 (알림, 접근성, 화면 녹화, 마이크, 음성 인식, AppleScript)
- **딥 링크**, 매개변수가 있는 에이전트를 시작하는 `neotask://` URL 스킴
- **CLI 설치**, `neotask` 명령줄 도구 설치

## iOS 앱

iOS 앱은 게이트웨이의 노드로 연결되어 에이전트에 모바일 기능을 제공합니다.

### 기능
- **캔버스**, SwiftUI 기반 인터랙티브 콘텐츠 렌더링
- **카메라**, 사진 및 비디오 클립 (전면/후면 카메라)
- **오디오 녹음**, 마이크 캡처
- **위치**, 정확도 선택이 있는 GPS
- **알림**, 네이티브 iOS 푸시 알림

### 특징
- **발견**, Bonjour(LAN), Tailscale(VPN), 또는 수동 입력을 통해 게이트웨이를 찾습니다
- **페어링**, 게이트웨이의 승인을 통한 안전한 기기 페어링
- **음성 웨이크**, 핸즈프리 상호작용을 위한 웨이크 워드 활성화
- **토크 모드**, 연속 음성 대화
- **공유 확장**, 다른 앱에서 에이전트로 직접 콘텐츠 공유
- **A2UI**, 기기 캔버스에서 에이전트 구동 UI 렌더링

### 제한 사항
- 포그라운드 우선 설계 (iOS는 백그라운드에서 WebSocket 연결을 중단합니다)
- 엄격한 백그라운드 명령 제한
- 현재 내부 프리뷰 중

## Android 앱

Android 앱은 iOS와 유사한 기능을 갖춘 노드로 연결됩니다.

### 기능
- **캔버스**, Jetpack Compose 기반 UI 렌더링
- **카메라**, 사진 및 비디오 (전면/후면, 권한 제한)
- **화면 녹화**, 시스템 화면 캡처 (Android 10+)
- **위치**, 정확도 모드가 있는 GPS
- **SMS 전송**, 전화 지원이 있는 기기에서
- **채팅 및 기록**, 기기에서 대화 기록 보기

### 특징
- **포그라운드 서비스**, 연결을 유지하는 영구 알림
- **공유 세션**, 연결된 모든 노드에서 동일한 세션
- **최신 Android**, Android 12+ (API 31) 필요

## 헤드리스 노드 호스트

빌드 서버, 원격 머신, 헤드리스 Linux 박스에 이상적인 UI 없이 노드를 실행합니다.

### 기능
- **시스템 실행**, 노드 호스트에서 명령 실행
- **명령 허용 목록**, 노드가 실행할 수 있는 명령 구성
- **영구 서비스**, launchd/systemd 서비스로 설치

### 사용 사례
- CI/CD 빌드 에이전트, AI 에이전트가 원격 서버에서 빌드를 트리거하도록 합니다
- 홈 랩 자동화, Raspberry Pi 또는 홈 서버에서 명령 실행
- 다중 머신 오케스트레이션, 여러 머신에 걸쳐 작업 조율

## 기기 페어링

### 페어링 흐름
1. 동반 앱이 기기 정체성(지문 + 공개 키)을 제시합니다
2. 게이트웨이가 페어링 승인 요청을 발행합니다
3. 귀하가 데스크톱 앱 또는 대시보드를 통해 기기를 승인합니다
4. 게이트웨이가 향후 연결을 위한 기기 토큰을 발행합니다

### 신뢰 모델
- **로컬 기기**(루프백)는 편의를 위해 자동으로 승인됩니다
- **비로컬 기기**는 명시적인 승인이 필요합니다
- 기기 토큰은 로컬에 저장되고 재연결 시 재사용됩니다

## 실행 승인

시스템 명령을 실행할 수 있는 노드(macOS, 헤드리스 호스트)의 경우 실행 승인으로 허용되는 것을 제어합니다:

- **허용 목록 모드**, 사전 승인된 명령만 실행할 수 있습니다
- **묻기 모드**, 알 수 없는 명령은 승인을 요청합니다
- **전체 모드**, 제한 없음 (주의해서 사용)

각 기기가 할 수 있는 것을 정확히 제어하기 위해 노드별 허용 목록을 구성합니다.