nsaspy/a0-symbolics

Fork 0

EPIC: first-class Android shell for full Agent Zero WebUI + plugin compatibility #184

New issue

Open

opened 2026-09-09 15:05:28 +00:00 by nsaspy · 0 comments

nsaspy commented

2026-09-09 15:05:28 +00:00

Owner

Goal

Build a modern Android application for a0-symbolics that provides a first-class mobile experience for a remote or local Agent Zero instance without reimplementing Agent Zero in Kotlin.

The Android app should be a polished native shell around the authoritative Agent Zero WebUI. The WebUI, its service worker, WebSockets, authentication/CSRF behavior, full plugin UI/extensions, and future WebUI changes remain authoritative.

This is intentionally a hybrid native shell + real WebView architecture:

Jetpack Compose / Material 3 Expressive for native Android chrome, setup, server profiles, permissions, connection state, and platform integration.
Android WebView for the actual Agent Zero UI and every plugin-owned UI surface.
Minimal, version-tolerant mobile optimization injected around the WebUI rather than a parallel Android client that would strand plugins.

Related: #23 modern WebUI/plugin surface architecture. This Android epic must work against the current WebUI and must not be blocked on #23.

Architecture requirements

1. Repository boundary

Create an android/ application boundary in this repository with its own AGENTS.md documenting ownership, build/test commands, security rules, and WebView compatibility contracts.

Do not modify agent.py or initialize.py for the Android client.

The Android app connects to a running Agent Zero instance over its normal WebUI origin. No Android-only backend fork.

2. Native Android shell

Use modern Android UI and platform conventions:

Kotlin
Jetpack Compose
Material 3 / Material 3 Expressive where stable enough
edge-to-edge layout
predictive back-compatible navigation
dark/light/system theme support
dynamic color as an optional preference, with an Agent Zero-branded default theme
adaptive layouts for phone, foldable/tablet and landscape
touch targets and typography suitable for mobile

The in-session WebView should remain visually dominant. Native chrome must be compact and collapsible rather than wasting screen space.

3. Connection profiles

Provide a native first-run/server selector that supports multiple Agent Zero instances.

Each profile should contain only non-secret connection metadata such as:

display name
base URL
optional color/icon metadata

Requirements:

support both https:// and http:// endpoints so LAN/local Agent Zero instances work
normalize trailing slashes and reject malformed/non-http(s) schemes
persist profiles locally
allow switching instances without reinstalling the app
remember the last active profile
provide a clear visual warning for plaintext HTTP rather than silently pretending it is secure

Authentication itself remains Agent Zero's WebUI/auth flow so credentials and CSRF semantics are not duplicated in Android.

4. WebView compatibility contract

The WebView is the compatibility layer and must behave close to Chrome for Agent Zero's same-origin UI.

Required:

JavaScript enabled
DOM storage enabled
cookies enabled
third-party cookies where required for supported auth flows
WebSockets work normally
service workers and Cache Storage remain available
Agent Zero's /, /safe, /ui/index, bundle/cache bootstrap and login flows remain functional
same-origin navigation remains inside the app
window.open / external links have an intentional mobile behavior
no unsafe generic addJavascriptInterface bridge exposed to arbitrary pages
Web contents debugging only in debug builds
preserve WebUI auth/CSRF/origin assumptions
do not intercept or rewrite Agent Zero API/WebSocket traffic

For HTTPS profiles, do not weaken TLS validation or auto-accept certificate errors.

For HTTP profiles, allow cleartext traffic intentionally and visibly mark the connection as insecure.

5. Plugin compatibility is a release gate

Existing Agent Zero plugins must continue to work because their HTML/JS/CSS runs in the same WebUI origin and extension system.

Compatibility includes:

<x-extension> frontend breakpoints
JS extensions
<x-component> loading
plugin modals/settings
plugin-owned full pages/surfaces
plugin API handlers
plugin WebSocket/event flows
plugin static assets
Plugin Hub / install / configuration flows
bundled and third-party plugin UI

Do not create an Android-only plugin API as the primary path.

The app may expose a tiny, versioned native capability marker to the same configured Agent Zero origin if useful, but plugins must not need Android-specific code to function.

6. Mobile optimization without DOM fragility

Mobile optimizations must be additive and conservative.

Use a stable app marker such as a user-agent suffix and/or a root document attribute inserted at document start. Prefer CSS custom properties / capability markers to brittle selector rewrites.

Good candidates:

