docs(android-agent): Design fuer nativen Android-Agenten (Pfad B)

Nativer Kotlin-Agent unter host-agent/android/ zur Handy-Fernsteuerung inkl.
Bedienen fremder App-UIs (E-Mail-Setup) via AccessibilityService. Verbindung wie
die ARIA-App (QR-Scan/manuell), erscheint in der Diagnostic (host_hello).

Festgehalten: Android-Action-Set (screenshot/ui_dump/ui_tap/ui_text/ui_swipe/
ui_key/app_launch/info/notify statt Shell), Sicherheit (CONTROL_ENABLED + explizite
Accessibility/MediaProjection-Freigabe), Dauerbetrieb (A: Foreground-Service —
einfach, reutzt host_command 1:1; B: FCM-Push wie WhatsApp — akkuschonend, spaeter),
4 Meilensteine, Build via Docker/Gradle + release.sh <version> -> Gitea-Asset.

Status: Design. Naechster Schritt: Meilenstein 1 (Verbinden + sichtbar).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

host-agent/android/README.md

@@ -0,0 +1,111 @@
+# 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).