66 lines
3.5 KiB
Markdown
66 lines
3.5 KiB
Markdown
# Manual Slop: Tooling & IPC Technical Reference
|
|
|
|
A deep-dive into the Model Context Protocol (MCP) bridge, the Hook API, and the "Human-in-the-Loop" communication protocol.
|
|
|
|
---
|
|
|
|
## 1. The MCP Bridge: Filesystem Security
|
|
|
|
The AI's ability to interact with your filesystem is mediated by a strict security allowlist.
|
|
|
|
### Path Resolution & Sandboxing
|
|
Every tool accessing the disk (e.g., `read_file`, `list_directory`, `search_files`) executes `_resolve_and_check(path)`:
|
|
1. **Normalization:** The requested path is converted to an absolute path.
|
|
2. **Constraint Check:** The path must reside within the project's `base_dir`.
|
|
3. **Enforcement:** Violations trigger a `PermissionError`, returned to the model as an `ACCESS DENIED` status.
|
|
|
|
### Native Toolset
|
|
* **`read_file(path)`:** UTF-8 extraction, clamped by token budgets.
|
|
* **`list_directory(path)`:** Returns a structural map (Name, Type, Size).
|
|
* **`get_file_summary(path)`:** AST-based heuristic parsing for high-signal architectural mapping without full-file read costs.
|
|
* **`web_search(query)`:** Scrapes DuckDuckGo raw HTML via a dependency-free parser.
|
|
|
|
---
|
|
|
|
## 2. The Hook API: Remote Control & Telemetry
|
|
|
|
Manual Slop exposes a REST-based IPC interface (running by default on port `8999`) to facilitate automated verification and external monitoring.
|
|
|
|
### Core Endpoints
|
|
* `GET /status`: Engine health and hook server readiness.
|
|
* `GET /mma_status`: Retrieves the 4-Tier state, active track metadata, and current ticket DAG status.
|
|
* `POST /api/gui`: Pushes events into the `AsyncEventQueue`.
|
|
* Payload example: `{"action": "set_value", "item": "current_provider", "value": "anthropic"}`
|
|
* `GET /diagnostics`: High-frequency telemetry for UI performance (FPS, CPU, Input Lag).
|
|
|
|
### ApiHookClient Implementation
|
|
The `api_hook_client.py` provides a robust wrapper for the Hook API:
|
|
* **Synchronous Wait:** `wait_for_server()` polls `/status` with exponential backoff.
|
|
* **State Polling:** `wait_for_value()` blocks until a specific GUI element matches an expected state.
|
|
* **Remote Interaction:** `click()`, `set_value()`, and `select_tab()` methods allow external agents to drive the GUI.
|
|
|
|
---
|
|
|
|
## 3. The HITL IPC Flow: `ask/respond`
|
|
|
|
Manual Slop supports a synchronous "Human-in-the-Loop" request pattern for operations requiring explicit confirmation or manual data mutation.
|
|
|
|
### Sequence of Operation
|
|
1. **Request:** A background agent (e.g., a Tier 3 Worker) calls `/api/ask` with a JSON payload.
|
|
2. **Intercept:** the `HookServer` generates a unique `request_id` and pushes a `type: "ask"` event to the GUI's `_pending_gui_tasks`.
|
|
3. **Modal Display:** The GUI renders an `Approve/Reject` modal with the payload details.
|
|
4. **Response:** Upon user action, the GUI thread `POST`s to `/api/ask/respond`.
|
|
5. **Resume:** The original agent call to `/api/ask` (which was polling for completion) unblocks and receives the user's response.
|
|
|
|
This pattern is the foundation of the **Execution Clutch**, ensuring that no destructive action occurs without an auditable human signal.
|
|
|
|
---
|
|
|
|
## 4. Synthetic Context Refresh
|
|
|
|
To minimize token churn and redundant `read_file` calls, the `ai_client` performs a post-tool-execution refresh:
|
|
1. **Detection:** Triggered after the final tool call in a reasoning round.
|
|
2. **Collection:** re-reads all project-tracked files from disk.
|
|
3. **Injection:** The updated content is injected into the next LLM turn as a `[SYSTEM: FILES UPDATED]` block.
|
|
4. **Pruning:** Older snapshots are stripped from history in subsequent rounds to maintain a lean context window.
|