feat(tool): add move_file, create_directory, and get_file_info built-in tools #883

Open
opened 2026-03-13 22:59:46 +00:00 by freemo · 2 comments
Owner

Metadata

  • Commit Message: feat(tool): add move_file, create_directory, and get_file_info built-in tools
  • Branch: feature/m4-missing-builtin-tools

Background and Context

The specification defines 9 built-in resource tools: read_file, write_file, edit_file, delete_file, move_file, create_directory, list_files, search_files, and get_file_info. Issue #276 implemented 6 of these (builtin/file-read, file-write, file-edit, file-delete, file-list, file-search). Three tools remain unimplemented: move_file, create_directory, and get_file_info.

These are core tools that actors use to modify resources during plan execution. Without move_file, actors cannot rename or relocate files. Without create_directory, actors rely on file-write's create_dirs side effect. Without get_file_info, actors cannot inspect file metadata.

Expected Behavior

  • builtin/file-move: Move or rename a file within a resource. Parameters: source_path, destination_path. Returns: confirmation with old and new paths.
  • builtin/dir-create: Create a directory (with parents). Parameters: path, parents (bool). Returns: confirmation with created path.
  • builtin/file-info: Get file metadata. Parameters: path. Returns: size, permissions, timestamps (created, modified, accessed), file type, encoding.

Acceptance Criteria

  • builtin/file-move moves/renames files within sandbox boundaries
  • builtin/dir-create creates directories with optional parent creation
  • builtin/file-info returns comprehensive file metadata
  • All tools are registered in ALL_FILE_TOOLS in tool/builtins/file_tools.py
  • All tools respect sandbox boundaries (path traversal protection)
  • All tools have proper JSON Schema input/output definitions
  • All tools have capability metadata (writes, checkpointable, etc.)

Subtasks

  • Implement MoveFileTool in tool/builtins/file_tools.py
  • Implement CreateDirectoryTool in tool/builtins/file_tools.py
  • Implement GetFileInfoTool in tool/builtins/file_tools.py
  • Add all three to ALL_FILE_TOOLS and register_file_tools()
  • Tests (Behave): Add scenarios for each tool (success, error, edge cases)
  • Verify coverage >= 97% via nox -s coverage_report
  • Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

  • All subtasks above are completed and checked off.
  • A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation.
  • The commit is pushed to the remote on the branch matching the Branch in Metadata exactly.
  • The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.
## Metadata - **Commit Message**: `feat(tool): add move_file, create_directory, and get_file_info built-in tools` - **Branch**: `feature/m4-missing-builtin-tools` ## Background and Context The specification defines 9 built-in resource tools: `read_file`, `write_file`, `edit_file`, `delete_file`, `move_file`, `create_directory`, `list_files`, `search_files`, and `get_file_info`. Issue #276 implemented 6 of these (`builtin/file-read`, `file-write`, `file-edit`, `file-delete`, `file-list`, `file-search`). Three tools remain unimplemented: `move_file`, `create_directory`, and `get_file_info`. These are core tools that actors use to modify resources during plan execution. Without `move_file`, actors cannot rename or relocate files. Without `create_directory`, actors rely on `file-write`'s `create_dirs` side effect. Without `get_file_info`, actors cannot inspect file metadata. ## Expected Behavior - `builtin/file-move`: Move or rename a file within a resource. Parameters: `source_path`, `destination_path`. Returns: confirmation with old and new paths. - `builtin/dir-create`: Create a directory (with parents). Parameters: `path`, `parents` (bool). Returns: confirmation with created path. - `builtin/file-info`: Get file metadata. Parameters: `path`. Returns: size, permissions, timestamps (created, modified, accessed), file type, encoding. ## Acceptance Criteria - [x] `builtin/file-move` moves/renames files within sandbox boundaries - [x] `builtin/dir-create` creates directories with optional parent creation - [x] `builtin/file-info` returns comprehensive file metadata - [x] All tools are registered in `ALL_FILE_TOOLS` in `tool/builtins/file_tools.py` - [x] All tools respect sandbox boundaries (path traversal protection) - [x] All tools have proper JSON Schema input/output definitions - [x] All tools have capability metadata (`writes`, `checkpointable`, etc.) ## Subtasks - [x] Implement `MoveFileTool` in `tool/builtins/file_tools.py` - [x] Implement `CreateDirectoryTool` in `tool/builtins/file_tools.py` - [x] Implement `GetFileInfoTool` in `tool/builtins/file_tools.py` - [x] Add all three to `ALL_FILE_TOOLS` and `register_file_tools()` - [x] Tests (Behave): Add scenarios for each tool (success, error, edge cases) - [x] Verify coverage >= 97% via `nox -s coverage_report` - [x] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done.
freemo added this to the v3.4.0 milestone 2026-03-13 23:00:14 +00:00
Member

Implementation Notes

