feat(resource): wire inheritance polymorphism into tool binding and auto-discovery #942

Open
opened 2026-03-14 01:17:46 +00:00 by freemo · 2 comments
Owner

Background and Context

The specification defines resource type inheritance with polymorphic matching as a core capability (spec §Core Concepts > Resources, §Architecture > Resource System). Resource types form an inheritance hierarchy (e.g., code/python inherits from code, which inherits from file). Tools bound to a parent resource type should automatically apply to all child types. Auto-discovery should resolve the most specific resource type for a given file.

The current implementation in src/cleveragents/resource/inheritance.py (~80% complete) has:

  • ResourceTypeHierarchy — tree structure with parent/child relationships
  • ResourceType model with inheritance chain
  • is_subtype_of() and get_ancestors() methods (functional)
  • Built-in type hierarchy (file > code > code/python, file > code > code/javascript, etc.)

Missing:

  • Not wired into tool binding — When a tool declares it works with code resources, it does NOT automatically match code/python resources. Tool binding uses exact string matching, not polymorphic matching.
  • Not wired into auto-discovery — Resource auto-discovery resolves MIME type but does NOT traverse the inheritance hierarchy to find the most specific type.
  • No resource type registration from plugins — Custom resource types cannot extend the hierarchy through the plugin system.

Affected files

  • src/cleveragents/resource/inheritance.pyResourceTypeHierarchy (primitives exist)
  • src/cleveragents/application/services/tool_service.py — Tool binding resolution
  • src/cleveragents/application/services/resource_service.py — Resource discovery
  • src/cleveragents/infrastructure/plugins/registry.py — Plugin resource type registration

Expected Behavior

Tool binding must use polymorphic matching: a tool bound to code automatically applies to code/python, code/javascript, etc. Resource auto-discovery must find the most specific type in the hierarchy. Plugins must be able to register new resource types.

Acceptance Criteria

  • Tool binding uses is_subtype_of() for resource type matching (not exact string match)
  • A tool declared for resource type code automatically binds to code/python, code/rust, etc.
  • Resource auto-discovery resolves to most specific type (e.g., .py file → code/python, not just file)
  • Resource type hierarchy is queryable: resource types --tree shows the full hierarchy
  • Custom resource types registered through plugins extend the hierarchy
  • Inheritance chain exposed in resource metadata for debugging

Metadata

  • Commit message: feat(resource): wire inheritance polymorphism into tool binding and auto-discovery
  • Branch: feature/resource-inheritance-wiring
  • Parent Epic: None (standalone feature)
  • Blocks: None
  • Blocked by: None

Subtasks

  • Refactor ToolService.bind_tools() to use ResourceTypeHierarchy.is_subtype_of()
  • Refactor ResourceService.discover() to traverse hierarchy for most specific type
  • Implement resource types --tree CLI command
  • Wire resource.type_handler extension point for plugin resource types
  • Add inheritance chain to resource metadata output
  • Tests (Behave): Add scenarios for polymorphic tool binding
  • Tests (Behave): Add scenarios for resource type auto-discovery
  • Tests (Unit): Add tests for hierarchy traversal 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 tool binding uses polymorphic resource type matching, auto-discovery resolves to the most specific type, and the inheritance hierarchy is queryable and extensible.

