ARIA-AGENT/host-agent/android/README.md

# ARIA Android-Agent

Ein **nativer Android-Agent** (eigene APK), der ARIA erlaubt, ein Smartphone
**fernzusteuern** — inkl. Bedienen fremder App-UIs (z.B. „ARIA, richte auf dem
Handy ein E-Mail-Konto ein"). Gegenstück zum Desktop-`host-agent` (Linux/macOS/
Windows), aber Android ist kein Unix-Shell-System — deshalb ein **anderes
Action-Set** (UI-Automation statt beliebiger Shell-Kommandos).

Verbindet sich wie die ARIA-App **ausgehend** zum RVS (gleicher Token/Raum),
Verbindungs-Setup per **QR-Scan oder manueller Eingabe**. Taucht in der
Diagnostic unter **Satelliten → Host-Agenten 💻** auf (`host_hello` mit
`os="Android …"` + Android-Caps).

## Warum nativ (Kotlin), nicht Termux/RN

- **UI-Automation** (fremde Apps bedienen) geht auf Android nur über einen
  **AccessibilityService** — den kann nur eine native App bereitstellen.
- **Screenshots** einer laufenden Session: **MediaProjection** (native).
- **Dauerbetrieb**: Foreground-Service mit Notification (native).
- Termux gäbe nur Shell + `termux-api` (SMS/Anruf/Standort …), **kein** Bedienen
  anderer App-UIs. Für „E-Mail-Konto durchklicken" reicht das nicht.

Tech: **Kotlin**, OkHttp-WebSocket (RVS-Client), CameraX/ML-Kit (QR),
AccessibilityService (Input), MediaProjection (Screenshot). Build via Docker
(Android-SDK + Gradle) → APK. Nur Linux baut APKs (Docker), Deploy manuell.

## Action-Set (host_command → host_result)

Android-spezifisch (statt exec/read/write des Desktop-Agents):

| Action | Was |
|---|---|
| `screenshot`   | Bildschirmfoto (MediaProjection) — ARIA *sieht* den Schirm |
| `ui_dump`      | Sichtbare UI als Baum (Texte, Buttons, Felder + Koordinaten) — ARIAs „Augen" für gezieltes Tippen |
| `ui_tap`       | Tippen (x,y ODER auf ein Element aus ui_dump) |
| `ui_text`      | Text in das fokussierte/angegebene Feld schreiben |
| `ui_swipe`     | Wischen/Scrollen |
| `ui_key`       | Systemtasten (BACK, HOME, ENTER …) |
| `app_launch`   | App per Paketname starten (z.B. E-Mail-App) |
| `app_list`     | installierte Apps auflisten |
| `info`         | Gerät: Modell, Android-Version, Akku, Netz, IP |
| `notify`       | Benachrichtigung anzeigen |
| *(später)*     | `sms_send`, `call`, `location`, `clipboard` (je nach Bedarf + Berechtigung) |

ARIA-Flow „E-Mail einrichten": `app_launch` (Mail-App) → `screenshot`/`ui_dump`
(sehen, was da ist) → `ui_tap`/`ui_text` (durchklicken) → wieder `ui_dump` prüfen,
bis fertig. Genau das agentische Muster wie beim Endian-Fix, nur mit Handy-UI.

## Dauerbetrieb — Foreground-Service vs. Push (FCM)

Der Agent muss **immer erreichbar** sein, obwohl Android Hintergrundprozesse
aggressiv killt (Doze, App-Standby, OEM-Batterie-Manager wie Xiaomi/Huawei).
Zwei Wege, deine WhatsApp-Intuition trifft ins Schwarze:

**A) Foreground-Service (persistente WebSocket)** — der einfache Start:
- Dauerhafte RVS-Verbindung + Foreground-Notification („Agent aktiv").
- Braucht: `FOREGROUND_SERVICE`, **Akku-Optimierung ausnehmen**
  (`REQUEST_IGNORE_BATTERY_OPTIMIZATIONS` — User whitelistet die App),
  `RECEIVE_BOOT_COMPLETED` + BootReceiver (Neustart nach Reboot), Auto-Reconnect
  (haben wir im Protokoll schon).
- **Reutzt unser bestehendes `host_hello`/`host_command`/`host_result` 1:1.**
- Nachteil: etwas Akku; manche OEMs killen trotzdem → „Autostart" manuell erlauben.

**B) Push (Firebase Cloud Messaging)** — genau wie WhatsApp/Telegram:
- Kein 24/7-Socket. Die App registriert sich bei FCM; will ARIA etwas, schickt
  der **Server einen Push** → Android weckt die App (auch aus Doze) → sie holt
  den Befehl vom RVS, führt ihn aus, antwortet. Da der Agent primär **empfängt**,
  passt das perfekt und ist akkuschonend/zuverlässig.
- Nachteil: braucht **Firebase-Projekt** + **Google Play Services** aufm Gerät +
  einen **Push-Auslöser serverseitig** (RVS/Bridge feuert bei `host_command` einen
  FCM-Push an das Ziel-Gerät). Mehr Plumbing.

**Empfehlung:** Meilenstein 1–3 mit **A (Foreground-Service)** — läuft sofort,
nutzt alles Vorhandene. **B (FCM)** als spätere Robustheits-/Akku-Stufe, wenn A im
Alltag zu oft eingeschläfert wird. Das Action-Set bleibt identisch, nur der
Wecker (Socket vs. Push) ändert sich.

## Sicherheit

- Reagiert nur auf den eigenen RVS-Raum (Token); Setup per QR/manuell.
- **CONTROL_ENABLED**-Schalter in der App (Default AUS) — erst wenn Stefan es
  bewusst aktiviert, führt der Agent Aktionen aus.
- AccessibilityService + MediaProjection müssen vom User **explizit** in den
  Android-Einstellungen freigegeben werden (kein stiller Zugriff möglich).
- Alle Aktionen werden protokolliert (In-App-Log + optional an ARIA).
- Voller Gerätezugriff — nur auf eigenen/anvertrauten Geräten nutzen.

## Meilensteine

1. **Verbinden + sichtbar** — Gradle-Projekt, AndroidManifest, RVS-WS-Client,
   Foreground-Service, Connect-UI (QR-Scan + manuell), `host_hello`/`host_ping`.
   → Agent erscheint in der Diagnostic. Noch keine Steuerung.
2. **Sehen** — MediaProjection-Screenshot + `ui_dump` (AccessibilityService,
   read-only). → ARIA kann den Schirm ansehen und beschreiben.
3. **Steuern** — `ui_tap`/`ui_text`/`ui_swipe`/`ui_key`/`app_launch` über den
   AccessibilityService. → ARIA bedient Apps (E-Mail-Setup).
4. **Feinschliff** — `info`/`app_list`/`notify`, Build-Härtung, `release.sh`
   (Version-Param → Gitea-Release-Asset, wie die App).

## Build & Release (geplant)

```bash
cd host-agent/android
./build.sh                 # Docker (Android-SDK+Gradle) -> aria-android-agent.apk
./release.sh 0.1.0         # baut, taggt, laedt APK als Gitea-Release-Asset hoch
```

APK wird manuell aufs Zielgerät kopiert + installiert (unbekannte Quellen
erlauben). Gitea-Release macht den Download einfach (wie die Haupt-App).

> Status: **Design.** Als Nächstes Meilenstein 1 (Verbinden + sichtbar).