You've already forked zblade.dev
chore(deps): bump Astro and refresh changelog docs
- Update Astro, RSS, and TypeScript versions in the lockfile - Refresh tool call documentation and changelog page
This commit is contained in:
+449
-302
@@ -1,46 +1,74 @@
|
||||
# Zaguán Blade Tool Calls Reference
|
||||
|
||||
This document describes the regular tool calls that Zaguán Blade supports. These are the tools you can add to your Local AI system prompts to extend usability.
|
||||
This document lists the tool calls that are actually executable in the local `zblade` runtime.
|
||||
|
||||
> **Note:** This does not cover Blade-specific or ZLP (Zaguán Language Protocol) tools. These are standard file/editor tools for general AI coding assistance.
|
||||
It intentionally excludes:
|
||||
|
||||
- **ZLP-related tooling**
|
||||
- **Anything handled server-side by `zcoderd`**
|
||||
- **Schema-only entries that are not currently executed by `zblade`**
|
||||
|
||||
The authoritative implementation lives in `src-tauri/src/tools.rs`.
|
||||
|
||||
---
|
||||
|
||||
## File Operations
|
||||
## Scope
|
||||
|
||||
These tools are the ones `zblade` can execute locally in its own tool executor.
|
||||
|
||||
Excluded server-side tools include:
|
||||
|
||||
- `ask_followup_question`
|
||||
- `attempt_completion`
|
||||
- `new_task`
|
||||
- `generate_image`
|
||||
- `todo_write`
|
||||
|
||||
Also excluded from this document:
|
||||
|
||||
- `symbol_references` because it is present in tool schema definitions but is **not currently dispatched by the local executor**.
|
||||
|
||||
---
|
||||
|
||||
## File Tools
|
||||
|
||||
### `read_file`
|
||||
|
||||
Read the complete contents of a file.
|
||||
Read the full contents of a file.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
|------|------|----------|-------------|
|
||||
| `path` | string | Yes | File path (relative to workspace or absolute) |
|
||||
| `path` | string | Yes | File path |
|
||||
|
||||
**Aliases:** `file_path`, `filepath`, `filename`
|
||||
**Accepted aliases for `path`:** `file_path`, `filepath`, `filename`
|
||||
|
||||
**Example:**
|
||||
|
||||
```json
|
||||
{
|
||||
"path": "src/main.rs"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `read_file_range`
|
||||
|
||||
Read a specific line range from a file with optional context.
|
||||
Read a specific line range from a file, with optional surrounding context.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
|------|------|----------|-------------|
|
||||
| `path` | string | Yes | File path |
|
||||
| `start_line` | integer | No | Start line (1-indexed, default: 1) |
|
||||
| `end_line` | integer | No | End line (1-indexed, default: end of file) |
|
||||
| `context_lines` | integer | No | Extra context lines before/after range (default: 0) |
|
||||
| `start_line` | integer | No | Start line, 1-indexed. Defaults to `1`. |
|
||||
| `end_line` | integer | No | End line, 1-indexed. Defaults to end of file. |
|
||||
| `context_lines` | integer | No | Extra lines before and after the requested range. Defaults to `0`. |
|
||||
|
||||
**Accepted aliases for `path`:** `file_path`, `filepath`, `filename`
|
||||
|
||||
**Example:**
|
||||
|
||||
```json
|
||||
{
|
||||
"path": "src/lib.rs",
|
||||
@@ -50,21 +78,28 @@ Read a specific line range from a file with optional context.
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
### `write_file`
|
||||
|
||||
### `write_file` / `create_file`
|
||||
Write content to a file. Parent directories are created if needed.
|
||||
|
||||
Write content to a file. Creates parent directories if needed.
|
||||
### `create_file`
|
||||
|
||||
Alias of `write_file`.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
|------|------|----------|-------------|
|
||||
| `path` | string | Yes | File path |
|
||||
| `content` | string | Yes | Content to write |
|
||||
| `path` | string | Yes | Target file path |
|
||||
| `content` | string | Yes | File contents |
|
||||
|
||||
**Aliases for content:** `contents`, `text`, `data`
|
||||
**Accepted aliases:**
|
||||
|
||||
- `path`: `file_path`, `filepath`, `filename`
|
||||
- `content`: `contents`, `text`, `data`
|
||||
|
||||
**Example:**
|
||||
|
||||
```json
|
||||
{
|
||||
"path": "src/new_module.rs",
|
||||
@@ -72,415 +107,483 @@ Write content to a file. Creates parent directories if needed.
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `edit_file`
|
||||
|
||||
Apply a search/replace edit to a file (legacy tool).
|
||||
Legacy single search/replace edit tool.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
|------|------|----------|-------------|
|
||||
| `path` | string | Yes | File path |
|
||||
| `old_content` | string | Yes | Text to find |
|
||||
| `new_content` | string | Yes | Replacement text |
|
||||
|
||||
**Aliases:** `old`/`from` for old_content, `new`/`to` for new_content
|
||||
**Accepted aliases:**
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"path": "src/main.rs",
|
||||
"old_content": "fn old_function()",
|
||||
"new_content": "fn new_function()"
|
||||
}
|
||||
```
|
||||
- `path`: `file_path`, `filepath`, `filename`
|
||||
- `old_content`: `old`, `from`
|
||||
- `new_content`: `new`, `to`
|
||||
|
||||
---
|
||||
### `apply_patch`
|
||||
|
||||
### `apply_edit` / `apply_patch`
|
||||
Preferred patch/edit tool for search/replace edits.
|
||||
|
||||
Apply search/replace edits with robust fuzzy matching. Supports both single patches and atomic multi-patch operations.
|
||||
### `apply_edit`
|
||||
|
||||
Alias of `apply_patch`.
|
||||
|
||||
Supports both a single replacement and an atomic multi-patch mode.
|
||||
|
||||
**Single-patch parameters:**
|
||||
|
||||
**Single Patch Parameters:**
|
||||
| Name | Type | Required | Description |
|
||||
|------|------|----------|-------------|
|
||||
| `path` | string | Yes | File path |
|
||||
| `old_text` | string | Yes | Text to find and replace |
|
||||
| `old_text` | string | Yes | Exact text to replace |
|
||||
| `new_text` | string | Yes | Replacement text |
|
||||
|
||||
**Multi-Patch Parameters:**
|
||||
**Multi-patch parameters:**
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
|------|------|----------|-------------|
|
||||
| `path` | string | Yes | File path |
|
||||
| `patches` | array | Yes | Array of patch objects |
|
||||
|
||||
Each patch object contains:
|
||||
- `old_text` (string): Text to find
|
||||
- `new_text` (string): Replacement text
|
||||
- `start_line` (integer, optional): Hint for disambiguation
|
||||
- `end_line` (integer, optional): Hint for disambiguation
|
||||
Each patch object supports:
|
||||
|
||||
**Single Patch Example:**
|
||||
```json
|
||||
{
|
||||
"path": "src/lib.rs",
|
||||
"old_text": "let x = 5;",
|
||||
"new_text": "let x = 10;"
|
||||
}
|
||||
```
|
||||
- `old_text` — required
|
||||
- `new_text` — required
|
||||
- `start_line` — optional hint
|
||||
- `end_line` — optional hint
|
||||
|
||||
**Multi-Patch Example:**
|
||||
```json
|
||||
{
|
||||
"path": "src/lib.rs",
|
||||
"patches": [
|
||||
{"old_text": "fn foo()", "new_text": "fn bar()"},
|
||||
{"old_text": "let a = 1;", "new_text": "let a = 2;"}
|
||||
]
|
||||
}
|
||||
```
|
||||
**Accepted aliases in single-patch mode:**
|
||||
|
||||
> **Note:** Multi-patch operations are atomic - all patches are validated before any are applied. If any patch fails, no changes are made.
|
||||
- `path`: `file_path`, `filepath`, `filename`
|
||||
- `old_text`: `old_content`, `old`, `from`
|
||||
- `new_text`: `new_content`, `new`, `to`
|
||||
|
||||
---
|
||||
**Important behavior:**
|
||||
|
||||
- Matching is exact.
|
||||
- If the match is ambiguous, the edit fails.
|
||||
- Multi-patch application is atomic: if one patch fails validation, none are applied.
|
||||
|
||||
### `delete_file`
|
||||
|
||||
Delete a file or directory.
|
||||
Delete a file, or a directory when `recursive: true` is provided.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
|------|------|----------|-------------|
|
||||
| `path` | string | Yes | Path to delete |
|
||||
| `recursive` | boolean | No | Required for directories (default: false) |
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"path": "temp/old_file.txt"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
| `recursive` | boolean | No | Required when deleting a directory |
|
||||
|
||||
### `move_file`
|
||||
|
||||
Move or rename a file.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
|------|------|----------|-------------|
|
||||
| `source` | string | Yes | Source path |
|
||||
| `destination` | string | Yes | Destination path |
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"source": "src/old_name.rs",
|
||||
"destination": "src/new_name.rs"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `copy_file`
|
||||
|
||||
Copy a file or directory (recursive for directories).
|
||||
Copy a file or recursively copy a directory.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
|------|------|----------|-------------|
|
||||
| `source` | string | Yes | Source path |
|
||||
| `destination` | string | Yes | Destination path |
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"source": "templates/base.html",
|
||||
"destination": "src/templates/base.html"
|
||||
}
|
||||
```
|
||||
### `create_directory`
|
||||
|
||||
---
|
||||
Create a directory and any missing parent directories.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
|------|------|----------|-------------|
|
||||
| `path` | string | Yes | Directory path |
|
||||
|
||||
### `get_file_info`
|
||||
|
||||
Get metadata about a file or directory.
|
||||
Return basic filesystem metadata.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
|------|------|----------|-------------|
|
||||
| `path` | string | Yes | Path to inspect |
|
||||
|
||||
**Returns:** JSON with `path`, `size`, `is_directory`, `is_file`, `modified`, `readonly`
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"path": "Cargo.toml"
|
||||
}
|
||||
```
|
||||
**Returns:** JSON including `path`, `size`, `is_directory`, `is_file`, `modified`, and `readonly`.
|
||||
|
||||
---
|
||||
|
||||
### `create_directory`
|
||||
## Directory and Search Tools
|
||||
|
||||
Create a directory (and parent directories if needed).
|
||||
### `list_dir`
|
||||
|
||||
List directory contents using a compact tree-like view.
|
||||
|
||||
### `list_directory`
|
||||
|
||||
Alias of `list_dir`.
|
||||
|
||||
This is implemented by forwarding to `get_workspace_structure` with a default shallow depth.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
|------|------|----------|-------------|
|
||||
| `path` | string | Yes | Directory path to create |
|
||||
| `path` | string | No | Directory path. Defaults to `.`. |
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"path": "src/modules/new_feature"
|
||||
}
|
||||
```
|
||||
**Notes:**
|
||||
|
||||
---
|
||||
|
||||
## Directory & Search Tools
|
||||
|
||||
### `list_directory` / `list_dir`
|
||||
|
||||
List directory contents with tree view.
|
||||
|
||||
**Parameters:**
|
||||
| Name | Type | Required | Description |
|
||||
|------|------|----------|-------------|
|
||||
| `path` | string | No | Directory path (default: ".") |
|
||||
| `max_depth` | integer | No | Max traversal depth (default: 1) |
|
||||
|
||||
**Aliases:** `dir`, `directory`
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"path": "src",
|
||||
"max_depth": 2
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
- `list_dir` / `list_directory` exists mainly as a compatibility entry point.
|
||||
- The underlying structured traversal behavior is defined by `get_workspace_structure`.
|
||||
- Prefer `get_workspace_structure` when you need explicit traversal controls.
|
||||
|
||||
### `get_workspace_structure`
|
||||
|
||||
Get a tree view of the workspace structure.
|
||||
Return a tree view of the workspace or a subdirectory.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
|------|------|----------|-------------|
|
||||
| `path` | string | No | Starting path (default: ".") |
|
||||
| `depth` | integer | No | Max depth (default: 2) |
|
||||
| `limit` | integer | No | Max entries (default: 50, max: 200) |
|
||||
| `path` | string | No | Starting path. Defaults to `.`. |
|
||||
| `depth` | integer | No | Max traversal depth. Defaults to `2`. |
|
||||
| `limit` | integer | No | Max returned entries. Defaults to `50`, capped at `200`. |
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"path": ".",
|
||||
"depth": 3,
|
||||
"limit": 100
|
||||
}
|
||||
```
|
||||
**Accepted aliases for `path`:** `dir`, `directory`
|
||||
|
||||
> **Note:** Automatically ignores common directories like `node_modules`, `target`, `.git`, `__pycache__`, etc.
|
||||
**Behavior notes:**
|
||||
|
||||
---
|
||||
- Hidden files are skipped.
|
||||
- Common heavy/generated directories are skipped.
|
||||
- Gitignored paths are filtered when project settings enable that behavior.
|
||||
|
||||
### `find_files`
|
||||
|
||||
Find files by name pattern (substring match).
|
||||
Find files by substring match on filename.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
|------|------|----------|-------------|
|
||||
| `pattern` | string | Yes | Substring to match in filenames |
|
||||
| `path` | string | No | Starting path (default: workspace root) |
|
||||
| `max_depth` | integer | No | Max search depth |
|
||||
| `pattern` | string | Yes | Substring to match in entry names |
|
||||
| `path` | string | No | Search root inside the workspace |
|
||||
| `max_depth` | integer | No | Optional max traversal depth |
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"pattern": "test",
|
||||
"path": "src",
|
||||
"max_depth": 5
|
||||
}
|
||||
```
|
||||
### `find_files_glob`
|
||||
|
||||
---
|
||||
Find files with a glob pattern.
|
||||
|
||||
### `find_files_glob` / `glob`
|
||||
### `glob`
|
||||
|
||||
Find files using glob patterns.
|
||||
Alias of `find_files_glob`.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
|------|------|----------|-------------|
|
||||
| `pattern` | string | Yes | Glob pattern (e.g., `**/*.rs`) |
|
||||
| `path` | string | No | Base path for search |
|
||||
| `case_sensitive` | boolean | No | Case-sensitive matching (default: false) |
|
||||
| `pattern` | string | Yes | Glob pattern |
|
||||
| `path` | string | No | Optional base path |
|
||||
| `case_sensitive` | boolean | No | Whether matching is case-sensitive |
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"pattern": "**/*.tsx",
|
||||
"path": "src"
|
||||
}
|
||||
```
|
||||
**Accepted aliases:**
|
||||
|
||||
---
|
||||
- `pattern`: `glob`
|
||||
|
||||
### `grep_search` / `rg`
|
||||
### `grep_search`
|
||||
|
||||
Search file contents using regex patterns.
|
||||
Search file contents with a regular expression.
|
||||
|
||||
### `rg`
|
||||
|
||||
Alias of `grep_search`.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
|------|------|----------|-------------|
|
||||
| `pattern` | string | Yes | Regex pattern to search |
|
||||
| `path` | string | No | Directory to search (default: ".") |
|
||||
| `pattern` | string | Yes | Regex pattern |
|
||||
| `path` | string | No | Search root. Defaults to `.`. |
|
||||
| `include_dependencies` | boolean | No | Include dependency directories like `node_modules` and `vendor` |
|
||||
| `timeout_ms` | integer | No | Timeout used when timeout enforcement is enabled |
|
||||
|
||||
**Aliases for pattern:** `query`, `regex`
|
||||
**Accepted aliases:**
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"pattern": "fn\\s+main",
|
||||
"path": "src"
|
||||
}
|
||||
```
|
||||
- `pattern`: `query`, `regex`
|
||||
- `path`: `dir`, `directory`
|
||||
|
||||
**Returns:** Matches in format `filepath:line_number:line_content`
|
||||
**Behavior notes:**
|
||||
|
||||
---
|
||||
- Returns matches in `path:line:text` form on success.
|
||||
- If timeout enforcement is enabled and the search times out, it returns structured JSON with partial results and a hint.
|
||||
|
||||
### `codebase_search`
|
||||
|
||||
Search codebase with context lines around matches.
|
||||
Search the codebase with regex and return matches with surrounding context.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
|------|------|----------|-------------|
|
||||
| `query` | string | Yes | Regex pattern to search |
|
||||
| `file_pattern` | string | No | Filter files (e.g., `*.rs,*.toml`) |
|
||||
| `max_results` | integer | No | Maximum results (default: 50) |
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"query": "struct.*Config",
|
||||
"file_pattern": "*.rs",
|
||||
"max_results": 20
|
||||
}
|
||||
```
|
||||
|
||||
**Returns:** Matches with 2 lines of context before and after.
|
||||
| `query` | string | Yes | Regex pattern |
|
||||
| `file_pattern` | string | No | Comma-separated filename patterns |
|
||||
| `max_results` | integer | No | Max number of matches to return. Defaults to `50`. |
|
||||
|
||||
---
|
||||
|
||||
## Editor Interaction Tools
|
||||
## Editor and UI Interaction Tools
|
||||
|
||||
### `get_editor_state`
|
||||
|
||||
Get current editor context including active file, cursor position, and open files.
|
||||
Return the current local editor context.
|
||||
|
||||
**Parameters:** None
|
||||
**Parameters:** None.
|
||||
|
||||
**Returns:** JSON with:
|
||||
- `active_file`: Currently focused file
|
||||
- `open_files`: List of open file paths
|
||||
- `active_tab_index`: Index of active tab
|
||||
- `cursor_line`, `cursor_column`: Cursor position
|
||||
- `selection_start_line`, `selection_end_line`: Selection range
|
||||
**Returns:** JSON including:
|
||||
|
||||
---
|
||||
- `active_file`
|
||||
- `open_files`
|
||||
- `active_tab_index`
|
||||
- `cursor_line`
|
||||
- `cursor_column`
|
||||
- `selection_start_line`
|
||||
- `selection_end_line`
|
||||
|
||||
The returned text may also include human-readable helper guidance for the active file and cursor location.
|
||||
|
||||
### `open_file`
|
||||
|
||||
Open a file in the editor.
|
||||
Emit an editor action that opens a file, optionally at a line.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
|------|------|----------|-------------|
|
||||
| `path` | string | Yes | File path to open |
|
||||
| `path` | string | Yes | File to open |
|
||||
| `line` | integer | No | Line number to jump to |
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"path": "src/main.rs",
|
||||
"line": 42
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
**Note:** This returns an action payload for the frontend to intercept.
|
||||
|
||||
### `goto_line`
|
||||
|
||||
Navigate to a specific line in the active file.
|
||||
Emit an editor action that moves the cursor in the current file.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
|------|------|----------|-------------|
|
||||
| `line` | integer | Yes | Line number (1-indexed) |
|
||||
| `column` | integer | No | Column number |
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"line": 100,
|
||||
"column": 15
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
| `line` | integer | Yes | Target line |
|
||||
| `column` | integer | No | Optional target column |
|
||||
|
||||
### `get_selection`
|
||||
|
||||
Get the currently selected text in the editor.
|
||||
Request the current selection.
|
||||
|
||||
**Parameters:** None
|
||||
**Parameters:** None.
|
||||
|
||||
**Returns:** The selected text content.
|
||||
|
||||
---
|
||||
**Current status:** implemented only as a placeholder action payload. It does **not** currently return the true selected text.
|
||||
|
||||
### `replace_selection`
|
||||
|
||||
Replace the current selection with new content.
|
||||
Emit an editor action that replaces the current selection.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
|------|------|----------|-------------|
|
||||
| `content` | string | Yes | Replacement content |
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"content": "new replacement text"
|
||||
}
|
||||
```
|
||||
### `insert_at_cursor`
|
||||
|
||||
Emit an editor action that inserts content at the current cursor position.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
|------|------|----------|-------------|
|
||||
| `content` | string | Yes | Text to insert |
|
||||
|
||||
---
|
||||
|
||||
### `insert_at_cursor`
|
||||
## Local Code-Intelligence Tools
|
||||
|
||||
Insert content at the current cursor position.
|
||||
These tools are local to `zblade`. They are **not ZLP tools** and do not require `zcoderd`, but they do depend on `zblade`'s local language service / symbol index being available.
|
||||
|
||||
### `symbol_search`
|
||||
|
||||
Search indexed symbols by name or qualified name.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
|------|------|----------|-------------|
|
||||
| `content` | string | Yes | Content to insert |
|
||||
| `query` | string | Yes | Symbol query |
|
||||
| `path` | string | No | Restrict to a file |
|
||||
| `kind` | string | No | Symbol kind filter |
|
||||
| `limit` | integer | No | Max results. Defaults to `20`, capped at `100`. |
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"content": "// TODO: implement this\n"
|
||||
}
|
||||
```
|
||||
**Accepted aliases:**
|
||||
|
||||
- `path`: `file`, `file_path`
|
||||
- `kind`: `symbol_type`
|
||||
|
||||
### `symbol_resolve`
|
||||
|
||||
Resolve one symbol by ID, or by file plus name.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
|------|------|----------|-------------|
|
||||
| `symbol_id` | string | Conditionally | Stable symbol ID |
|
||||
| `path` | string | Conditionally | Required when resolving by file-scoped lookup |
|
||||
| `qualified_name` | string | No | Exact qualified name |
|
||||
| `name` | string | No | Simple symbol name |
|
||||
|
||||
**Accepted aliases:**
|
||||
|
||||
- `symbol_id`: `id`
|
||||
- `path`: `file`, `file_path`
|
||||
|
||||
**Rule:** provide either `symbol_id`, or a `path` with a symbol name selector.
|
||||
|
||||
### `symbol_outline`
|
||||
|
||||
Return the hierarchical symbol outline for one file.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
|------|------|----------|-------------|
|
||||
| `path` | string | Yes | File path |
|
||||
|
||||
**Accepted aliases for `path`:** `file`, `file_path`
|
||||
|
||||
### `symbol_graph`
|
||||
|
||||
Return incoming and outgoing graph edges for a symbol.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
|------|------|----------|-------------|
|
||||
| `symbol_id` | string | Conditionally | Stable symbol ID |
|
||||
| `path` | string | Conditionally | File path when resolving by file/name |
|
||||
| `qualified_name` | string | No | Exact qualified name |
|
||||
| `name` | string | No | Simple symbol name |
|
||||
| `relationship_type` | string | No | Edge type. Defaults to `call`. |
|
||||
| `limit` | integer | No | Max edges. Defaults to `20`, capped at `100`. |
|
||||
|
||||
**Accepted aliases:**
|
||||
|
||||
- `symbol_id`: `id`
|
||||
- `path`: `file`, `file_path`
|
||||
- `relationship_type`: `edge_kind`, `kind`
|
||||
|
||||
---
|
||||
|
||||
## Project Index Tools
|
||||
|
||||
These tools read the local `.zblade/context/project_index.md` artifact, or a semantic overview generated by the local language service when available.
|
||||
|
||||
### `get_project_index_overview`
|
||||
|
||||
Read a compact overview window from the local project index.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
|------|------|----------|-------------|
|
||||
| `path` | string | No | Optional workspace sub-root |
|
||||
| `max_chars` | integer | No | Character budget. Defaults to `6000`, capped at `12000`. |
|
||||
| `offset` | integer | No | Character offset |
|
||||
|
||||
### `get_project_index_chunk`
|
||||
|
||||
Read a deterministic paged chunk from the local project index.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
|------|------|----------|-------------|
|
||||
| `path` | string | No | Optional workspace sub-root |
|
||||
| `offset` | integer | No | Character offset |
|
||||
| `max_chars` | integer | No | Character budget. Defaults to `4000`, capped at `8000`. |
|
||||
|
||||
---
|
||||
|
||||
## Composite Read-Only Tools
|
||||
|
||||
These tools are supported by `zblade` locally.
|
||||
|
||||
By default, schema exposure may be gated by model family and the `composite_tools_enabled` feature flag, but the local executor does support them.
|
||||
|
||||
### `read_many_files`
|
||||
|
||||
Read multiple files selected by glob patterns in a single bounded call.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
|------|------|----------|-------------|
|
||||
| `paths` | array of strings | Yes | Include globs |
|
||||
| `exclude` | array of strings | No | Exclude globs |
|
||||
| `max_files` | integer | No | Max files. Defaults to `100`, capped at `500`. |
|
||||
| `max_bytes_per_file` | integer | No | Per-file byte limit. Defaults to `65536`, capped at `524288`. |
|
||||
| `include_line_numbers` | boolean | No | Include line numbers in returned content |
|
||||
|
||||
**Accepted aliases for include globs:** `globs`, `patterns`
|
||||
|
||||
### `batch`
|
||||
|
||||
Execute multiple read-only tool calls concurrently with all-settled behavior.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
|------|------|----------|-------------|
|
||||
| `calls` | array | Yes | Array of tool call objects |
|
||||
| `max_parallel` | integer | No | Defaults to `8`, capped at `16` |
|
||||
| `fail_fast` | boolean | No | Stop queued work after first failure |
|
||||
| `ordered` | boolean | No | Preserve input order. Defaults to `true`. |
|
||||
| `cancel_after_ms` | integer | No | Optional total budget |
|
||||
|
||||
Each call object supports:
|
||||
|
||||
- `tool` or `name`
|
||||
- `arguments`
|
||||
|
||||
**Important behavior:**
|
||||
|
||||
- Only read-only tools are allowed.
|
||||
- `batch` itself and `run_command` are explicitly blocked inside `batch`.
|
||||
|
||||
### `codebase_investigator`
|
||||
|
||||
Run a bounded read-only investigation pass and return structured findings.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
|------|------|----------|-------------|
|
||||
| `objective` | string | Yes | Investigation goal |
|
||||
| `scope` | array of strings | No | Glob scope. Defaults to `**/*`. |
|
||||
| `max_turns` | integer | No | Defaults to `8`, capped at `16` |
|
||||
| `max_tool_calls` | integer | No | Defaults to `40`, capped at `120` |
|
||||
| `output_format` | string | No | `json` or `markdown` |
|
||||
| `cancel_after_ms` | integer | No | Optional total budget |
|
||||
|
||||
---
|
||||
|
||||
@@ -488,63 +591,107 @@ Insert content at the current cursor position.
|
||||
|
||||
### `run_command`
|
||||
|
||||
Execute a shell command (requires user approval).
|
||||
Execute a command in the workspace. This requires approval in normal AI workflows.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
|------|------|----------|-------------|
|
||||
| `command` | string | Yes | Shell command to execute |
|
||||
| `cwd` | string | Yes | Working directory |
|
||||
| `command` | string | Conditionally | Legacy shell command line |
|
||||
| `program` | string | Conditionally | Executable path/name for structured execution |
|
||||
| `args` | array of strings | No | Structured arguments when using `program` |
|
||||
| `shell` | boolean | No | Force shell execution when using `program` |
|
||||
| `cwd` | string | No | Working directory |
|
||||
| `blocking` | boolean | No | Defaults to `true` |
|
||||
| `wait_ms_before_async` | integer | No | Startup wait when non-blocking |
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"command": "cargo build --release",
|
||||
"cwd": "."
|
||||
}
|
||||
```
|
||||
**Accepted aliases / alternate casing:**
|
||||
|
||||
> **Note:** This tool requires user confirmation before execution for safety.
|
||||
- `command`: `Command`, `command_line`, `CommandLine`
|
||||
- `program`: `Program`
|
||||
- `args`: `Args`
|
||||
- `shell`: `Shell`
|
||||
- `cwd`: `Cwd`
|
||||
- `blocking`: `Blocking`
|
||||
- `wait_ms_before_async`: `WaitMsBeforeAsync`
|
||||
|
||||
**Rule:** provide either `command` or `program`.
|
||||
|
||||
**Behavior notes:**
|
||||
|
||||
- If `program` is used, shell execution defaults to `false` unless explicitly enabled.
|
||||
- If `command` is used, shell execution is enabled.
|
||||
|
||||
---
|
||||
|
||||
## Tool Result Handling
|
||||
## General Notes
|
||||
|
||||
Tool results are automatically truncated if they exceed limits:
|
||||
- **Max size:** 50KB
|
||||
- **Max lines:** 2000
|
||||
### Result truncation
|
||||
|
||||
When truncated, the first 100 lines and last 50 lines are shown with a truncation message.
|
||||
Large tool results may be truncated.
|
||||
|
||||
- **Max size:** `50 KB`
|
||||
- **Max lines:** `2000`
|
||||
|
||||
When truncation happens, the executor keeps a head/tail summary rather than returning the entire payload.
|
||||
|
||||
### Path safety
|
||||
|
||||
Paths are generally constrained to the current workspace.
|
||||
|
||||
- Relative paths are resolved from the workspace root.
|
||||
- Absolute paths must still resolve inside the workspace when validation is enforced.
|
||||
|
||||
### Local vs advertised tools
|
||||
|
||||
This file documents what `zblade` can execute locally.
|
||||
|
||||
That is not always identical to what every model sees in advertised tool schemas:
|
||||
|
||||
- Some compatibility aliases are executor-only.
|
||||
- Some composite tools are feature-flag and model-family gated for schema exposure.
|
||||
- Some schema entries may exist before local execution support is complete.
|
||||
|
||||
---
|
||||
|
||||
## Path Resolution
|
||||
## Quick Reference
|
||||
|
||||
All paths can be:
|
||||
- **Relative:** Resolved from workspace root (e.g., `src/main.rs`)
|
||||
- **Absolute:** Used as-is (must be within workspace)
|
||||
### Locally executable non-server-side tools
|
||||
|
||||
Paths outside the workspace are rejected for security.
|
||||
|
||||
---
|
||||
|
||||
## Adding Tools to Your AI System Prompt
|
||||
|
||||
To use these tools with a local AI, include the tool definitions in your system prompt. Example format:
|
||||
|
||||
```
|
||||
You have access to the following tools:
|
||||
|
||||
- read_file: Read file contents. Args: {"path": "string"}
|
||||
- write_file: Write to file. Args: {"path": "string", "content": "string"}
|
||||
- grep_search: Search with regex. Args: {"pattern": "string", "path": "string"}
|
||||
- apply_edit: Edit file. Args: {"path": "string", "old_text": "string", "new_text": "string"}
|
||||
...
|
||||
|
||||
To use a tool, respond with:
|
||||
<tool_call>
|
||||
{"name": "tool_name", "arguments": {...}}
|
||||
</tool_call>
|
||||
```
|
||||
|
||||
The exact format depends on your AI provider's tool calling conventions.
|
||||
- `read_file`
|
||||
- `read_file_range`
|
||||
- `write_file`
|
||||
- `create_file`
|
||||
- `edit_file`
|
||||
- `apply_patch`
|
||||
- `apply_edit`
|
||||
- `delete_file`
|
||||
- `move_file`
|
||||
- `copy_file`
|
||||
- `create_directory`
|
||||
- `get_file_info`
|
||||
- `list_dir`
|
||||
- `list_directory`
|
||||
- `get_workspace_structure`
|
||||
- `find_files`
|
||||
- `find_files_glob`
|
||||
- `glob`
|
||||
- `grep_search`
|
||||
- `rg`
|
||||
- `codebase_search`
|
||||
- `get_editor_state`
|
||||
- `open_file`
|
||||
- `goto_line`
|
||||
- `get_selection`
|
||||
- `replace_selection`
|
||||
- `insert_at_cursor`
|
||||
- `symbol_search`
|
||||
- `symbol_resolve`
|
||||
- `symbol_outline`
|
||||
- `symbol_graph`
|
||||
- `get_project_index_overview`
|
||||
- `get_project_index_chunk`
|
||||
- `read_many_files`
|
||||
- `batch`
|
||||
- `codebase_investigator`
|
||||
- `run_command`
|
||||
|
||||
Reference in New Issue
Block a user