Feat/termux install path, bug fixes termux

.github/workflows/android-release.yml

@@ -0,0 +1,82 @@
+name: Android Release
+
+on:
+  release:
+    types:
+      - published
+
+concurrency:
+  group: android-release-${{ github.event.release.tag_name }}
+  cancel-in-progress: false
+
+jobs:
+  build-release:
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+
+      - name: Set up Java 21
+        uses: actions/setup-java@v5
+        with:
+          distribution: temurin
+          java-version: '21'
+          cache: gradle
+
+      - name: Set up Python 3.13 for Chaquopy
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.13'
+
+      - name: Set up Android SDK
+        uses: android-actions/setup-android@v4
+
+      - name: Restore signing material
+        env:
+          ANDROID_KEYSTORE_BASE64: ${{ secrets.ANDROID_KEYSTORE_BASE64 }}
+          ANDROID_KEYSTORE_PASSWORD: ${{ secrets.ANDROID_KEYSTORE_PASSWORD }}
+          ANDROID_KEY_ALIAS: ${{ secrets.ANDROID_KEY_ALIAS }}
+          ANDROID_KEY_PASSWORD: ${{ secrets.ANDROID_KEY_PASSWORD }}
+        run: |
+          test -n "$ANDROID_KEYSTORE_BASE64"
+          test -n "$ANDROID_KEYSTORE_PASSWORD"
+          test -n "$ANDROID_KEY_ALIAS"
+          test -n "$ANDROID_KEY_PASSWORD"
+          echo "$ANDROID_KEYSTORE_BASE64" | base64 --decode > android/release.keystore
+          cat > android/keystore.properties <<EOF
+          storeFile=release.keystore
+          storePassword=$ANDROID_KEYSTORE_PASSWORD
+          keyAlias=$ANDROID_KEY_ALIAS
+          keyPassword=$ANDROID_KEY_PASSWORD
+          EOF
+
+      - name: Ensure Gradle wrapper is executable
+        run: chmod +x android/gradlew
+
+      - name: Build signed Android artifacts
+        working-directory: android
+        env:
+          HERMES_RELEASE_TAG: ${{ github.event.release.tag_name }}
+          SOURCE_DATE_EPOCH: "315532800"
+        run: |
+          rm -rf ../build
+          export PYTHON_FOR_BUILD="$(command -v python3.13 || command -v python3 || command -v python)"
+          ./gradlew :app:assembleRelease :app:bundleRelease
+
+      - name: Rename artifacts and write checksums
+        run: |
+          python scripts/android_release_manifest.py --tag "${{ github.event.release.tag_name }}"
+
+      - name: Upload release assets
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release upload "${{ github.event.release.tag_name }}" \
+            dist/android-release/*.apk \
+            dist/android-release/*.aab \
+            dist/android-release/*.sha256 \
+            --clobber

.github/workflows/android.yml

@@ -0,0 +1,73 @@
+name: Android
+
+on:
+  push:
+    branches:
+      - feat/termux-install-path
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: android-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  smoke:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+
+      - name: Set up Java 21
+        uses: actions/setup-java@v5
+        with:
+          distribution: temurin
+          java-version: '21'
+          cache: gradle
+
+      - name: Set up Python 3.13 for Chaquopy
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.13'
+
+      - name: Set up Android SDK
+        uses: android-actions/setup-android@v4
+
+      - name: Install Python test dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e '.[android,dev]' -c constraints-android.txt
+
+      - name: Run Android-related Python tests
+        run: |
+          python -m pytest \
+            tests/hermes_android \
+            tests/hermes_android/test_android_packaging.py \
+            tests/gateway/test_api_server_toolset.py \
+            tests/gateway/test_api_server_android_toolset.py \
+            tests/tools/test_skills_sync.py \
+            tests/tools/test_web_tools_firecrawl_fallback.py \
+            tests/run_agent/test_run_agent_chatgpt_web.py \
+            -q
+
+      - name: Ensure Gradle wrapper is executable
+        run: chmod +x android/gradlew
+
+      - name: Build Android debug APK and run unit tests
+        working-directory: android
+        env:
+          SOURCE_DATE_EPOCH: "315532800"
+        run: |
+          rm -rf ../build
+          export PYTHON_FOR_BUILD="$(command -v python3.13 || command -v python3 || command -v python)"
+          ./gradlew :app:testDebugUnitTest -PskipHermesAndroidLinuxAssets=true
+          ./gradlew :app:assembleDebug
+
+      - name: Upload debug APK artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: hermes-agent-android-debug-apk
+          path: android/app/build/outputs/apk/debug/*.apk
+          if-no-files-found: error

.github/workflows/deploy-site.yml

@@ -26,7 +26,14 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Trigger Vercel Deploy
-        run: curl -X POST "${{ secrets.VERCEL_DEPLOY_HOOK }}"
+        env:
+          VERCEL_DEPLOY_HOOK: ${{ secrets.VERCEL_DEPLOY_HOOK }}
+        run: |
+          if [ -z "$VERCEL_DEPLOY_HOOK" ]; then
+            echo "VERCEL_DEPLOY_HOOK is not configured; skipping Vercel deploy."
+            exit 0
+          fi
+          curl -fsS -X POST "$VERCEL_DEPLOY_HOOK"
 
   deploy-docs:
     if: github.repository == 'NousResearch/hermes-agent'

.gitignore

@@ -30,6 +30,8 @@ run_datagen_sonnet.sh
 source-data/*
 run_datagen_megascience_glm4-6.sh
 data/*
+!android/app/src/main/java/com/nousresearch/hermesagent/data/
+!android/app/src/main/java/com/nousresearch/hermesagent/data/*.kt
 node_modules/
 browser-use/
 agent-browser/
@@ -70,3 +72,11 @@ mini-swe-agent/
 result
 website/static/api/skills-index.json
 models-dev-upstream/
+
+# Android local build / signing state
+android/.gradle/
+android/build/
+android/app/build/
+android/local.properties
+android/keystore.properties
+android/release.keystore

MANIFEST.in

@@ -1,3 +1,5 @@
+include constraints-termux.txt
+include constraints-android.txt
 graft skills
 graft optional-skills
 global-exclude __pycache__

README.md

@@ -38,6 +38,8 @@ Works on Linux, macOS, WSL2, and Android via Termux. The installer handles the p
 
 > **Android / Termux:** The tested manual path is documented in the [Termux guide](https://hermes-agent.nousresearch.com/docs/getting-started/termux). On Termux, Hermes installs a curated `.[termux]` extra because the full `.[all]` extra currently pulls Android-incompatible voice dependencies.
 >
+> **Android app:** Hermes also has an in-repo Android APK workstream under `android/`, with GitHub Actions workflows for debug and release artifact builds. This app path is separate from the Termux CLI path.
+>
 > **Windows:** Native Windows is not supported. Please install [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) and run the command above.
 
 After installation:

RELEASE_v0.13.0.md

@@ -0,0 +1,25 @@
+# Hermes Agent v0.13.0 (v2026.5.3)
+
+**Release Date:** May 3, 2026
+
+> Native Android Gemma release. Hermes can now run the Android APK as a local Gemma-powered agent path with first-class Gemma 4/Gemma 3 model selection, image attachment plumbing, Python 3.12 Chaquopy builds, and validated native tool access on the emulator.
+
+## Highlights
+
+- **Gemma 4 local Android agent path** - Gemma 4 E2B and E4B LiteRT-LM artifacts load and answer locally through the in-app OpenAI-compatible proxy. Gemma 4 E2B also powers native chat/tool-call flows that create, delete, and inspect files through the embedded Android Linux command suite.
+- **First-class Gemma model selection** - Settings now has a real model-selection dropdown card with provider suggestions plus local Gemma 4, Gemma 3, Gemma 3 vision, and Gemma 3n vision entries.
+- **Multimodal request plumbing** - Chat can attach images, preserve image attachments in state, encode them as OpenAI-style `image_url` content parts, and pass multimodal payloads through API, SSE, and native tool-calling clients.
+- **Vision-safe LiteRT-LM behavior** - Gemma 3/Gemma 3n vision models are represented as first-class local options. Text-only models now reject image requests with a clear 400 instead of silently ignoring images. The image-description instrumentation test runs automatically when a Gemma 3/Gemma 3n vision artifact is provisioned.
+- **Python 3.12 Android runtime** - Chaquopy and GitHub Actions now build with Python 3.12, and Android CI/release jobs use JDK 21 for LiteRT-LM compatibility.
+- **Deep UI visual coverage** - Added an emulator UI flow that captures chat typing, Settings selection, the model dropdown, and translated Spanish pages across Settings, Accounts, Device, and Portal.
+- **Native Android tool coverage** - Added emulator tests for terminal tool file creation/deletion, Android system status, cron lifecycle, and background runtime start/stop.
+- **Branding refresh** - Android launcher/topbar branding now uses the Nous/Hermes thumbnail asset.
+
+## Validation
+
+- `python -m pytest tests/hermes_android -q`
+- `./gradlew :app:testDebugUnitTest -PskipHermesAndroidLinuxAssets=true`
+- `./gradlew :app:installDebug :app:installDebugAndroidTest`
+- `adb shell am instrument ... DeepAppUiVisualInstrumentedTest`
+- `adb shell am instrument ... Gemma4LocalInferenceInstrumentedTest,NativeAppChatAndToolInstrumentedTest,NativeAppUiChatInstrumentedTest,NativeAgentToolAccessInstrumentedTest,LiteRtLmModelMatrixInstrumentedTest`
+- Additional model matrix checks passed for Gemma 4 E4B, Qwen3 0.6B, and Qwen2.5 1.5B. Phi-4-mini was attempted under the 5 GB artifact ceiling but the emulator aborted inside the native LiteRT loader during initialization, so it is not marked supported in this release.

RELEASE_v0.13.1.md

@@ -0,0 +1,20 @@
+# Hermes Agent v0.13.1
+
+**Release Date:** May 3, 2026
+
+Patch release for the native Android Gemma agent after live-device ADB validation on an arm64 phone.
+
+## Fixes
+
+- Rebased `feat/termux-install-path` on current upstream `NousResearch/hermes-agent/main`.
+- Fixed LiteRT-LM artifact selection so Gemma 4 downloads prefer Android `.litertlm` bundles instead of `*-web.task` browser FlatBuffers.
+- Added runtime preflight for stale or exact `.task` files that contain `TFL3` FlatBuffer headers, returning a clear message to remove the web task and download the `.litertlm` artifact.
+- Updated Android backend compatibility checks so existing preferred `*-web.task` downloads are rejected before engine startup instead of surfacing `Unable to open zip archive`.
+- Updated the Hermes Android debugging skill with the live-phone ADB diagnosis flow.
+
+## Validation
+
+- `python -m pytest tests/hermes_android/test_android_model_downloads.py tests/hermes_android/test_android_multimodal_model_selection.py -q`
+- `./gradlew :app:testDebugUnitTest -PskipHermesAndroidLinuxAssets=true`
+- `./gradlew :app:assembleDebug`
+- Live phone ADB confirmed the failing `gemma-4-e2b-it-web.task` artifact starts with `TFL3` bytes and is not a LiteRT-LM bundle.

RELEASE_v0.13.10.md

@@ -0,0 +1,16 @@
+# Hermes Agent v0.13.10
+
+This release adds a signed Cloudflare-backed model catalog for Android local inference and makes tested model setup a single dropdown flow in Settings.
+
+- Adds a Cloudflare Worker model index with D1 storage, KV-published signed JSON, Hugging Face webhook ingestion, scheduled scans, and an authenticated HTTP GET scan fallback for cron-only environments.
+- Discovers small mobile-friendly model files under 5 GiB, including Unsloth GGUF quantizations and LiteRT-LM Gemma builds.
+- Adds Android signature verification for the catalog before any detected model is shown.
+- Adds one Settings dropdown for detected downloadable models and a single action to download, mark preferred, and start the local runtime.
+- Keeps Gemma 4 LiteRT-LM and Qwen3.5 0.8B GGUF ranked as first-class Android choices.
+- Updates the F-Droid metadata template for the v0.13.10 release tag and Android version code.
+
+Validation:
+
+- Worker TypeScript check passed with `npm run check`.
+- Android Kotlin compile, debug unit tests, and debug APK assembly passed with JDK 21, Android SDK 35, and Python 3.12.
+- Emulator smoke test loaded the signed catalog in Settings and showed 62 downloadable model choices from the deployed worker.

RELEASE_v0.13.11.md

@@ -0,0 +1,14 @@
+# Hermes Agent v0.13.11
+
+Android/F-Droid reproducibility release.
+
+## Android
+
+- Builds the embedded Chaquopy runtime with Python 3.13 so GitHub release APKs match Debian 13/F-Droid builds.
+- Emits a single universal release APK and disables Android dependency metadata for F-Droid scanner compatibility.
+- Sorts generated Android Linux assets and native-library packaging inputs for deterministic release artifacts.
+
+## Packaging
+
+- Bumps the package version to 0.13.11.
+- Updates the F-Droid metadata template for Android version code 131190.

RELEASE_v0.13.12.md

@@ -0,0 +1,14 @@
+# Hermes Agent v0.13.12
+
+Android/F-Droid reproducibility follow-up.
+
+## Android
+
+- Cleans the tracked `build/` directory before GitHub Android release builds so release APKs match F-Droid's clean source build.
+- Canonicalizes Chaquopy `build.json` ordering before APK packaging.
+- Keeps the Python 3.13 Android runtime, single universal APK output, and disabled Android dependency metadata from v0.13.11.
+
+## Packaging
+
+- Bumps the package version to 0.13.12.
+- Updates the F-Droid metadata template for Android version code 131290.

RELEASE_v0.13.13.md

@@ -0,0 +1,16 @@
+# Hermes Agent v0.13.13
+
+This release fixes the remaining F-Droid reproducible-build differences in the
+Android APK.
+
+## Android
+
+- Forces GitHub Android release builds to use hash-based Python bytecode by
+  setting `SOURCE_DATE_EPOCH`.
+- Canonicalizes Chaquopy's generated `build.json` before Android asset merging.
+- Keeps the universal signed APK layout introduced for F-Droid verification.
+
+## F-Droid
+
+- Bumps the package version to 0.13.13.
+- Updates the F-Droid metadata template for Android version code 131390.

RELEASE_v0.13.14.md

@@ -0,0 +1,16 @@
+# Hermes Agent v0.13.14
+
+This release completes the Android reproducible-build fixes needed by the
+F-Droid inclusion review.
+
+## Android
+
+- Canonicalizes Chaquopy `requirements-common.imy` before APK packaging.
+- Removes local pip `direct_url.json` install paths from embedded Python assets.
+- Rewrites embedded pyc bodies with a stable marshal format while preserving
+  hash-based pyc headers.
+
+## F-Droid
+
+- Bumps the package version to 0.13.14.
+- Updates the F-Droid metadata template for Android version code 131490.

RELEASE_v0.13.15.md

@@ -0,0 +1,11 @@
+# Hermes Agent v0.13.15
+
+This release adds the metadata needed for F-Droid autoupdate checks to track
+future semver tags without being limited to the 0.13 release line.
+
+## F-Droid
+
+- Adds a tracked `fdroid/com.nousresearch.hermesagent.version` file containing
+  the literal Android `versionName` and `versionCode` for each release tag.
+- Updates the draft fdroiddata metadata template to use `AI Chat` and
+  unrestricted tag checks.

RELEASE_v0.13.16.md

@@ -0,0 +1,31 @@
+# Hermes Agent v0.13.16
+
+This release hardens native Android agent startup and adds first-class setup
+surfaces for Shizuku/Sui-assisted privileged Android actions.
+
+## Android Agent
+
+- Adds Shizuku/Sui status reporting and setup actions for developer options,
+  wireless debugging, Shizuku launch/download, and Shizuku permission requests.
+- Keeps background runtime service startup responsive by promoting foreground
+  notification immediately and moving heavy runtime boot work off the service
+  main thread.
+- Delays automatic persisted-runtime restart during app process startup so the
+  first activity and instrumentation launch do not collide with Python/native
+  asset extraction.
+- Fixes native tool-call chat loops so Hermes sends the post-tool follow-up
+  request instead of returning the last raw tool result as the assistant reply.
+
+## Native Android Runtime
+
+- Fixes embedded Android Linux subprocess library resolution by adding the
+  packaged native executable directory to `LD_LIBRARY_PATH`.
+- Keeps Python subprocesses on `/system/bin/sh` while preserving Hermes Android
+  shell metadata for native tools.
+
+## Validation
+
+- Adds emulator visual-harness commands for screenshots, taps, swipes, text,
+  key events, launch, and viewport sizing.
+- Adds Android instrumentation coverage for privileged-access status, native
+  tool status JSON, and full connected startup stability.