59 lines
4.0 KiB
Markdown
59 lines
4.0 KiB
Markdown
# Guide: Tooling
|
|
|
|
Overview of the tool dispatch and execution model.
|
|
|
|
---
|
|
|
|
The agent is provided two classes of tools: Read-Only MCP Tools, and a Destructive Execution Loop.
|
|
|
|
## 1. Read-Only Context (MCP Tools)
|
|
|
|
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.
|
|
|
|
### Security & Scope
|
|
|
|
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.
|
|
|
|
### Supplied Tools:
|
|
|
|
**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.
|
|
|
|
**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.
|
|
|
|
## 2. Destructive Execution (run_powershell)
|
|
|
|
The core manipulation mechanism. This is a single, heavily guarded tool.
|
|
|
|
### Flow
|
|
|
|
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.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.
|
|
|
|
### AI Guidelines
|
|
|
|
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.
|
|
|
|
### 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.
|