feat: add a subagent frame

agentlite/docs/tools.md

@@ -0,0 +1,271 @@
+# AgentLite Tool Suite
+
+A comprehensive tool suite for AgentLite, inspired by kimi-cli's tools, with configuration support for enabling/disabling individual tools.
+
+## Overview
+
+This tool suite provides:
+
+- **File Operations**: Read, write, edit, search files
+- **Shell Execution**: Execute shell commands
+- **Web Access**: Fetch URLs and search the web
+- **Multi-Agent**: Task delegation and subagent creation
+- **Utilities**: Todo lists and thinking tools
+- **Configuration**: Fine-grained control over which tools are available
+
+## Installation
+
+The tool suite is included with AgentLite. No additional installation required.
+
+## Quick Start
+
+```python
+from agentlite.tools import ConfigurableToolset, ToolSuiteConfig
+from agentlite import Agent, OpenAIProvider
+
+# Create toolset with default config (all tools enabled)
+toolset = ConfigurableToolset()
+
+# Create agent with tools
+provider = OpenAIProvider(api_key="your-key", model="gpt-4")
+agent = Agent(
+    provider=provider,
+    system_prompt="You are a helpful assistant.",
+    tools=toolset.tools,
+)
+```
+
+## Configuration
+
+### Basic Configuration
+
+```python
+from agentlite.tools import (
+    ToolSuiteConfig,
+    FileToolsConfig,
+    ShellToolsConfig,
+)
+
+# Disable specific tools
+config = ToolSuiteConfig(
+    file_tools=FileToolsConfig(
+        tools={"WriteFile": False, "StrReplaceFile": False}
+    )
+)
+toolset = ConfigurableToolset(config)
+```
+
+### Disable Entire Tool Groups
+
+```python
+# Disable all shell tools
+config = ToolSuiteConfig(
+    shell_tools=ShellToolsConfig(enabled=False)
+)
+toolset = ConfigurableToolset(config)
+```
+
+### Custom Tool Settings
+
+```python
+config = ToolSuiteConfig(
+    file_tools=FileToolsConfig(
+        max_lines=500,
+        max_bytes=50 * 1024,  # 50KB
+        allow_write_outside_work_dir=False,
+    ),
+    shell_tools=ShellToolsConfig(
+        timeout=60,
+        blocked_commands=["rm -rf", "sudo"],
+    ),
+)
+```
+
+### Dynamic Configuration
+
+```python
+# Create toolset
+config = ToolSuiteConfig()
+toolset = ConfigurableToolset(config)
+
+# Disable tools and reload
+config.file_tools.disable_tool("WriteFile")
+config.shell_tools.enabled = False
+toolset.reload()
+```
+
+## Available Tools
+
+### File Tools
+
+| Tool | Description | Config Options |
+|------|-------------|----------------|
+| `ReadFile` | Read text files with line numbers | `max_lines`, `max_bytes` |
+| `WriteFile` | Write or append to files | `allow_write_outside_work_dir` |
+| `StrReplaceFile` | Edit files using string replacement | `allow_write_outside_work_dir` |
+| `Glob` | Search files using glob patterns | `max_glob_matches` |
+| `Grep` | Search file contents with regex | - |
+| `ReadMediaFile` | Read images and videos | `max_size_mb` |
+
+### Shell Tools
+
+| Tool | Description | Config Options |
+|------|-------------|----------------|
+| `Shell` | Execute shell commands | `timeout`, `blocked_commands` |
+
+### Web Tools
+
+| Tool | Description | Config Options |
+|------|-------------|----------------|
+| `FetchURL` | Fetch web page content | `timeout`, `user_agent` |
+| `SearchWeb` | Search the web | `timeout` |
+
+### Multi-Agent Tools
+
+| Tool | Description | Config Options |
+|------|-------------|----------------|
+| `Task` | Delegate tasks to subagents | `max_steps` |
+| `CreateSubagent` | Create custom subagents | - |
+
+### Utility Tools
+
+| Tool | Description |
+|------|-------------|
+| `SetTodoList` | Manage todo lists |
+| `Think` | Record thinking steps |
+
+## Safety Features
+
+### Path Security
+
+- Files outside the working directory require absolute paths
+- Optional restriction on writing outside working directory
+- Path traversal protection
+
+### Shell Security
+
+- Configurable command timeout
+- Blocked command list
+- No shell injection (uses `execve` style execution)
+
+### Resource Limits
+
+- File size limits
+- Line count limits
+- Glob match limits
+- HTTP content size limits
+
+## Examples
+
+### Safe Configuration for Untrusted Agents
+
+```python
+from agentlite.tools import ToolSuiteConfig, FileToolsConfig, ShellToolsConfig
+
+# Safe config - read-only file access, no shell
+safe_config = ToolSuiteConfig(
+    file_tools=FileToolsConfig(
+        allow_write_outside_work_dir=False,
+    ),
+    shell_tools=ShellToolsConfig(enabled=False),
+)
+
+toolset = ConfigurableToolset(safe_config)
+```
+
+### Using Individual Tools
+
+```python
+from agentlite.tools.file import ReadFile, Glob
+from pathlib import Path
+
+# Create tools directly
+read_tool = ReadFile(work_dir=Path("."))
+glob_tool = Glob(work_dir=Path("."))
+
+# Use tools
+result = await read_tool.read({"path": "README.md"})
+if not result.is_error:
+    print(result.output)
+
+result = await glob_tool.glob({"pattern": "*.py"})
+if not result.is_error:
+    print(result.output)
+```
+
+### Configuration from File
+
+```python
+import json
+from agentlite.tools import ToolSuiteConfig
+
+# Load config from file
+with open("tool_config.json") as f:
+    config_dict = json.load(f)
+
+config = ToolSuiteConfig.model_validate(config_dict)
+toolset = ConfigurableToolset(config)
+```
+
+## API Reference
+
+### Config Classes
+
+#### `ToolSuiteConfig`
+
+Main configuration class for all tools.
+
+```python
+class ToolSuiteConfig(BaseModel):
+    file_tools: FileToolsConfig
+    shell_tools: ShellToolsConfig
+    web_tools: WebToolsConfig
+    multiagent_tools: MultiAgentToolsConfig
+    misc_tools: ToolGroupConfig
+```
+
+#### `FileToolsConfig`
+
+```python
+class FileToolsConfig(ToolGroupConfig):
+    max_lines: int = 1000
+    max_line_length: int = 2000
+    max_bytes: int = 100 * 1024
+    allow_write_outside_work_dir: bool = False
+    max_glob_matches: int = 1000
+```
+
+#### `ShellToolsConfig`
+
+```python
+class ShellToolsConfig(ToolGroupConfig):
+    timeout: int = 60
+    max_timeout: int = 300
+    blocked_commands: list[str] = []
+```
+
+#### `WebToolsConfig`
+
+```python
+class WebToolsConfig(ToolGroupConfig):
+    timeout: int = 30
+    user_agent: str = "Mozilla/5.0 ..."
+    max_content_length: int = 1024 * 1024
+```
+
+### ConfigurableToolset
+
+```python
+class ConfigurableToolset(SimpleToolset):
+    def __init__(
+        self,
+        config: ToolSuiteConfig | None = None,
+        work_dir: str | None = None,
+    )
+    
+    def reload(self, config: ToolSuiteConfig | None = None) -> None
+```
+
+## License
+
+MIT License - same as AgentLite.