iris_x_hermes/AGENTS.md

AGENTS.md

Hard rules

• hermes-agent/ is a read-only research reference (git-ignored). Never commit, push, or modify it — a pre-commit hook (scripts/guard_hermes_agent.sh --staged) fails any commit that stages it. Never modify hermes core; we only install our plugin into the live hermes home.
• The plugin is installed by symlink: ~/.hermes/plugins/android → <repo>/gateway-plugin (already set up on this machine).

Layout

• gateway-plugin/ — Python hermes platform plugin (android). No build step, zero new deps (stdlib + hermes-provided websockets/httpx). protocol.py is the frame source of truth, mirrored in app/shared/.../protocol/Protocol.kt and docs/protocol/frames.schema.json.
• app/ — one Compose Multiplatform Gradle project: :shared (KMP, most of the code; jvmMain is shared by the android and desktop targets since both are JVM-based), :androidApp (thin shell, package dev.iris.app), :desktopApp (thin shell).
• docs/ — numbered reference library; read docs/00-overview.md first. Locked decisions: docs/16-open-questions.md.

Commands

• hermes is not on PATH: use hermes-agent/.venv/bin/hermes (venv from cd hermes-agent && uv sync).
• Gateway: hermes gateway setup (one-time; generates ANDROID_TOKEN in ~/.hermes/.env, prints the token only once) → hermes gateway (run) → hermes gateway status.
• Android: check the device is connected first (adb devices → a5ca2a4b listed as device); then cd app && ./gradlew :androidApp:installDebug to install on the phone and live-verify changes (launch/screenshot: see ADB below).
• Desktop: cd app && ./gradlew :desktopApp:run; packaging: :desktopApp:jpackage (app-image; -PjpackageType=deb for a .deb).
• Python tests — never bare pytest: cd hermes-agent && scripts/run_tests.sh tests/gateway/test_android.py (no args = full suite).
• Kotlin tests: cd app && ./gradlew :shared:testDebugUnitTest / :shared:desktopTest (no test sources exist yet).
• WS probe (gateway must be running): hermes-agent/.venv/bin/python gateway-plugin/tests/ws_probe.py --token <ANDROID_TOKEN> --send "hello" — assertion flags documented in gateway-plugin/tests/README.md.
• E2E driver (gateway must be running; it never starts/stops it): hermes-agent/.venv/bin/python gateway-plugin/tests/e2e.py.

Environment / pairing quirks

• Pairing token: ANDROID_TOKEN in ~/.hermes/.env. The app has no QR scanner — pairing is manual URL + token entry.
• WS default bind is 127.0.0.1; for a phone on the LAN set ANDROID_WS_HOST to the gateway's LAN IP.
• app/local.properties (sdk.dir) is git-ignored and required for Android builds.
• google-services.json is optional: without it FCM is inert and ntfy is the push path. Public ntfy.sh SSE is flaky — self-host ntfy.
• JDK 17; no system Gradle — always the wrapper (./gradlew).
• Desktop jpackage on Linux/JDK 17 prints a non-fatal pure virtual method called (JDK-8348560); the app works.

Testing quirks

• hermes-agent/tests/gateway/test_android.py is a thin mirror that imports the live gateway-plugin/ package from this repo (override with ANDROID_PLUGIN_DIR); HERMES_HOME is sandboxed per-test by the conftest. Tests must never touch the real ~/.hermes.
• e2e scenarios 3 (reasoning) and 5 (commentary) are model-dependent → SKIP; 11 (push) and 12 (reconnect) are PARTIAL by design.
• ADB: launch adb shell am start -n dev.iris.app/.MainActivity; reset pairing state adb shell pm clear dev.iris.app; screenshot adb exec-out screencap -p > /tmp/shot.png.
• Gateway logs: ~/.hermes/logs/gateway.log or hermes logs --follow.