safe-area/inset variables
touch/long-press polish
prevent tiny form controls from triggering unwanted viewport zoom
keyboard/IME resize handling
mobile viewport height handling
overscroll behavior
native status/chrome spacing
optional mobile density mode

Do not hide or rewrite arbitrary plugin DOM. Unknown plugin pages must render unmodified by default.

7. Full interaction support

The Android app must support the platform glue needed to use Agent Zero fully from a phone:

HTML file upload chooser, including multiple files where requested
Android document picker/content URIs
downloads through Android's download UX
clipboard copy/paste
long-press/select/copy
microphone permission for voice/STT/plugin surfaces
camera permission when a WebUI/plugin explicitly requests it
fullscreen/custom-view handling for media/remote surfaces
native back behavior with WebView history
forward/reload/home controls
share current URL / selected Agent Zero URL
open external URLs in an appropriate Android browser/custom tab path
graceful offline/unreachable-server screen with retry and profile switching
process-death/state restoration where safe
orientation changes without losing the current session unnecessarily

Agent Zero features that must remain usable include at least:

chat
attachments
projects/profiles
tasks
files
settings/model configuration
plugins / Plugin Hub
Browser surface
Desktop surface
terminal/code-execution surfaces
editor/document surfaces
onboarding and OAuth-related setup flows

8. Security

never commit Agent Zero passwords, API tokens, cookies or signing secrets
WebView permissions are origin-scoped and user-mediated
only the configured Agent Zero origin receives any future native bridge/capability messages
external origins must never inherit privileged Android bridge access
reject file:, content:, javascript: and unexpected custom-scheme top-level navigation unless an explicit safe handler exists
no TLS error bypass
no global arbitrary certificate trust override
clear browsing/session data action in Settings
optional biometric/app-lock can be a later slice; it must not replace Agent Zero authentication

9. Build target

Target Android 16 / API 36 and remain compatible with a reasonable older-phone floor (prefer minSdk 26+ unless implementation evidence requires otherwise).

Use current Android Gradle Plugin/Kotlin/Compose versions that support API 36.

10. CI and installable artifacts

Add Android CI under .github/workflows/:

Gradle build
unit tests
Android lint
debug APK build
upload APK as a GitHub Actions artifact

Design release signing so secrets can be supplied through GitHub Actions secrets; do not commit a production signing key.

When signing secrets are present, release workflow should be able to produce a signed installable APK. Debug artifacts must remain clearly labeled as debug/dev builds.

11. Testing

At minimum cover:

Unit tests

URL normalization/validation
connection profile persistence model
navigation-origin policy
permission-origin policy
external link routing

Instrumented/UI tests

first-run profile creation
HTTP and HTTPS profile selection
WebView loads an Agent Zero login/main page fixture
back/forward/reload behavior
file chooser callback
offline -> retry recovery
configuration survives recreation

Manual compatibility matrix

current a0-symbolics WebUI
current Chrome/System WebView stable
phone portrait/landscape
Android 15 and Android 16
Samsung One UI device
at least one third-party/custom plugin with WebUI extensions
bundled Plugin Hub/settings/plugin pages
Browser/desktop/terminal surfaces

UX direction

The app should feel like a modern remote workstation for Agent Zero, not a generic browser with an address bar.

Desired shell:

polished first-run instance cards
compact floating/collapsible top chrome while connected
prominent connection-state treatment only when state changes or is insecure
near-fullscreen Agent Zero content
gesture-friendly back/navigation
clean loading/reconnect states
native sheets for server management and app settings
no permanent browser-style URL bar

Acceptance

Android project exists under a documented repository boundary.
App installs and launches on a modern Samsung/Android phone.
User can add/switch Agent Zero HTTP and HTTPS instances.
Agent Zero login/session/auth/CSRF flows work without Android-specific server changes.
Chat and streaming/WebSocket activity work.
Uploads and downloads work.
Browser, Desktop, terminal/editor and plugin settings surfaces remain interactive.
Existing bundled plugin UI works without plugin modifications.
A custom plugin with WebUI extension points works without Android-specific code.
External URLs cannot gain privileged native bridge access.
HTTPS certificate failures are not bypassed.
Current service-worker/cache bootstrap and /safe escape path work.
App handles mobile keyboard, safe areas, rotation and back navigation cleanly.
CI produces an installable debug APK artifact; signed releases work when signing secrets are configured.
No core Agent Zero backend fork is required.

Mirrored from lost-rob0t/a0-symbolics#49 via tracker sync.

