ed/manual_slop
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(conductor): Expert-level architectural documentation refresh

Browse Source
This commit is contained in:
Edward R. Gonzalez
2026-03-01 09:19:48 -05:00
parent 7384df1e29
commit bf4468f125
8 changed files with 263 additions and 195 deletions
Download Patch File Download Diff File Expand all files Collapse all files

83
docs/guide_tools.md
View File

@@ -1,58 +1,65 @@
# Guide: Tooling
# Manual Slop: Tooling & IPC Technical Reference
Overview of the tool dispatch and execution model.
A deep-dive into the Model Context Protocol (MCP) bridge, the Hook API, and the "Human-in-the-Loop" communication protocol.
---
The agent is provided two classes of tools: Read-Only MCP Tools, and a Destructive Execution Loop.
## 1. The MCP Bridge: Filesystem Security
## 1. Read-Only Context (MCP Tools)
The AI's ability to interact with your filesystem is mediated by a strict security allowlist.
Implemented in mcp_client.py. These tools allow the AI to selectively expand its knowledge of the codebase without requiring the user to dump entire 10,000-line files into the static context prefix.
### 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.
### Security & Scope
### 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.
Every **filesystem** MCP tool passes its arguments through `_resolve_and_check`. This function ensures that the requested path falls under one of the allowed directories defined in the GUI's Base Dir configurations.
If the AI attempts to read or search a path outside the project bounds, the tool safely catches the constraint violation and returns ACCESS DENIED.
---
The two **web tools** (`web_search`, `fetch_url`) bypass this check entirely — they have no filesystem access and are unrestricted.
## 2. The Hook API: Remote Control & Telemetry
### Supplied Tools:
Manual Slop exposes a REST-based IPC interface (running by default on port `8999`) to facilitate automated verification and external monitoring.
**Filesystem tools** (access-controlled via `_resolve_and_check`):
* `read_file(path)`: Returns the raw UTF-8 text of a file.
* `list_directory(path)`: Returns a formatted table of a directory's contents, showing file vs dir and byte sizes.
* `search_files(path, pattern)`: Executes a glob search (e.g., `**/*.py`) within an allowed directory.
* `get_file_summary(path)`: Invokes the local `summarize.py` heuristic parser to get the AST structure of a file without reading the whole body.
### 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).
**Web tools** (unrestricted — no filesystem access):
* `web_search(query)`: Queries DuckDuckGo's raw HTML endpoint and returns the top 5 results (title, URL, snippet) using a native `_DDGParser` (HTMLParser subclass) to avoid heavy dependencies.
* `fetch_url(url)`: Downloads a target webpage and strips out all scripts, styling, and structural HTML via `_TextExtractor`, returning only the raw prose content (clamped to 40,000 characters). Automatically resolves DuckDuckGo redirect links.
### 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.
## 2. Destructive Execution (run_powershell)
---
The core manipulation mechanism. This is a single, heavily guarded tool.
## 3. The HITL IPC Flow: `ask/respond`
### Flow
Manual Slop supports a synchronous "Human-in-the-Loop" request pattern for operations requiring explicit confirmation or manual data mutation.
1. The AI generates a 'run_powershell' payload containing a PowerShell script.
2. The AI background thread calls confirm_and_run_callback (injected by gui_legacy.py).
3. The background thread blocks completely, creating a modal popup on the main GUI thread.
4. The user reads the script and chooses to Approve or Reject.
5. If Approved, shell_runner.py executes the script using -NoProfile -NonInteractive -Command within the specified base_dir.
6. The combined stdout, stderr, and EXIT CODE are captured and returned to the AI in the tool result block.
### 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.
### AI Guidelines
This pattern is the foundation of the **Execution Clutch**, ensuring that no destructive action occurs without an auditable human signal.
The core system prompt explicitly guides the AI on how to use this tool safely:
---
* Prefer targeted replacements (using PowerShell's .Replace()) over full rewrites where possible.
* If a file is large and complex (requiring specific escape characters), do not attempt an inline python -c script. Instead, use a PowerShell here-string (@'...'@) to write a temporary python helper script to disk, execute the python script, and then delete it.
## 4. Synthetic Context Refresh
### Synthetic Context Refresh
After the **last** tool call in each round finishes (when multiple tools are called in a single round, the refresh happens once after all of them), ai_client runs `_reread_file_items`. It fetches the latest disk state of all files in the current project context. The `file_items` variable is reassigned so subsequent tool rounds within the same request use the fresh content.
For Anthropic, the refreshed contents are injected as a text block in the `tool_results` user message. For Gemini, they are appended to the last function response's output string. In both cases, the block is prefixed with `[FILES UPDATED]` / `[SYSTEM: FILES UPDATED]`.
On the next tool round, stale file-refresh blocks from previous rounds are stripped from history to prevent token accumulation. This means if the AI writes to a file, it instantly "sees" the modification in its next turn without having to waste a cycle calling `read_file`, and the cost of carrying the full file snapshot is limited to one round.
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.