feat(resource): add handler runtime for git-checkout and fs-directory #154

Closed
opened 2026-02-22 23:39:40 +00:00 by freemo · 2 comments
Owner

Metadata

  • Commit Message: feat(resource): add handler runtime for git-checkout and fs-directory
  • Branch: feature/m1-resource-handlers

Definition of Done

A ResourceHandler protocol and registry are implemented, supporting handler lookup by ResourceType with normalized error types for missing/invalid handlers. GitCheckoutHandler validates repo path and branch, builds a worktree path under sandbox root, and returns metadata. FsDirectoryHandler validates path existence, normalizes absolute paths, and creates copy-on-write sandbox targets.

This issue is complete when:

  • All subtasks below 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 body should be appropriate in size for a commit message and relatively
    complete in describing what was done.
  • 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.

Subtasks

  • Add ResourceHandler protocol + registry, including handler lookup by ResourceType and normalized error types for missing/invalid handlers.
  • Implement GitCheckoutHandler to validate repo path/branch, build a worktree path under the sandbox root, and return read-only vs writeable metadata.
  • Implement FsDirectoryHandler to validate path existence, normalize absolute paths, and create copy-on-write sandbox targets.
  • Integrate sandbox manager so PlanExecutionContext always yields a per-plan sandbox root and handler outputs are persisted on the plan for apply/rollback.
  • Add resource binding resolver (contextual/static/parameter) that injects resource_root, read_only, and sandbox_root into tool inputs consistently.
  • Add handler metadata exposure in resource inspect output (handler name, sandbox root, read-only flag).
  • Update docs/reference/resource_handlers.md with handler behavior and sandbox outputs.
  • Tests (Behave): Add scenarios for handler resolution, sandbox root creation, read-only enforcement, and binding precedence.
  • Tests (Robot): Add Robot test covering resource inspect handler output and plan execute using sandboxed paths.
  • Tests (ASV): Add benchmarks/resource_handler_bench.py for handler resolution overhead.
  • Verify coverage >=97% via nox -s coverage_report. If coverage is <97% then review the current unit test coverage report at build/coverage.xml and use it to write new Behave based unit tests to improve code coverage. Specifically, write Behave style unit tests that are descriptively named and specifically improves coverage on whichever file has the most uncovered lines by writing tests that will target the uncovered lines in the report. Once that is done rerun nox -s coverage_report to verify all tests pass and coverage is above >=97%. Only mark this as complete once coverage is >=97%, if not repeat this task as many times as is needed until coverage reaches >=97%.
  • Run nox (all default sessions, including benchmark), fix any errors if needed ensuring nox passes across entire code base, do not ignore any failure even if it seems unrelated to this commit, fix it.

Section: #### M1: Minimal Local Source-Code Workflow (Target: Day 7, recovery path)
Status: Completed

## Metadata - **Commit Message**: `feat(resource): add handler runtime for git-checkout and fs-directory` - **Branch**: `feature/m1-resource-handlers` ## Definition of Done A `ResourceHandler` protocol and registry are implemented, supporting handler lookup by ResourceType with normalized error types for missing/invalid handlers. `GitCheckoutHandler` validates repo path and branch, builds a worktree path under sandbox root, and returns metadata. `FsDirectoryHandler` validates path existence, normalizes absolute paths, and creates copy-on-write sandbox targets. This issue is complete when: - All subtasks below 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 body should be appropriate in size for a commit message and relatively complete in describing what was done. - 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. ## Subtasks - [x] Add `ResourceHandler` protocol + registry, including handler lookup by ResourceType and normalized error types for missing/invalid handlers. - [x] Implement `GitCheckoutHandler` to validate repo path/branch, build a worktree path under the sandbox root, and return read-only vs writeable metadata. - [x] Implement `FsDirectoryHandler` to validate path existence, normalize absolute paths, and create copy-on-write sandbox targets. - [x] Integrate sandbox manager so `PlanExecutionContext` always yields a per-plan sandbox root and handler outputs are persisted on the plan for apply/rollback. - [x] Add resource binding resolver (contextual/static/parameter) that injects `resource_root`, `read_only`, and `sandbox_root` into tool inputs consistently. - [x] Add handler metadata exposure in `resource inspect` output (handler name, sandbox root, read-only flag). - [x] Update `docs/reference/resource_handlers.md` with handler behavior and sandbox outputs. - [x] Tests (Behave): Add scenarios for handler resolution, sandbox root creation, read-only enforcement, and binding precedence. - [x] Tests (Robot): Add Robot test covering `resource inspect` handler output and plan execute using sandboxed paths. - [x] Tests (ASV): Add `benchmarks/resource_handler_bench.py` for handler resolution overhead. - [x] Verify coverage >=97% via `nox -s coverage_report`. If coverage is <97% then review the current unit test coverage report at `build/coverage.xml` and use it to write new Behave based unit tests to improve code coverage. Specifically, write Behave style unit tests that are descriptively named and specifically improves coverage on whichever file has the most uncovered lines by writing tests that will target the uncovered lines in the report. Once that is done rerun `nox -s coverage_report` to verify all tests pass and coverage is above >=97%. Only mark this as complete once coverage is >=97%, if not repeat this task as many times as is needed until coverage reaches >=97%. - [x] Run `nox` (all default sessions, including benchmark), fix any errors if needed ensuring nox passes across **entire** code base, do not ignore any failure even if it seems unrelated to this commit, fix it. **Section**: #### M1: Minimal Local Source-Code Workflow (Target: Day 7, recovery path) **Status**: Completed
freemo added this to the v3.0.0 milestone 2026-02-22 23:39:40 +00:00
Author
Owner

Expected completion updated (Day 15 rebaseline): Day 17 / 2026-02-25 (previously Day 16 / 2026-02-24)

**Expected completion updated (Day 15 rebaseline):** Day 17 / 2026-02-25 (previously Day 16 / 2026-02-24)
freemo added the due date 2026-02-22 2026-02-23 18:41:07 +00:00
Author
Owner

All subtasks completed and merged to master via PR #385 (develop-hamza-2). All implementation plan tasks for commit group M1.resource-handlers verified as complete — including code, docs, Behave/Robot/ASV tests, coverage >=97%, and full nox pass.

All subtasks completed and merged to `master` via PR #385 (`develop-hamza-2`). All implementation plan tasks for commit group **M1.resource-handlers** verified as complete — including code, docs, Behave/Robot/ASV tests, coverage >=97%, and full nox pass.
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

2026-02-22

Blocks
Reference
cleveragents/cleveragents-core#154
No description provided.