Design Decisions

  1. Naming convention: Used builtin/file-move, builtin/dir-create, and builtin/file-info — following the existing naming pattern where file operations use file-* prefix and directory operations use dir-* prefix.
  2. shutil.move vs Path.rename: Used shutil.move() for file-move because it handles cross-filesystem moves, which Path.rename() does not.
  3. Timestamps: File info returns ISO 8601 formatted timestamps using datetime.fromtimestamp(ts, tz=UTC) — consistent with the specification's preference for ISO dates and avoiding timezone-naive datetime warnings.
  4. Parent directory creation: file-move creates parent directories of the destination if they don't exist, matching the behavior of file-write's create_dirs parameter.

Key Code Locations (commit e65c3866)

  • Handlers: cleveragents.tool.builtins.file_tools._handle_file_move, _handle_dir_create, _handle_file_info
  • Specs: cleveragents.tool.builtins.file_tools.FILE_MOVE_SPEC, DIR_CREATE_SPEC, FILE_INFO_SPEC
  • ALL_FILE_TOOLS updated from 6 to 9 entries
  • Registration: cleveragents.tool.builtins.register_file_tools() docstring updated to "9 built-in file tools"

Test Coverage

  • Behave: 7 scenarios in features/builtin_file_tools_new.feature — move success, move path traversal, dir create with/without parents, file info for file/dir, file info nonexistent
  • Robot: 4 integration tests in robot/builtin_file_tools_new.robot
  • ASV: 3 benchmark suites in benchmarks/bench_builtin_file_tools_new.py

Quality Gates

Session Result
lint PASS
typecheck PASS (0 errors)
unit_tests PASS (11,462 scenarios)
integration_tests PASS (1 pre-existing failure unrelated)
coverage_report PASS (97%)

PR

PR #1070Closes #883

## Implementation Notes ### Design Decisions 1. **Naming convention**: Used `builtin/file-move`, `builtin/dir-create`, and `builtin/file-info` — following the existing naming pattern where file operations use `file-*` prefix and directory operations use `dir-*` prefix. 2. **`shutil.move` vs `Path.rename`**: Used `shutil.move()` for `file-move` because it handles cross-filesystem moves, which `Path.rename()` does not. 3. **Timestamps**: File info returns ISO 8601 formatted timestamps using `datetime.fromtimestamp(ts, tz=UTC)` — consistent with the specification's preference for ISO dates and avoiding timezone-naive datetime warnings. 4. **Parent directory creation**: `file-move` creates parent directories of the destination if they don't exist, matching the behavior of `file-write`'s `create_dirs` parameter. ### Key Code Locations (commit `e65c3866`) - Handlers: `cleveragents.tool.builtins.file_tools._handle_file_move`, `_handle_dir_create`, `_handle_file_info` - Specs: `cleveragents.tool.builtins.file_tools.FILE_MOVE_SPEC`, `DIR_CREATE_SPEC`, `FILE_INFO_SPEC` - `ALL_FILE_TOOLS` updated from 6 to 9 entries - Registration: `cleveragents.tool.builtins.register_file_tools()` docstring updated to "9 built-in file tools" ### Test Coverage - **Behave**: 7 scenarios in `features/builtin_file_tools_new.feature` — move success, move path traversal, dir create with/without parents, file info for file/dir, file info nonexistent - **Robot**: 4 integration tests in `robot/builtin_file_tools_new.robot` - **ASV**: 3 benchmark suites in `benchmarks/bench_builtin_file_tools_new.py` ### Quality Gates | Session | Result | |---|---| | lint | PASS | | typecheck | PASS (0 errors) | | unit_tests | PASS (11,462 scenarios) | | integration_tests | PASS (1 pre-existing failure unrelated) | | coverage_report | PASS (97%) | ### PR PR #1070 — `Closes #883`
freemo self-assigned this 2026-04-02 06:13:54 +00:00
Author
Owner

Implementation update (ca-issue-worker):

Branch feature/m4-missing-builtin-tools has been rebased onto current master (commit 07d104f8). The merge conflict in CHANGELOG.md has been resolved.

Quality gates verified post-rebase:

  • Lint: PASSED (ruff check — 0 errors)
  • Typecheck: PASSED (pyright strict — 0 errors, 0 warnings)
  • Functional tests: All 3 tools verified working (file-move, dir-create, file-info)

PR #1070 is now mergeable. All review findings from the initial code review (H1–H4, M1–M7, L1–L10) were addressed in the commit. PR review and merge handled by continuous review stream.

**Implementation update (ca-issue-worker):** Branch `feature/m4-missing-builtin-tools` has been rebased onto current `master` (commit `07d104f8`). The merge conflict in `CHANGELOG.md` has been resolved. **Quality gates verified post-rebase:** - ✅ Lint: PASSED (ruff check — 0 errors) - ✅ Typecheck: PASSED (pyright strict — 0 errors, 0 warnings) - ✅ Functional tests: All 3 tools verified working (file-move, dir-create, file-info) **PR #1070** is now mergeable. All review findings from the initial code review (H1–H4, M1–M7, L1–L10) were addressed in the commit. PR review and merge handled by continuous review stream.
Sign in to join this conversation.
No milestone
No project
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Reference
cleveragents/cleveragents-core#883
No description provided.