## Background and Context The specification defines resource type inheritance with polymorphic matching as a core capability (spec §Core Concepts > Resources, §Architecture > Resource System). Resource types form an inheritance hierarchy (e.g., `code/python` inherits from `code`, which inherits from `file`). Tools bound to a parent resource type should automatically apply to all child types. Auto-discovery should resolve the most specific resource type for a given file. The current implementation in `src/cleveragents/resource/inheritance.py` (~80% complete) has: - `ResourceTypeHierarchy` — tree structure with parent/child relationships - `ResourceType` model with inheritance chain - `is_subtype_of()` and `get_ancestors()` methods (functional) - Built-in type hierarchy (`file > code > code/python`, `file > code > code/javascript`, etc.) Missing: - **Not wired into tool binding** — When a tool declares it works with `code` resources, it does NOT automatically match `code/python` resources. Tool binding uses exact string matching, not polymorphic matching. - **Not wired into auto-discovery** — Resource auto-discovery resolves MIME type but does NOT traverse the inheritance hierarchy to find the most specific type. - **No resource type registration from plugins** — Custom resource types cannot extend the hierarchy through the plugin system. ### Affected files - `src/cleveragents/resource/inheritance.py` — `ResourceTypeHierarchy` (primitives exist) - `src/cleveragents/application/services/tool_service.py` — Tool binding resolution - `src/cleveragents/application/services/resource_service.py` — Resource discovery - `src/cleveragents/infrastructure/plugins/registry.py` — Plugin resource type registration ## Expected Behavior Tool binding must use polymorphic matching: a tool bound to `code` automatically applies to `code/python`, `code/javascript`, etc. Resource auto-discovery must find the most specific type in the hierarchy. Plugins must be able to register new resource types. ## Acceptance Criteria - [ ] Tool binding uses `is_subtype_of()` for resource type matching (not exact string match) - [ ] A tool declared for resource type `code` automatically binds to `code/python`, `code/rust`, etc. - [ ] Resource auto-discovery resolves to most specific type (e.g., `.py` file → `code/python`, not just `file`) - [ ] Resource type hierarchy is queryable: `resource types --tree` shows the full hierarchy - [ ] Custom resource types registered through plugins extend the hierarchy - [ ] Inheritance chain exposed in resource metadata for debugging ## Metadata - **Commit message**: `feat(resource): wire inheritance polymorphism into tool binding and auto-discovery` - **Branch**: `feature/resource-inheritance-wiring` - **Parent Epic**: None (standalone feature) - **Blocks**: None - **Blocked by**: None ## Subtasks - [ ] Refactor `ToolService.bind_tools()` to use `ResourceTypeHierarchy.is_subtype_of()` - [ ] Refactor `ResourceService.discover()` to traverse hierarchy for most specific type - [ ] Implement `resource types --tree` CLI command - [ ] Wire `resource.type_handler` extension point for plugin resource types - [ ] Add inheritance chain to resource metadata output - [ ] Tests (Behave): Add scenarios for polymorphic tool binding - [ ] Tests (Behave): Add scenarios for resource type auto-discovery - [ ] Tests (Unit): Add tests for hierarchy traversal 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 tool binding uses polymorphic resource type matching, auto-discovery resolves to the most specific type, and the inheritance hierarchy is queryable and extensible.
freemo added this to the v3.5.0 milestone 2026-03-14 01:18:25 +00:00
freemo self-assigned this 2026-03-29 02:30:31 +00:00
Author
Owner

Implementation submitted in PR #1197.

Changes:

  • BindingResolutionService._is_type_compatible() now delegates to is_subtype_of() for polymorphic matching (ADR-042)
  • ResourceRegistryService gains discover_most_specific_type(), get_type_tree(), register_plugin_resource_type(), and get_resource_inheritance_metadata()
  • PluginManager.register_resource_types() provides the extension point for plugin resource type registration
  • resource type tree CLI command displays the full inheritance hierarchy
  • Resource metadata output includes inheritance_chain field
  • 14 BDD scenarios (53 steps) covering all acceptance criteria

Nox results: lint, format, typecheck, security_scan, dead_code, unit_tests, docs, build — all pass.

Implementation submitted in PR #1197. **Changes:** - `BindingResolutionService._is_type_compatible()` now delegates to `is_subtype_of()` for polymorphic matching (ADR-042) - `ResourceRegistryService` gains `discover_most_specific_type()`, `get_type_tree()`, `register_plugin_resource_type()`, and `get_resource_inheritance_metadata()` - `PluginManager.register_resource_types()` provides the extension point for plugin resource type registration - `resource type tree` CLI command displays the full inheritance hierarchy - Resource metadata output includes `inheritance_chain` field - 14 BDD scenarios (53 steps) covering all acceptance criteria **Nox results:** lint, format, typecheck, security_scan, dead_code, unit_tests, docs, build — all pass.
Author
Owner

PR #1197 reviewed, approved, and merged.

The implementation wires resource type inheritance polymorphism into tool binding and auto-discovery:

  • Tool binding now uses is_subtype_of() for polymorphic matching (a tool bound to code automatically matches code/python, etc.)
  • Resource auto-discovery resolves to the most specific type via discover_most_specific_type()
  • Type hierarchy is queryable via get_type_tree() and the resource type tree CLI command
  • Plugin resource type registration via register_plugin_resource_type()
  • Inheritance chain exposed in resource metadata for debugging
PR #1197 reviewed, approved, and merged. The implementation wires resource type inheritance polymorphism into tool binding and auto-discovery: - Tool binding now uses `is_subtype_of()` for polymorphic matching (a tool bound to `code` automatically matches `code/python`, etc.) - Resource auto-discovery resolves to the most specific type via `discover_most_specific_type()` - Type hierarchy is queryable via `get_type_tree()` and the `resource type tree` CLI command - Plugin resource type registration via `register_plugin_resource_type()` - Inheritance chain exposed in resource metadata for debugging
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.

Dependencies

No dependencies set.

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