manual_slop/docs/guide_tools.md

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