73 lines
4.8 KiB
Markdown
73 lines
4.8 KiB
Markdown
# Manual Slop: Architectural Technical Reference
|
|
|
|
A deep-dive into the asynchronous orchestration, state synchronization, and the "Linear Execution Clutch" of the Manual Slop engine. This document is designed to move the reader from a high-level mental model to a low-level implementation understanding.
|
|
|
|
---
|
|
|
|
## 1. Philosophy: The Decoupled State Machine
|
|
|
|
Manual Slop is built on a single, core realization: **AI reasoning is high-latency and non-deterministic, while GUI interaction must be low-latency and responsive.**
|
|
|
|
To solve this, the engine enforces a strict decoupling between three distinct boundaries:
|
|
|
|
* **The GUI Boundary (Main Thread):** A retained-mode loop (ImGui) that must never block. It handles visual telemetry and user "Seal of Approval" actions.
|
|
* **The AI Boundary (Daemon Threads):** Stateless execution loops that handle the "heavy lifting" of context aggregation, LLM communication, and tool reasoning.
|
|
* **The Orchestration Boundary (Asyncio):** A background thread that manages the flow of data between the other two, ensuring thread-safe communication without blocking the UI.
|
|
|
|
---
|
|
|
|
## 2. System Lifetime & Initialization
|
|
|
|
The application lifecycle, managed by `App` in `gui_2.py`, follows a precise sequence to ensure the environment is ready before the first frame:
|
|
|
|
1. **Context Hydration:** The engine reads `config.toml` (global) and `<project>.toml` (local). This builds the initial "world view" of the project—what files are tracked, what the discussion history is, and which AI models are active.
|
|
2. **Thread Bootstrapping:**
|
|
* The `Asyncio` event loop thread is started (`_loop_thread`).
|
|
* The `HookServer` (FastAPI) is started as a daemon to handle IPC.
|
|
3. **UI Entry:** The main thread enters `immapp.run()`. At this point, the GUI is "alive," and the background threads are ready to receive tasks.
|
|
4. **The Dual-Flush Shutdown:** On exit, the system commits state back to both project and global configs. This ensures that your window positions, active discussions, and even pending tool results are preserved for the next session.
|
|
|
|
---
|
|
|
|
## 3. The Task Pipeline: Producer-Consumer Synchronization
|
|
|
|
Because ImGui state cannot be safely modified from a background thread, Manual Slop uses a **Producer-Consumer** model for all updates.
|
|
|
|
### The Flow of an AI Request
|
|
1. **Produce:** When you click "Gen + Send," the GUI thread produces a `UserRequestEvent` and pushes it into the `AsyncEventQueue`.
|
|
2. **Consume:** The background `asyncio` loop pops this event and dispatches it to the `ai_client`. The GUI thread remains free to render and respond to other inputs.
|
|
3. **Task Backlog:** When the AI responds, the background thread *cannot* update the UI text boxes directly. Instead, it appends a **Task Dictionary** to the `_pending_gui_tasks` list.
|
|
4. **Sync:** On every frame, the GUI thread checks this list. If tasks exist, it acquires a lock, clears the list, and executes the updates (e.g., "Set AI response text," "Blink the terminal indicator").
|
|
|
|
---
|
|
|
|
## 4. The Execution Clutch: Human-In-The-Loop (HITL)
|
|
|
|
The "Execution Clutch" is our answer to the "Black Box" problem of AI. It allows you to shift from automatic execution to a manual, deterministic step-through mode.
|
|
|
|
### How the "Shifting" Works
|
|
When the AI requests a destructive action (like running a PowerShell script), the background execution thread is **suspended** using a `threading.Condition`:
|
|
|
|
1. **The Pause:** The thread enters a `.wait()` state. It is physically blocked.
|
|
2. **The Modal:** A task is sent to the GUI to open a modal dialog.
|
|
3. **The Mutation:** The user can read the script, edit it, or reject it.
|
|
4. **The Unleash:** When the user clicks "Approve," the GUI thread updates the shared state and calls `.notify_all()`. The background thread "wakes up," executes the (potentially modified) script, and reports the result back to the AI.
|
|
|
|
---
|
|
|
|
## 5. Security: The MCP Allowlist
|
|
|
|
To prevent "hallucinated" file access, every filesystem tool (read, list, search) is gated by the **MCP (Model Context Protocol) Bridge**:
|
|
|
|
* **Resolution:** Every path requested by the AI is resolved to an absolute path.
|
|
* **Checking:** It is verified against the project's `base_dir`. If the AI tries to `read_file("C:/Windows/System32/...")`, the bridge intercepts the call and returns an `ACCESS DENIED` error to the model before the OS is ever touched.
|
|
|
|
---
|
|
|
|
## 6. Telemetry & Auditing
|
|
|
|
Every interaction in Manual Slop is designed to be auditable:
|
|
* **JSON-L Comms Logs:** Raw API traffic is logged for debugging and token cost analysis.
|
|
* **Generated Scripts:** Every script that passes through the "Clutch" is saved to `scripts/generated/`.
|
|
* **Performance Monitor:** Real-time metrics (FPS, Frame Time, Input Lag) are tracked and can be queried via the Hook API to ensure the UI remains "fluid" under load.
|