# 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.