dirigence/dirigent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
582954667108ac850934420ef82a6372c92b75c7
dirigent/crates/dirigent_tools/IMPLEMENTATION_STATUS.md
T
g4borg b03dc15371 sync from monorepo @ 2452e92e
2026-05-08 01:59:04 +02:00

8.0 KiB
Raw Blame History

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)

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 View Git Blame Copy Permalink