## Goal Build a modern Android application for `a0-symbolics` that provides a first-class mobile experience for a remote or local Agent Zero instance **without reimplementing Agent Zero in Kotlin**. The Android app should be a polished native shell around the authoritative Agent Zero WebUI. The WebUI, its service worker, WebSockets, authentication/CSRF behavior, full plugin UI/extensions, and future WebUI changes remain authoritative. This is intentionally a **hybrid native shell + real WebView** architecture: - Jetpack Compose / Material 3 Expressive for native Android chrome, setup, server profiles, permissions, connection state, and platform integration. - Android WebView for the actual Agent Zero UI and every plugin-owned UI surface. - Minimal, version-tolerant mobile optimization injected around the WebUI rather than a parallel Android client that would strand plugins. Related: #23 modern WebUI/plugin surface architecture. This Android epic must work against the current WebUI and must not be blocked on #23. ## Architecture requirements ### 1. Repository boundary Create an `android/` application boundary in this repository with its own `AGENTS.md` documenting ownership, build/test commands, security rules, and WebView compatibility contracts. Do not modify `agent.py` or `initialize.py` for the Android client. The Android app connects to a running Agent Zero instance over its normal WebUI origin. No Android-only backend fork. ### 2. Native Android shell Use modern Android UI and platform conventions: - Kotlin - Jetpack Compose - Material 3 / Material 3 Expressive where stable enough - edge-to-edge layout - predictive back-compatible navigation - dark/light/system theme support - dynamic color as an optional preference, with an Agent Zero-branded default theme - adaptive layouts for phone, foldable/tablet and landscape - touch targets and typography suitable for mobile The in-session WebView should remain visually dominant. Native chrome must be compact and collapsible rather than wasting screen space. ### 3. Connection profiles Provide a native first-run/server selector that supports multiple Agent Zero instances. Each profile should contain only non-secret connection metadata such as: - display name - base URL - optional color/icon metadata Requirements: - support both `https://` and `http://` endpoints so LAN/local Agent Zero instances work - normalize trailing slashes and reject malformed/non-http(s) schemes - persist profiles locally - allow switching instances without reinstalling the app - remember the last active profile - provide a clear visual warning for plaintext HTTP rather than silently pretending it is secure Authentication itself remains Agent Zero's WebUI/auth flow so credentials and CSRF semantics are not duplicated in Android. ### 4. WebView compatibility contract The WebView is the compatibility layer and must behave close to Chrome for Agent Zero's same-origin UI. Required: - JavaScript enabled - DOM storage enabled - cookies enabled - third-party cookies where required for supported auth flows - WebSockets work normally - service workers and Cache Storage remain available - Agent Zero's `/`, `/safe`, `/ui/index`, bundle/cache bootstrap and login flows remain functional - same-origin navigation remains inside the app - `window.open` / external links have an intentional mobile behavior - no unsafe generic `addJavascriptInterface` bridge exposed to arbitrary pages - Web contents debugging only in debug builds - preserve WebUI auth/CSRF/origin assumptions - do not intercept or rewrite Agent Zero API/WebSocket traffic For HTTPS profiles, do not weaken TLS validation or auto-accept certificate errors. For HTTP profiles, allow cleartext traffic intentionally and visibly mark the connection as insecure. ### 5. Plugin compatibility is a release gate Existing Agent Zero plugins must continue to work because their HTML/JS/CSS runs in the same WebUI origin and extension system. Compatibility includes: - `<x-extension>` frontend breakpoints - JS extensions - `<x-component>` loading - plugin modals/settings - plugin-owned full pages/surfaces - plugin API handlers - plugin WebSocket/event flows - plugin static assets - Plugin Hub / install / configuration flows - bundled and third-party plugin UI Do **not** create an Android-only plugin API as the primary path. The app may expose a tiny, versioned native capability marker to the same configured Agent Zero origin if useful, but plugins must not need Android-specific code to function. ### 6. Mobile optimization without DOM fragility Mobile optimizations must be additive and conservative. Use a stable app marker such as a user-agent suffix and/or a root document attribute inserted at document start. Prefer CSS custom properties / capability markers to brittle selector rewrites. Good candidates: - safe-area/inset variables - touch/long-press polish - prevent tiny form controls from triggering unwanted viewport zoom - keyboard/IME resize handling - mobile viewport height handling - overscroll behavior - native status/chrome spacing - optional mobile density mode Do not hide or rewrite arbitrary plugin DOM. Unknown plugin pages must render unmodified by default. ### 7. Full interaction support The Android app must support the platform glue needed to use Agent Zero fully from a phone: - HTML file upload chooser, including multiple files where requested - Android document picker/content URIs - downloads through Android's download UX - clipboard copy/paste - long-press/select/copy - microphone permission for voice/STT/plugin surfaces - camera permission when a WebUI/plugin explicitly requests it - fullscreen/custom-view handling for media/remote surfaces - native back behavior with WebView history - forward/reload/home controls - share current URL / selected Agent Zero URL - open external URLs in an appropriate Android browser/custom tab path - graceful offline/unreachable-server screen with retry and profile switching - process-death/state restoration where safe - orientation changes without losing the current session unnecessarily Agent Zero features that must remain usable include at least: - chat - attachments - projects/profiles - tasks - files - settings/model configuration - plugins / Plugin Hub - Browser surface - Desktop surface - terminal/code-execution surfaces - editor/document surfaces - onboarding and OAuth-related setup flows ### 8. Security - never commit Agent Zero passwords, API tokens, cookies or signing secrets - WebView permissions are origin-scoped and user-mediated - only the configured Agent Zero origin receives any future native bridge/capability messages - external origins must never inherit privileged Android bridge access - reject `file:`, `content:`, `javascript:` and unexpected custom-scheme top-level navigation unless an explicit safe handler exists - no TLS error bypass - no global arbitrary certificate trust override - clear browsing/session data action in Settings - optional biometric/app-lock can be a later slice; it must not replace Agent Zero authentication ### 9. Build target Target Android 16 / API 36 and remain compatible with a reasonable older-phone floor (prefer minSdk 26+ unless implementation evidence requires otherwise). Use current Android Gradle Plugin/Kotlin/Compose versions that support API 36. ### 10. CI and installable artifacts Add Android CI under `.github/workflows/`: - Gradle build - unit tests - Android lint - debug APK build - upload APK as a GitHub Actions artifact Design release signing so secrets can be supplied through GitHub Actions secrets; do not commit a production signing key. When signing secrets are present, release workflow should be able to produce a signed installable APK. Debug artifacts must remain clearly labeled as debug/dev builds. ### 11. Testing At minimum cover: #### Unit tests - URL normalization/validation - connection profile persistence model - navigation-origin policy - permission-origin policy - external link routing #### Instrumented/UI tests - first-run profile creation - HTTP and HTTPS profile selection - WebView loads an Agent Zero login/main page fixture - back/forward/reload behavior - file chooser callback - offline -> retry recovery - configuration survives recreation #### Manual compatibility matrix - current `a0-symbolics` WebUI - current Chrome/System WebView stable - phone portrait/landscape - Android 15 and Android 16 - Samsung One UI device - at least one third-party/custom plugin with WebUI extensions - bundled Plugin Hub/settings/plugin pages - Browser/desktop/terminal surfaces ## UX direction The app should feel like a modern remote workstation for Agent Zero, not a generic browser with an address bar. Desired shell: - polished first-run instance cards - compact floating/collapsible top chrome while connected - prominent connection-state treatment only when state changes or is insecure - near-fullscreen Agent Zero content - gesture-friendly back/navigation - clean loading/reconnect states - native sheets for server management and app settings - no permanent browser-style URL bar ## Acceptance - [ ] Android project exists under a documented repository boundary. - [ ] App installs and launches on a modern Samsung/Android phone. - [ ] User can add/switch Agent Zero HTTP and HTTPS instances. - [ ] Agent Zero login/session/auth/CSRF flows work without Android-specific server changes. - [ ] Chat and streaming/WebSocket activity work. - [ ] Uploads and downloads work. - [ ] Browser, Desktop, terminal/editor and plugin settings surfaces remain interactive. - [ ] Existing bundled plugin UI works without plugin modifications. - [ ] A custom plugin with WebUI extension points works without Android-specific code. - [ ] External URLs cannot gain privileged native bridge access. - [ ] HTTPS certificate failures are not bypassed. - [ ] Current service-worker/cache bootstrap and `/safe` escape path work. - [ ] App handles mobile keyboard, safe areas, rotation and back navigation cleanly. - [ ] CI produces an installable debug APK artifact; signed releases work when signing secrets are configured. - [ ] No core Agent Zero backend fork is required. --- *Mirrored from [`lost-rob0t/a0-symbolics#49`](https://github.com/lost-rob0t/a0-symbolics/issues/49)* via tracker sync.