67 lines
4.0 KiB
Markdown
67 lines
4.0 KiB
Markdown
# Project: HermesControl Jetpack Compose Android App
|
|
|
|
## Architecture
|
|
The HermesControl Jetpack Compose Android application communicates with the local Hermes agent instance via two communication channels:
|
|
1. **REST API (Port 9119)**: For status queries, listing sessions, and system configuration.
|
|
2. **WebSocket Gateway (`/api/ws?token=<TOKEN>`)**: For real-time JSON-RPC messaging (chat, prompt submission, stream events, tool execution updates, etc.).
|
|
|
|
### Package Boundaries
|
|
- `com.m57.hermescontrol.data.model` — REST API data classes.
|
|
- `com.m57.hermescontrol.data.remote` — Retrofit ApiClient and HermesApiService.
|
|
- `com.m57.hermescontrol.data.ws` — JSON-RPC models, HermesWsClient, and EventParser.
|
|
- `com.m57.hermescontrol.data.local` — AuthManager (EncryptedSharedPreferences).
|
|
- `com.m57.hermescontrol.ui.connect` — ConnectScreen and ConnectViewModel.
|
|
- `com.m57.hermescontrol.ui.chat` — ChatScreen, ChatViewModel, and ChatBubble.
|
|
- `com.m57.hermescontrol.ui.settings` — SettingsScreen and SettingsViewModel.
|
|
- `com.m57.hermescontrol.theme` — Color, Theme, and Type.
|
|
|
|
---
|
|
|
|
## Milestones
|
|
|
|
| # | Name | Scope | Dependencies | Status |
|
|
|---|---|---|---|---|
|
|
| M1 | Exploration & Setup | Explore codebase, identify dependencies and structure | None | DONE |
|
|
| M2 | Networking & Data Layer | Implement/Fix AuthManager, api clients, WS clients, EventParser | M1 | DONE |
|
|
| M3 | UI Screen Implementation | Implement ConnectScreen, ChatScreen, SettingsScreen, and Nav integration | M2 | DONE |
|
|
| M4 | Unit Testing | Implement unit tests for AuthManager, EventParser, Connect/Chat ViewModels | M2, M3 | DONE |
|
|
| M5 | Styling & Audit Validation | Perform ktlint formatting fixes, compiler error fixes, and run Forensic Audit | M4 | DONE |
|
|
| M6 | E2E Testing Track | Design and build comprehensive opaque-box integration tests (Tiers 1-4) | M5 | PLANNED |
|
|
| M7 | API Integration & Models | Add Retrofit endpoints and JSON serialization models for Skills & Cron Jobs | M5 | PLANNED |
|
|
| M8 | Skills Management UI | Implement Viewmodel and UI Screen for skills management | M7 | PLANNED |
|
|
| M9 | Cron Jobs Management UI | Implement Viewmodel and UI Screen for cron jobs control | M7 | PLANNED |
|
|
| M10 | Navigation Drawer | Integrate Material3 navigation drawer using Navigation3 keys | M8, M9 | PLANNED |
|
|
| M11 | E2E & Hardening Phase | Verify all E2E tests, perform adversarial coverage hardening (Tier 5) | M6, M10 | PLANNED |
|
|
|
|
---
|
|
|
|
## Interface Contracts
|
|
|
|
### REST API Service
|
|
- `getStatus()`: Returns `StatusResponse` (version, gateway status, active sessions)
|
|
- `getSessions()`: Returns `SessionListResponse` (all sessions and metadata)
|
|
- `getSessionMessages(sessionId: String)`: Returns `SessionMessagesResponse` (message history)
|
|
- `getSystemStats()`: Returns `SystemStatsResponse` (CPU, memory, etc.)
|
|
- `getSkills()`: Returns list of skills (`GET api/skills`)
|
|
- `toggleSkill(payload)`: Toggles a skill's state (`PUT api/skills/toggle`)
|
|
- `getCronJobs()`: Returns list of cron jobs (`GET api/cron/jobs`)
|
|
- `pauseCronJob(id)`: Pauses a job (`POST api/cron/jobs/{id}/pause`)
|
|
- `resumeCronJob(id)`: Resumes a job (`POST api/cron/jobs/{id}/resume`)
|
|
- `triggerCronJob(id)`: Triggers a job immediately (`POST api/cron/jobs/{id}/trigger`)
|
|
- `deleteCronJob(id)`: Deletes a job (`DELETE api/cron/jobs/{id}`)
|
|
|
|
### WebSocket Client (`HermesWsClient`)
|
|
- `connect()`: Establish connection to `/api/ws?token=<TOKEN>`
|
|
- `disconnect()`: Terminate connection
|
|
- `sendMessage(text: String)`: Submit prompt (`prompt.submit` JSON-RPC method)
|
|
- `resumeSession(sessionId: String)`: Resume a session (`session.resume` JSON-RPC method)
|
|
- Callbacks: `onConnected()`, `onDisconnected(reason: String)`, `onMessage(JsonRpcResponse)`
|
|
|
|
### Event Parser (`EventParser`)
|
|
- Parses incoming JSON messages from WebSocket and extracts event fields (`event`, `data`, `id`, `result`, `error`).
|
|
- Categorizes events: `message.complete`, `message.token`, `tool.start`, `tool.complete`, `clarify.request`, etc.
|
|
|
|
## Code Layout
|
|
- `app/src/main/java/com/m57/hermescontrol/` (Main Source)
|
|
- `app/src/test/java/com/m57/hermescontrol/` (Unit Tests)
|