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)

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).