feat(resource): add resource type inheritance and polymorphic tool matching #513

Closed
opened 2026-03-02 16:22:20 +00:00 by freemo · 0 comments
Owner

Metadata

  • Commit Message: feat(resource): add resource type inheritance and polymorphic tool matching
  • Branch: feature/m6-resource-type-inheritance

Background and Context

The specification (ADR-042, §Resources > Resource Type Inheritance) defines a single-inheritance model for resource types via an inherits field in YAML configuration. Inheritance chains are limited to 5 levels. When a tool declares it accepts a parent resource type (e.g., container-instance), it must also accept any child type (e.g., devcontainer-instance). This polymorphic matching enables generic container tools to work with specialized container types.

Expected Behavior

Resource types can declare an inherits field. The ToolRegistry performs polymorphic matching — a tool requiring container-instance also matches devcontainer-instance. Inheritance chain depth is validated at registration time.

Acceptance Criteria

  • Add inherits field to resource type YAML schema and Pydantic model in src/cleveragents/resource/schema.py.
  • Implement inheritance chain resolution that walks the inherits chain up to 5 levels.
  • Add chain depth validation at resource type registration time — reject chains deeper than 5 levels with a clear error.
  • Implement polymorphic tool matching in ToolRegistry: when checking if a resource matches a tool's declared resource type, check both the exact type and all ancestor types in the inheritance chain.
  • Implement polymorphic matching in ResourceHandlerResolver: when resolving a handler, check for handlers registered on ancestor types if no direct handler exists.
  • CLI: agents resource type show <name> displays the inheritance chain.
  • CLI: agents resource type list shows the inherits field for types that have one.

Definition of Done

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 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

  • Code [Hamza]: Add inherits optional field to ResourceTypeConfig in src/cleveragents/resource/schema.py.
  • Code [Hamza]: Implement resolve_inheritance_chain(type_name: str) -> list[str] method in ResourceTypeRegistry that returns the full chain from child to root.
  • Code [Hamza]: Add chain depth validation (max 5) at registration time with ResourceTypeInheritanceDepthError.
  • Code [Hamza]: Implement polymorphic matching in ToolRegistry.find_tools_for_resource() — check resource type AND all ancestor types.
  • Code [Hamza]: Implement polymorphic handler resolution in ResourceHandlerResolver — fall back to ancestor type handlers.
  • Code [Hamza]: Update agents resource type show CLI output to display inheritance chain.
  • Code [Hamza]: Update agents resource type list CLI output to show inherits field.
  • Docs [Hamza]: Add docs/reference/resource_type_inheritance.md documenting the inheritance model, chain depth limits, and polymorphic matching behavior.
  • Tests (Behave) [Hamza]: Add features/resource_type_inheritance.feature covering: single-level inheritance, multi-level chain, max depth validation, polymorphic tool matching, polymorphic handler resolution, CLI display.
  • Tests (Robot) [Hamza]: Add robot/resource_type_inheritance.robot integration tests for inheritance chain resolution and CLI output.
  • Tests (ASV) [Hamza]: Add benchmarks/resource_type_inheritance_bench.py for chain resolution and polymorphic matching throughput.
  • Quality [Hamza]: 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 improve 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%.
  • Quality [Hamza]: 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.

Parent: #397 (Epic: Server & Autonomy Infrastructure)

## Metadata - **Commit Message**: `feat(resource): add resource type inheritance and polymorphic tool matching` - **Branch**: `feature/m6-resource-type-inheritance` ## Background and Context The specification (ADR-042, §Resources > Resource Type Inheritance) defines a single-inheritance model for resource types via an `inherits` field in YAML configuration. Inheritance chains are limited to 5 levels. When a tool declares it accepts a parent resource type (e.g., `container-instance`), it must also accept any child type (e.g., `devcontainer-instance`). This polymorphic matching enables generic container tools to work with specialized container types. ## Expected Behavior Resource types can declare an `inherits` field. The ToolRegistry performs polymorphic matching — a tool requiring `container-instance` also matches `devcontainer-instance`. Inheritance chain depth is validated at registration time. ## Acceptance Criteria - [ ] Add `inherits` field to resource type YAML schema and Pydantic model in `src/cleveragents/resource/schema.py`. - [ ] Implement inheritance chain resolution that walks the `inherits` chain up to 5 levels. - [ ] Add chain depth validation at resource type registration time — reject chains deeper than 5 levels with a clear error. - [ ] Implement polymorphic tool matching in `ToolRegistry`: when checking if a resource matches a tool's declared resource type, check both the exact type and all ancestor types in the inheritance chain. - [ ] Implement polymorphic matching in `ResourceHandlerResolver`: when resolving a handler, check for handlers registered on ancestor types if no direct handler exists. - [ ] CLI: `agents resource type show <name>` displays the inheritance chain. - [ ] CLI: `agents resource type list` shows the `inherits` field for types that have one. ## Definition of Done 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 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 - [ ] Code [Hamza]: Add `inherits` optional field to `ResourceTypeConfig` in `src/cleveragents/resource/schema.py`. - [ ] Code [Hamza]: Implement `resolve_inheritance_chain(type_name: str) -> list[str]` method in `ResourceTypeRegistry` that returns the full chain from child to root. - [ ] Code [Hamza]: Add chain depth validation (max 5) at registration time with `ResourceTypeInheritanceDepthError`. - [ ] Code [Hamza]: Implement polymorphic matching in `ToolRegistry.find_tools_for_resource()` — check resource type AND all ancestor types. - [ ] Code [Hamza]: Implement polymorphic handler resolution in `ResourceHandlerResolver` — fall back to ancestor type handlers. - [ ] Code [Hamza]: Update `agents resource type show` CLI output to display inheritance chain. - [ ] Code [Hamza]: Update `agents resource type list` CLI output to show `inherits` field. - [ ] Docs [Hamza]: Add `docs/reference/resource_type_inheritance.md` documenting the inheritance model, chain depth limits, and polymorphic matching behavior. - [ ] Tests (Behave) [Hamza]: Add `features/resource_type_inheritance.feature` covering: single-level inheritance, multi-level chain, max depth validation, polymorphic tool matching, polymorphic handler resolution, CLI display. - [ ] Tests (Robot) [Hamza]: Add `robot/resource_type_inheritance.robot` integration tests for inheritance chain resolution and CLI output. - [ ] Tests (ASV) [Hamza]: Add `benchmarks/resource_type_inheritance_bench.py` for chain resolution and polymorphic matching throughput. - [ ] Quality [Hamza]: Verify coverage >=97% via `nox -s coverage_report`. If coverage is &lt;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 improve 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%. - [ ] Quality [Hamza]: 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. Parent: #397 (Epic: Server &amp; Autonomy Infrastructure)
freemo added this to the v3.5.0 milestone 2026-03-02 16:22:42 +00:00
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".

No due date set.

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