build: establish Android beta packaging
This commit is contained in:
Hermes Agent
@@ -0,0 +1,94 @@
|
||||
# Android Beta Build and Install
|
||||
|
||||
This guide covers the native Kotlin/Compose direct-gateway client at version `v0.1.0-beta.1`. It does not build or require `apps/companion`, publish an APK, or complete the beta release criteria by itself.
|
||||
|
||||
## Package identity
|
||||
|
||||
- Application ID: `cloud.molberg.hermesmobile`
|
||||
- Android `versionName`: `0.1.0-beta.1`
|
||||
- Android `versionCode`: `10001`
|
||||
- Debug APK: `apps/mobile/android/app/build/outputs/apk/debug/hermes-mobile-v0.1.0-beta.1-debug.apk`
|
||||
|
||||
`versionName` is the user-visible semantic version. `versionCode` is an internal monotonically increasing Android package revision and must increase for every later installable build.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- JDK 17 or newer supported by the checked-in Android Gradle Plugin.
|
||||
- Android SDK platform 35, matching build tools, and platform tools.
|
||||
- Network access for the first dependency resolution, or a complete compatible Gradle cache.
|
||||
- For installation, a real Android device with USB debugging enabled or a running emulator visible to `adb`.
|
||||
- For use, an HTTPS upstream Hermes Agent gateway/API server and its bearer token when authentication is enabled.
|
||||
|
||||
Do not run Capacitor synchronization for this client. The beta application source is the native project under `apps/mobile/android`.
|
||||
|
||||
## Build and test
|
||||
|
||||
From the repository root:
|
||||
|
||||
```bash
|
||||
cd apps/mobile/android
|
||||
GRADLE_USER_HOME="$PWD/../../../.gradle-user" ./gradlew \
|
||||
:app:testDebugUnitTest \
|
||||
:app:assembleDebug
|
||||
```
|
||||
|
||||
The expected APK is:
|
||||
|
||||
```text
|
||||
app/build/outputs/apk/debug/hermes-mobile-v0.1.0-beta.1-debug.apk
|
||||
```
|
||||
|
||||
Confirm the package metadata before distributing the file:
|
||||
|
||||
```bash
|
||||
aapt dump badging app/build/outputs/apk/debug/hermes-mobile-v0.1.0-beta.1-debug.apk \
|
||||
| sed -n '1p'
|
||||
sha256sum app/build/outputs/apk/debug/hermes-mobile-v0.1.0-beta.1-debug.apk
|
||||
```
|
||||
|
||||
Expected badging includes package `cloud.molberg.hermesmobile`, `versionCode='10001'`, and `versionName='0.1.0-beta.1'`.
|
||||
|
||||
The debug APK is signed with the local Android debug key. It is suitable for beta verification, not a production signing or store-release workflow. APKs and build output must remain untracked.
|
||||
|
||||
## Clean install and run
|
||||
|
||||
Confirm that exactly one intended target is attached:
|
||||
|
||||
```bash
|
||||
adb devices -l
|
||||
```
|
||||
|
||||
Remove any prior installation, then install the newly built APK. Uninstalling clears existing Hermes Mobile app data and stored gateway credentials.
|
||||
|
||||
```bash
|
||||
adb uninstall cloud.molberg.hermesmobile || true
|
||||
adb install app/build/outputs/apk/debug/hermes-mobile-v0.1.0-beta.1-debug.apk
|
||||
adb shell monkey -p cloud.molberg.hermesmobile -c android.intent.category.LAUNCHER 1
|
||||
```
|
||||
|
||||
In Hermes Mobile Settings, configure the upstream gateway directly:
|
||||
|
||||
1. Enter the required Remote HTTPS gateway base URL and, optionally, a Local HTTPS URL for the same trusted gateway.
|
||||
2. Select bearer authentication and enter the gateway token when required, or select no authentication only when the gateway is configured that way.
|
||||
3. Save and test the connection. The client probes `/health`, validates compatibility through the authenticated gateway surface, and displays the active Local or Remote route.
|
||||
4. Exercise chat/session behavior only where the gateway advertises the required capabilities.
|
||||
|
||||
Do not enter a legacy companion URL or companion access key. The beta path is the direct upstream Hermes gateway architecture described in `docs/DIRECT_GATEWAY_ARCHITECTURE.md`.
|
||||
|
||||
## Required install evidence
|
||||
|
||||
Record all of the following before claiming R2 installation verification or a beta release:
|
||||
|
||||
- The source commit used for the build.
|
||||
- Passing Android unit tests and APK assembly.
|
||||
- `aapt` package/version output and the APK SHA-256.
|
||||
- A successful clean `adb install` on a named real device or emulator.
|
||||
- App launch plus direct-gateway configuration and connection result.
|
||||
- Any observed limitations or failures, without treating source-only checks as device evidence.
|
||||
|
||||
## Known limitations
|
||||
|
||||
- R1 adaptive/accessibility verification still requires the documented real-device/emulator matrix.
|
||||
- B3 remains blocked on an official session-search contract and live upstream gateway compatibility evidence.
|
||||
- Direct gateway chat, streaming, tools, artifacts, and recovery remain capability-gated; unsupported or unverified routes are not inferred.
|
||||
- The debug APK is not a published release artifact. No beta release exists until all release criteria in `docs/ROADMAP.md` are genuinely satisfied.
|
||||
Reference in New Issue
Block a user