64 lines
5.9 KiB
Markdown
64 lines
5.9 KiB
Markdown
|
# Project Meatbag: Session Handoff
|
||
|
|
|
||
|
|
**Date**: June 27, 2026
|
||
|
|
**Ecosystem**: WhetForge
|
||
|
|
**Goal**: Scaffolding and Implementing the MVP for **Meatbag**, a multiplatform "Human Latency Optimization Tool" for server-driven UI (SDUI).
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 1. What We Did This Session
|
||
|
|
We initiated the project from scratch, structured it as a Kotlin Multiplatform Gradle project, and developed a stateful routing backend and a stateless Compose Multiplatform client. The session focused on achieving a successful end-to-end ping-pong loop:
|
||
|
|
1. An agent submits an `ApprovalRequest` via HTTP POST to the backend.
|
||
|
|
2. The backend determines the target device and attention tier based on user context rules, then suspends the request.
|
||
|
|
3. The backend notifies the target device via WebSockets.
|
||
|
|
4. The client simulates haptics (or alerts) based on the `AttentionTier`, parses the JSON UI primitive, and inflates the UI dynamically.
|
||
|
|
5. The human taps "Yes" / interacts, sending a response to the backend.
|
||
|
|
6. The backend resumes the suspended agent request and returns the response.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 2. Core Project Architecture
|
||
|
|
The project directory is structured as a multi-module Kotlin project:
|
||
|
|
|
||
|
|
* **`:common` (Kotlin Multiplatform)**
|
||
|
|
* [UiPrimitive.kt](file:///Users/blindmouse/meatbag/common/src/commonMain/kotlin/meatbag/common/UiPrimitive.kt): Declares the sealed hierarchy representing JSON UI elements (`UiPrimitive` with sub-types `ApprovalRequest`, `ActionList`, `TextInput`), the `AttentionTier` enum (`SILENT_HAPTIC`, `BACKGROUND_NOTIFICATION`, `OVERRIDE_SCREEN`), and common payload envelopes (`WebSocketPayload`, `ApprovalResponse`). Includes polymorphic serialization helpers.
|
||
|
|
* [UiPrimitiveTest.kt](file:///Users/blindmouse/meatbag/common/src/commonTest/kotlin/meatbag/common/UiPrimitiveTest.kt): Verifies correct serialization and parsing with class discriminators.
|
||
|
|
|
||
|
|
* **`:backend` (Ktor/JVM)**
|
||
|
|
* [Application.kt](file:///Users/blindmouse/meatbag/backend/src/main/kotlin/meatbag/backend/Application.kt): Scaffolds Ktor Netty, sets up CORS/WebSockets/ContentNegotiation plugins, exposes client-facing WebSocket (`/ws/connect`), response handler (`/api/respond`), agent request (`/api/request`), and diagnostic endpoints. Includes context-aware urgency auto-detection.
|
||
|
|
* [DeviceRegistry.kt](file:///Users/blindmouse/meatbag/backend/src/main/kotlin/meatbag/backend/DeviceRegistry.kt): Registers connected active client devices dynamically.
|
||
|
|
* [RoutingEngine.kt](file:///Users/blindmouse/meatbag/backend/src/main/kotlin/meatbag/backend/RoutingEngine.kt): Implements attention-based routing (e.g. routes urgent/silent haptics to Wear OS if active, otherwise falls back to phone/desktop) and holds coroutine suspend contexts via `CompletableDeferred` pending user callbacks.
|
||
|
|
* [RoutingEngineTest.kt](file:///Users/blindmouse/meatbag/backend/src/test/kotlin/meatbag/backend/RoutingEngineTest.kt): Fully verifies WebSocket connections, payload transmission, attention tier routing, and callback resume resolution under Ktor's `testApplication` engine.
|
||
|
|
|
||
|
|
* **`:client` (Compose Multiplatform / Desktop target)**
|
||
|
|
* [ComponentRegistry.kt](file:///Users/blindmouse/meatbag/client/src/commonMain/kotlin/meatbag/client/ComponentRegistry.kt): dynamic Compose renderer converting `UiPrimitive` polymorphically into premium, dark cyberpunk UI components using Unidirectional Data Flow (UDF) callbacks.
|
||
|
|
* [MeatbagClient.kt](file:///Users/blindmouse/meatbag/client/src/commonMain/kotlin/meatbag/client/MeatbagClient.kt): Manages WebSocket connections and POST responses. Decodes payloads and triggers simulated attention effects (vibrations, sound chimes, or display takeover overlays).
|
||
|
|
* [Main.kt](file:///Users/blindmouse/meatbag/client/src/desktopMain/kotlin/meatbag/client/Main.kt): Cyberpunk glassmorphic client simulator. Displays connection logs and simulates haptic profiles (Smartwatch vs. Phone vs. Desktop) and injects local offline mock payloads for isolated UI debugging.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 3. Configuration & Dependency Fixes Applied
|
||
|
|
During compilation and verification, several compatibility fixes were successfully applied:
|
||
|
|
1. **Plugin Portal Registration**: Configured `gradlePluginPortal()` in `settings.gradle.kts` to allow resolution of the Ktor and Kotlin JVM plugins.
|
||
|
|
2. **Kotlin Compiler Version Alignment**: Managed Kotlin compiler plugin versions centrally in the root `build.gradle.kts` and applied them cleanly inside sub-modules to prevent classloader duplicate classpath conflicts.
|
||
|
|
3. **Obsolete Property Removal**: Removed the obsolete `kotlin.mpp.enableGranularSourceSetsMetadata=true` from `gradle.properties` to fix Kotlin Gradle compiler configuration errors.
|
||
|
|
4. **Client Test Classpath**: Added Ktor Client content negotiation and websocket JVM targets to `:backend` test dependencies so that Ktor's test client works flawlessly during JUnit runs.
|
||
|
|
5. **Client Simulator Fixes**:
|
||
|
|
* Fixed window size dimensions to use `Dp` units (`1280.dp`, `800.dp`).
|
||
|
|
* Resolved Ktor 2.x `Frame.Text` read extension function resolution by importing `io.ktor.websocket.readText`.
|
||
|
|
* Refactored client `log` helpers to be non-suspending (using flow `tryEmit` instead of `emit`), and introduced a public `injectMockEvent` helper to safely feed mock events from the simulator UI without coroutine thread blocks.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 4. Current Status
|
||
|
|
* **Compilation Status**: `BUILD SUCCESSFUL` for all modules and targets.
|
||
|
|
* **Testing Status**: Common serialization and backend integration routing tests pass successfully.
|
||
|
|
* **Active Subagents**: Cleaned up and terminated all background subagent processes.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 5. Next Steps
|
||
|
|
1. **Develop Android/Wear OS Platform Code**: Implement physical haptic motor triggers (`Vibrator` and `VibratorManager`) in `wearMain` and push banner notifications in `androidMain`.
|
||
|
|
2. **Persistence Layer**: Implement a database (e.g., SQLite via SQLDelight or PostgreSQL) to persist user rule-sets and past agent requests.
|
||
|
|
3. **Authentication**: Secure endpoints using API keys for CLI agents and OAuth/Device Tokens for clients.
|