sync from monorepo @ 2452e92e
This commit is contained in:
@@ -0,0 +1,238 @@
|
||||
# dirigent_tools Implementation Status
|
||||
|
||||
This document tracks the implementation status of the tools package, showing which features are complete and which are stubbed pending implementation.
|
||||
|
||||
## Status Legend
|
||||
|
||||
- ✅ **Completed** - Fully implemented with tests
|
||||
- ⏸️ **Stubbed** - Function signatures present, returns `unimplemented!()`
|
||||
- 🚧 **In Progress** - Actively being implemented
|
||||
|
||||
---
|
||||
|
||||
## Completed Features
|
||||
|
||||
### Core Infrastructure
|
||||
|
||||
- ✅ **Error Types** (`src/error.rs`) - Complete error handling with user-facing messages
|
||||
- ✅ **Configuration Types** (`src/config.rs`) - All config structures with validation
|
||||
- ✅ **Path Validation** (`src/path/validate.rs`) - Path normalization and validation
|
||||
- ✅ **Path Canonicalization** (`src/path/canonicalize.rs`) - Cross-platform canonical paths
|
||||
- ✅ **Path Containment** (`src/path/containment.rs`) - Sandbox boundary checking
|
||||
- ✅ **Path Blocklist** (`src/path/blocklist.rs`) - Glob-based path blocking
|
||||
|
||||
---
|
||||
|
||||
## Stubbed Features (TODO)
|
||||
|
||||
### File Operations
|
||||
|
||||
- ⏸️ **Read Text File** (`src/fs/read.rs`) - TOOLS-FS-01
|
||||
- Function: `read_text_file()`
|
||||
- Types: `ReadTextFileRequest`, `ReadTextFileResponse`
|
||||
- Features: Line/limit support, UTF-8 validation, sandboxing
|
||||
|
||||
- ⏸️ **Write Text File** (`src/fs/write.rs`) - TOOLS-FS-02
|
||||
- Function: `write_text_file()`, `normalize_eol()`
|
||||
- Types: `WriteTextFileRequest`, `WriteTextFileResponse`
|
||||
- Features: Atomic writes, EOL normalization, permission checks
|
||||
|
||||
- ⏸️ **Generate Diff** (`src/fs/diff.rs`) - TOOLS-FS-03
|
||||
- Function: `generate_diff()`
|
||||
- Features: Unified diff generation, edge case handling
|
||||
|
||||
- ⏸️ **Edit File** (`src/fs/edit.rs`) - TOOLS-FS-04
|
||||
- Function: `edit_file()`
|
||||
- Types: `EditFileRequest`, `EditFileResponse`, `EditOperation`
|
||||
- Features: Read + transform + write, automatic diff generation
|
||||
|
||||
### Search Operations
|
||||
|
||||
- ⏸️ **Directory Listing** (`src/search/ls.rs`) - TOOLS-SEARCH-01
|
||||
- Function: `ls()`
|
||||
- Types: `LsRequest`, `LsResponse`, `LsEntry`, `FileKind`
|
||||
- Features: Sandboxing, exclude globs, file metadata
|
||||
|
||||
- ⏸️ **Glob Search** (`src/search/glob.rs`) - TOOLS-SEARCH-02
|
||||
- Function: `glob_search()`
|
||||
- Types: `GlobRequest`, `GlobResponse`
|
||||
- Features: Pattern matching, result limits, exclude patterns
|
||||
|
||||
- ⏸️ **Content Search** (`src/search/grep.rs`) - TOOLS-SEARCH-03
|
||||
- Function: `grep_search()`
|
||||
- Types: `GrepRequest`, `GrepResponse`, `GrepMatch`
|
||||
- Features: Regex search, context lines, binary file detection
|
||||
|
||||
### Terminal Operations
|
||||
|
||||
- ⏸️ **Create Terminal** (`src/terminal/create.rs`) - TOOLS-TERM-01
|
||||
- Function: `create_terminal()`
|
||||
- Types: `CreateTerminalRequest`, `CreateTerminalResponse`, `EnvVar`
|
||||
- Features: Process spawning, CWD validation, env filtering, output capture
|
||||
|
||||
- ⏸️ **Get Terminal Output** (`src/terminal/output.rs`) - TOOLS-TERM-02
|
||||
- Function: `get_terminal_output()`
|
||||
- Types: `TerminalOutputRequest`, `TerminalOutputResponse`
|
||||
- Features: Ring buffer snapshot, truncation tracking, exit status
|
||||
|
||||
- ⏸️ **Wait for Exit** (`src/terminal/wait.rs`) - TOOLS-TERM-03
|
||||
- Function: `wait_for_terminal_exit()`
|
||||
- Types: `WaitForTerminalExitRequest`, `WaitForTerminalExitResponse`
|
||||
- Features: Blocking wait, timeout enforcement
|
||||
|
||||
- ⏸️ **Kill Terminal** (`src/terminal/kill.rs`) - TOOLS-TERM-04
|
||||
- Function: `kill_terminal()`
|
||||
- Types: `KillTerminalCommandRequest`, `KillTerminalCommandResponse`
|
||||
- Features: Forceful termination, idempotent operations
|
||||
|
||||
- ⏸️ **Release Terminal** (`src/terminal/release.rs`) - TOOLS-TERM-05
|
||||
- Function: `release_terminal()`
|
||||
- Types: `ReleaseTerminalRequest`, `ReleaseTerminalResponse`
|
||||
- Features: Resource cleanup, registry removal
|
||||
|
||||
- ⏸️ **Ring Buffer** (`src/terminal/ring_buffer.rs`) - TOOLS-TERM-01
|
||||
- Type: `RingBuffer`
|
||||
- Features: Fixed-size circular buffer, UTF-8 boundary handling
|
||||
|
||||
### Security and Permissions
|
||||
|
||||
- ⏸️ **Permission System** (`src/permission.rs`) - TOOLS-PERM-01 through TOOLS-PERM-05
|
||||
- Functions: Permission checks, decision caching, whitelist matching
|
||||
- Features: Ask/whitelist/yolo modes, per-connector/session scope
|
||||
|
||||
### Observability
|
||||
|
||||
- ⏸️ **Audit Logging** (`src/audit.rs`) - TOOLS-AUDIT-01 through TOOLS-AUDIT-03
|
||||
- Functions: Structured audit logging, metrics
|
||||
- Features: Operation tracking, performance monitoring
|
||||
|
||||
### UI Integration
|
||||
|
||||
- ⏸️ **Tool Call Rendering** (`src/tool_call.rs`) - TOOLS-UI-01 through TOOLS-UI-03
|
||||
- Functions: ToolKind mapping, title generation, diff formatting
|
||||
- Features: ACP integration, location extraction
|
||||
|
||||
---
|
||||
|
||||
## When Implementing a Stubbed Feature
|
||||
|
||||
Follow these steps to properly implement a feature:
|
||||
|
||||
1. **Implement the Function**
|
||||
- Replace `unimplemented!()` with actual logic
|
||||
- Follow the task specification in `docs/building/04_acp_client/04_tasks_02_tools_and_sandboxing.md`
|
||||
- Reference the security spec in `docs/building/04_acp_client/03_fs_sandboxing_and_permissions_spec.md`
|
||||
|
||||
2. **Add Comprehensive Tests**
|
||||
- Unit tests for happy paths
|
||||
- Edge case testing
|
||||
- Error case validation
|
||||
- Cross-platform tests (Windows, Linux, macOS)
|
||||
|
||||
3. **Enable Capability** (if applicable)
|
||||
- Update `ClientCapabilities::default()` in `packages/dirigent_core/src/acp/connector_state.rs`
|
||||
- Change from `None` to `Some(...)` for the relevant capability
|
||||
- Document why the capability is now safe to advertise
|
||||
|
||||
4. **Update This Document**
|
||||
- Move feature from "Stubbed" to "Completed"
|
||||
- Add any notes or caveats
|
||||
- Update completion percentage
|
||||
|
||||
5. **Integration Testing**
|
||||
- Test with dirigent-acp-mocker
|
||||
- Verify tool calls work end-to-end
|
||||
- Test UI rendering if applicable
|
||||
|
||||
---
|
||||
|
||||
## Capability Enablement
|
||||
|
||||
**CRITICAL**: Do NOT enable capabilities in `ClientCapabilities::default()` until the corresponding tools are fully implemented and tested.
|
||||
|
||||
### Current Capability Defaults (dirigent_core)
|
||||
|
||||
```rust
|
||||
impl Default for ClientCapabilities {
|
||||
fn default() -> Self {
|
||||
Self {
|
||||
fs: None, // ❌ Disabled - file operations not yet implemented
|
||||
terminal: None, // ❌ Disabled - terminal operations not yet implemented
|
||||
_meta: None,
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### When to Enable
|
||||
|
||||
**File System (`fs`)**:
|
||||
- ✅ TOOLS-FS-01 (read) is implemented and tested
|
||||
- ✅ TOOLS-FS-02 (write) is implemented and tested (or omit `write_text_file: Some(true)`)
|
||||
- ✅ Path validation and sandboxing are complete
|
||||
- ✅ Permission system is integrated
|
||||
|
||||
**Terminal (`terminal`)**:
|
||||
- ✅ TOOLS-TERM-01 through TOOLS-TERM-05 are implemented
|
||||
- ✅ Ring buffer is working correctly
|
||||
- ✅ Permission checks are in place
|
||||
- ✅ Cross-platform spawn/kill is tested
|
||||
|
||||
---
|
||||
|
||||
## Progress Summary
|
||||
|
||||
- **Total Features**: 25
|
||||
- **Completed**: 6 (24%)
|
||||
- **Stubbed**: 19 (76%)
|
||||
- **In Progress**: 0
|
||||
|
||||
---
|
||||
|
||||
## Task References
|
||||
|
||||
All task specifications are in:
|
||||
- `docs/building/04_acp_client/04_tasks_02_tools_and_sandboxing.md`
|
||||
|
||||
Task ID format: `TOOLS-{AREA}-{NUMBER}`
|
||||
- `TOOLS-SCAFFOLD-XX` - Package structure
|
||||
- `TOOLS-PATH-XX` - Path operations
|
||||
- `TOOLS-FS-XX` - File operations
|
||||
- `TOOLS-SEARCH-XX` - Search operations
|
||||
- `TOOLS-TERM-XX` - Terminal operations
|
||||
- `TOOLS-PERM-XX` - Permission system
|
||||
- `TOOLS-AUDIT-XX` - Audit and observability
|
||||
- `TOOLS-UI-XX` - UI integration
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
To continue implementation:
|
||||
|
||||
1. **Protocol Integration** (prerequisite)
|
||||
- Ensure ACP protocol handlers can call tool functions
|
||||
- Wire up request/response types
|
||||
- Handle tool call lifecycle (pending → in_progress → completed/failed)
|
||||
|
||||
2. **File Operations** (high priority for UI features)
|
||||
- TOOLS-FS-01: Read text file
|
||||
- TOOLS-FS-02: Write text file
|
||||
- TOOLS-FS-03: Generate diffs
|
||||
|
||||
3. **Search Operations** (useful for development)
|
||||
- TOOLS-SEARCH-01: Directory listing
|
||||
- TOOLS-SEARCH-02: Glob search
|
||||
|
||||
4. **Permission System** (security-critical)
|
||||
- TOOLS-PERM-01: Permission checks
|
||||
- TOOLS-PERM-02: Decision caching
|
||||
|
||||
5. **Terminal Operations** (complex, later priority)
|
||||
- TOOLS-TERM-01: Create terminal
|
||||
- TOOLS-TERM-02: Get output
|
||||
|
||||
---
|
||||
|
||||
*Last Updated: 2025-11-12*
|
||||
*Status: All core infrastructure complete, tool operations stubbed and ready for implementation*
|
||||
Reference in New Issue
Block a user