hermes-android: Instructions file for Codex

Agent instructions for Hermes-Android

This file is the shared entry point for AI assistants working in this repository. Keep it project-specific and safe to publish. Do not put private machine setup, credentials, tokens, local network secrets, or personal workflow notes here.

Read first

Before making changes, read:

1. README.md
2. ROADMAP.md
3. ARCHITECTURE.md
4. AGENTS.md

For implementation work, also inspect the relevant source files under app/src/main/java/com/hermeswebui/android/.

Useful entry points:

• MainActivity.kt - Android platform boundary, WebView, intents, downloads, dashboard Custom Tab launch
• core/security/UrlPolicy.kt - URL and navigation decisions; also contains the top-level UrlOrigins object with origin/URL normalization utilities (hostFrom, hasSameOrigin, documentStartOriginRule, normalizeOriginUrl, normalizedPath) — use these helpers rather than ad-hoc URI parsing
• core/security/WebTrustPolicy.kt - context-specific WebView trust decisions for configured WebUI/dashboard routes, notification bridge sources/targets, and permission origins; keep parsing and trust rules here rather than duplicating them in MainActivity
• data/SettingsRepository.kt - encrypted settings persistence; implements SettingsStore interface. Uses a versioned runMigration() pattern (KEY_LAST_MIGRATION_VERSION): when adding new data schema changes, increment currentMigrationVersion and add a corresponding migration block. Non-interface methods (hasRequestedNotificationPermission, markNotificationPermissionRequested, getLastLoadedUrl) are called directly by MainActivity.
• domain/ServerUrlValidator.kt - server URL validation rules
• domain/ShareIntentParser.kt - Android share-sheet parsing
• domain/SharedFileHandoff.kt - staged share-sheet files; onShowFileChooser auto-delivers them only when the main WebView's top-level URL is the configured WebUI route. Other pages (proxy sign-in, OAuth providers) get the normal picker and must not consume or receive the staged files (Issue #136); never equate navigation consent with attachment trust
• ui/MainViewModel.kt - app state orchestration (paired with ui/MainViewModelFactory.kt)
• ui/web/WebShell.kt - Compose WebView host and refresh/error UX
• ui/settings/SettingsScreen.kt + ui/settings/SettingsSections.kt - native settings surface and task-based section components (opened via hermes://app/settings and the injected WebUI sidebar entry)
• ui/settings/ServerSetupHelp.kt - copy-only guided Hermes-chat setup prompts. Keep res/raw/setup_*_prompt.txt in sync with README fenced copy blocks; never execute them, add credentials, or imply clipboard tests verify host installation or phone connectivity.
• ui/DebugLogFloatingButton.kt - draggable overlay shown while debug logging is active
• OAuthPopupFlow.kt - parses authorization requests and verifies OAuth/OIDC callbacks before allowing in-app provider navigation
• notification/HermesNotificationBridgeCoordinator.kt - scoped WebUI Notification API bridge and Android permission reply handling
• notification/HermesNotificationPresenter.kt - renders Android-backed WebUI notifications and routes tapped notification intents back into the trusted WebView
• background/HermesReconnectService.kt + background/ReconnectBackgroundPolicy.kt - foreground service (manifest foregroundServiceType="dataSync") that keeps the bounded reconnect probe and /api/session/stream subscription alive while the activity is backgrounded; policy helpers gate when the service should run/keep-alive/cancel
• background/HermesForegroundServiceCoordinator.kt - owns MainActivity-facing reconnect/debug foreground-service lifecycle sync and promotion/teardown rules
• background/ApprovalClient.kt + background/ApprovalActionSupport.kt + background/ReconnectSessionStreamSupport.kt - authenticated /api/approval/pending//api/approval/respond client and SSE event support used by the notification approval actions
• Background session IDs come from trusted WebUI URLs ending in /session/{id}, including mount prefixes. Use UrlOrigins.pathSegments to split before decoding once; do not restore the dashboard-only /{id} assumption or parse untrusted provider URLs to enable monitoring.
• Session-monitor requests must refresh when reconnect/session/cookie/privacy state changes. Fence canceled streams and stale approval completions so they cannot stop or overwrite replacement monitoring. HermesSessionMonitorInstrumentationTest exercises the actual Android service, notification PendingIntents, and loopback HTTP/SSE on the emulator, not upstream WebUI behavior.
• background/HermesDebugLoggingService.kt + background/DebugLogBootstrap.kt - opt-in foreground logcat capture into files/debug-logs/ with a persistent Stop notification
• server/HermesServerProfileCoordinator.kt - startup preflight plus server-profile add/edit/delete/switch validation and confirmation flows
• launcher/LauncherIconManager.kt - PackageManager-authoritative launcher artwork selection. Keep the stable WebUiLauncher/AgentLauncher aliases and always-enabled MainActivity; toggle only aliases, preserving share/deep links and channel labels. Profile serverType is a cosmetic manual override (UNSPECIFIED means Automatic); detectedServerType remembers explicit runtime-marker detection from the configured main-frame route. Fence asynchronous probes across navigation/server changes, clear detection on URL edits, preserve manual overrides, and never use either label as a trust signal or change launcher artwork automatically.
• webview/HermesWebViewConfigurator.kt - shared main/popup WebView hardening and settings setup
• webview/HermesWebViewDownloadListener.kt - allowlisted DownloadManager handoff with session cookies, user agent, and AndroidX RFC-compatible filename parsing; preserve filename*, original extensions, and explicit downloads from inline image headers rather than using legacy android.webkit.URLUtil; on Android 10+ save to the shared Download folder (no storage permission needed) so files appear in Files > Downloads, keeping the app-specific folder only on Android 8/9 or when shared storage is unavailable (Issue #130)
• webui/VoiceCaptureLifecycleGate.kt - new-request WebView microphone gate and proposed hermes-app-foreground host signal; a pending trusted permission result can be granted while started before resume
• webui/HermesWebUiScripts.kt - document-start WebUI compatibility shims (hybrid viewport polyfill with generic collapse detection, microphone fallback, Enter-key newline behavior, sidebar settings injector, notification bridge script payloads); keep these scoped to the configured Hermes WebUI origin
• update/HermesAppUpdateCoordinator.kt - app-update checks, update notifications, Play update launch, and GitHub APK download intents
• update/GitHubReleaseUpdateChecker.kt + update/AppVersionComparator.kt + update/AppUpdateCheckResult.kt - GitHub-channel update check (Play channel uses Play Core through update/PlayUpdateClient.kt, implemented in app/src/play/java with a no-op FOSS twin in app/src/foss/java)
• update/AppUpdateDownloadPolicy.kt - strict GitHub APK download host allowlist used by update download intents (github.com and *.githubusercontent.com only)