49 lines
2.2 KiB
Markdown
49 lines
2.2 KiB
Markdown
|
# Functional Spec: Agent Capabilities
|
||
|
|
|
||
|
|
## Overview
|
||
|
|
The Agent interacts with the Target Project through a set of deterministic Tools. These tools are exposed as Tauri Commands to the frontend, which acts as the orchestrator for the LLM.
|
||
|
|
|
||
|
|
## 1. Filesystem Tools
|
||
|
|
All filesystem operations are **strictly scoped** to the active `SessionState.project_root`. Attempting to access paths outside this root (e.g., `../foo`) must return an error.
|
||
|
|
|
||
|
|
### `read_file`
|
||
|
|
* **Input:** `path: String` (Relative to project root)
|
||
|
|
* **Output:** `Result<String, AppError>`
|
||
|
|
* **Behavior:** Returns the full text content of the file.
|
||
|
|
|
||
|
|
### `write_file`
|
||
|
|
* **Input:** `path: String`, `content: String`
|
||
|
|
* **Output:** `Result<(), AppError>`
|
||
|
|
* **Behavior:** Overwrites the file. Creates parent directories if they don't exist.
|
||
|
|
|
||
|
|
### `list_directory`
|
||
|
|
* **Input:** `path: String` (Relative)
|
||
|
|
* **Output:** `Result<Vec<FileEntry>, AppError>`
|
||
|
|
* **Data Structure:** `FileEntry { name: String, kind: "file" | "dir" }`
|
||
|
|
|
||
|
|
## 2. Search Tools
|
||
|
|
High-performance text search is critical for the Agent to "read" the codebase without dumping all files into context.
|
||
|
|
|
||
|
|
### `search_files`
|
||
|
|
* **Input:** `query: String` (Regex or Literal), `glob: Option<String>`
|
||
|
|
* **Output:** `Result<Vec<Match>, AppError>`
|
||
|
|
* **Engine:** Rust `ignore` crate (WalkBuilder) + `grep_searcher`.
|
||
|
|
* **Constraints:**
|
||
|
|
* Must respect `.gitignore`.
|
||
|
|
* Limit results (e.g., top 100 matches) to prevent freezing.
|
||
|
|
|
||
|
|
## 3. Shell Tools
|
||
|
|
The Agent needs to compile code, run tests, and manage git.
|
||
|
|
|
||
|
|
### `exec_shell`
|
||
|
|
* **Input:** `command: String`, `args: Vec<String>`
|
||
|
|
* **Output:** `Result<CommandOutput, AppError>`
|
||
|
|
* **Data Structure:** `CommandOutput { stdout: String, stderr: String, exit_code: i32 }`
|
||
|
|
* **Security Policy:**
|
||
|
|
* **Allowlist:** `git`, `cargo`, `npm`, `yarn`, `pnpm`, `node`, `bun`, `ls`, `find`, `grep`, `mkdir`, `rm`, `mv`, `cp`, `touch`.
|
||
|
|
* **cwd:** Always executed in `SessionState.project_root`.
|
||
|
|
* **Timeout:** Hard limit (e.g., 30s) to prevent hanging processes.
|
||
|
|
|
||
|
|
## Error Handling
|
||
|
|
All tools must return a standardized JSON error object to the frontend so the LLM knows *why* a tool failed (e.g., "File not found", "Permission denied").
|