170 lines
5.4 KiB
Markdown
170 lines
5.4 KiB
Markdown
# Package: dirigent_tools
|
|
|
|
Tool implementations for ACP client operations with sandboxing and security.
|
|
|
|
## Quick Facts
|
|
- **Type**: Library
|
|
- **Main Entry**: src/lib.rs
|
|
- **Dependencies**: tokio, serde, anyhow, thiserror, tracing, regex, globset, similar, dunce
|
|
- **Status**: Scaffolding phase - structure complete, implementation pending
|
|
|
|
## Purpose
|
|
|
|
This package provides the foundational tool operations for the Dirigent ACP client, implementing file operations, terminal execution, and search capabilities with strong security guarantees. It is designed to support ACP-compliant agents by providing safe, sandboxed tool handlers.
|
|
|
|
## Module Structure
|
|
|
|
### Core Modules
|
|
- **error** (`src/error.rs`) - Error types for tool operations
|
|
- **config** (`src/config.rs`) - Configuration types (sandbox, permissions, terminal, search, embedding)
|
|
- **path** (`src/path.rs`) - Cross-platform path normalization and containment checking
|
|
|
|
### Tool Modules
|
|
- **fs** (`src/fs.rs`) - File read/write/edit operations
|
|
- **search** (`src/search.rs`) - Glob/grep/ls search operations
|
|
- **terminal** (`src/terminal.rs`) - Command execution and output capture
|
|
|
|
### Security Modules
|
|
- **permission** (`src/permission.rs`) - Permission prompt system and decision caching
|
|
- **audit** (`src/audit.rs`) - Structured audit logging
|
|
|
|
### Integration Modules
|
|
- **tool_call** (`src/tool_call.rs`) - ACP tool call metadata and helpers
|
|
|
|
## Security Model
|
|
|
|
All operations are subject to:
|
|
|
|
1. **Sandbox Containment**: Operations restricted to configured allowed roots
|
|
2. **Blocklist Enforcement**: Sensitive paths explicitly denied
|
|
3. **Permission Prompts**: Write/execute operations require user approval (configurable)
|
|
4. **Resource Limits**: Bounded file sizes, search results, terminal output
|
|
5. **Audit Logging**: All operations logged with structured context
|
|
|
|
## Platform Support
|
|
|
|
Windows is a first-class platform with explicit support for:
|
|
- Backslash and forward slash separators
|
|
- Drive letters (C:\, D:\)
|
|
- UNC paths (\\server\share\...)
|
|
- Long path prefixes (\\?\...)
|
|
- MINGW-style paths (/c/Users/...)
|
|
- Junctions and symlinks
|
|
- cmd.exe and PowerShell
|
|
|
|
All path normalization and containment logic handles these cases.
|
|
|
|
## Configuration (Future)
|
|
|
|
Configuration types will be implemented in SCAFF-05:
|
|
|
|
```rust
|
|
pub struct SandboxConfig {
|
|
pub allowed_roots: Vec<PathBuf>,
|
|
pub blocked_paths: Vec<String>, // glob patterns
|
|
pub allow_symlink_escape: bool,
|
|
pub follow_symlinks_within_roots: bool,
|
|
pub read_enabled: bool,
|
|
pub write_enabled: bool,
|
|
pub max_read_bytes: u64,
|
|
pub max_write_bytes: u64,
|
|
// ... more fields
|
|
}
|
|
|
|
pub struct PermissionConfig {
|
|
pub mode: PermissionMode, // Ask | Whitelist | Yolo
|
|
pub remember_decisions: bool,
|
|
pub remember_ttl_secs: u64,
|
|
pub scope: DecisionScope, // PerConnector | PerSession
|
|
pub whitelist: WhitelistConfig,
|
|
}
|
|
|
|
pub struct TerminalConfig {
|
|
pub enabled: bool,
|
|
pub default_cwd: PathBuf,
|
|
pub env_allowlist: Vec<String>,
|
|
pub command_blocklist: Vec<String>,
|
|
pub output_byte_limit: u64,
|
|
pub max_runtime_secs: u64,
|
|
}
|
|
|
|
pub struct SearchConfig {
|
|
pub max_results: u32,
|
|
pub max_bytes: u64,
|
|
pub default_include_globs: Vec<String>,
|
|
pub default_exclude_globs: Vec<String>,
|
|
}
|
|
|
|
pub struct EmbeddingConfig {
|
|
pub max_embed_bytes: u64,
|
|
pub allow_resource_link: bool,
|
|
pub redact_patterns: Vec<String>, // regex patterns
|
|
}
|
|
```
|
|
|
|
## Implementation Status
|
|
|
|
**Current Phase**: SCAFF-01 (Scaffolding) - Complete
|
|
|
|
All modules are stubs with `unimplemented!()`. Implementation will proceed in phases:
|
|
|
|
### Phase 1: Path and Sandbox (Protocol tasks)
|
|
- Path normalization (Windows, Linux, macOS)
|
|
- Canonical path resolution (symlinks, junctions)
|
|
- Containment checking
|
|
- Blocklist matching
|
|
|
|
### Phase 2: Tool Operations (Tool tasks)
|
|
- File read with line ranges
|
|
- File write with atomic operations
|
|
- File edit with diff generation
|
|
- Glob search
|
|
- Grep search with context
|
|
- LS directory listing
|
|
- Terminal creation and lifecycle
|
|
- Terminal output capture with ring buffer
|
|
|
|
### Phase 3: Security and Integration (Integration tasks)
|
|
- Permission prompt flow
|
|
- Decision caching with TTL
|
|
- Audit logging with structured fields
|
|
- ACP tool call event generation
|
|
- Tool title formatting
|
|
|
|
## Integration Points
|
|
|
|
### dirigent_core
|
|
- Uses `dirigent_tools` for ACP client request handlers
|
|
- Passes configuration from connector params
|
|
- Routes tool operations through sandbox
|
|
|
|
### api
|
|
- May use `dirigent_tools` for server function implementations
|
|
- Exposes configuration endpoints
|
|
- Handles permission prompts via UI
|
|
|
|
### web
|
|
- Displays tool calls with titles, locations, diffs
|
|
- Renders permission prompts
|
|
- Shows audit logs
|
|
|
|
## Testing Strategy
|
|
|
|
Test infrastructure will be set up in SCAFF-03:
|
|
- Unit tests for each module
|
|
- Integration tests with mocker
|
|
- Cross-platform tests (Windows, Linux, macOS)
|
|
- Golden transcript fixtures
|
|
- Test utilities for temp directories, file comparison, sandboxed environments
|
|
|
|
## Related Packages
|
|
- **dirigent_core** - Uses this package for tool operations
|
|
- **api** - May use this package for server functions
|
|
- **dirigent_protocol** - Shared event types for tool calls
|
|
|
|
## References
|
|
- Task file: `docs/building/04_acp_client/04_tasks_00_scaffolding_and_finishing.md`
|
|
- Tools research: `docs/building/04_acp_client/03_tools_research.md`
|
|
- Sandbox spec: `docs/building/04_acp_client/03_fs_sandboxing_and_permissions_spec.md`
|
|
- Roadmap: `docs/building/04_acp_client/roadmap.md`
|