cleveragents/cleveragents-core

Fork 3

UAT: `PluginDescriptor` has no `min_core_version`/`max_core_version` fields — plugin compatibility checks absent #5699

New issue

Open

opened 2026-04-09 08:40:10 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-09 08:40:10 +00:00

Owner

Bug Report

Feature Area: Plugin Architecture — Plugin Versioning
Milestone: v3.6.0
Severity: Critical (v3.6.0 deliverable: plugin versioning/compatibility checks)

What Was Tested

Analyzed src/cleveragents/infrastructure/plugins/types.py (PluginDescriptor) and src/cleveragents/infrastructure/plugins/manager.py (PluginManager.activate_plugin()) for version compatibility checking.

Expected Behavior (from spec)

The spec (§Extensibility, §Plugin Architecture Overview) and the v3.6.0 milestone describe a plugin architecture where plugins declare compatibility with specific versions of CleverAgents core. When a plugin is activated, the system should verify that the current core version satisfies the plugin's declared requirements.

The PluginDescriptor should include fields like:

min_core_version: Minimum CleverAgents version required (e.g., "3.6.0")
max_core_version: Maximum CleverAgents version supported (optional)
api_version: Plugin API version the plugin was built against

The PluginManager.activate_plugin() should check these constraints before loading.

Actual Behavior

PluginDescriptor only has a version field for the plugin's own version, with no fields for core compatibility:

class PluginDescriptor(BaseModel):
    name: str
    version: str = Field(default="0.0.0", ...)  # Plugin's own version only
    author: str = Field(default="", ...)
    description: str = Field(default="", ...)
    module_path: str = Field(default="", ...)
    class_name: str = Field(default="", ...)
    extension_points: list[str] = Field(default_factory=list, ...)
    dependencies: list[str] = Field(default_factory=list, ...)
    state: PluginState = Field(default=PluginState.DISCOVERED, ...)
    # MISSING: min_core_version, max_core_version, api_version

PluginManager.activate_plugin() performs no version compatibility checks:

def activate_plugin(self, name: str) -> None:
    # ... loads class, creates instance, sets ACTIVATED
    # NO version compatibility check anywhere

Code Location

src/cleveragents/infrastructure/plugins/types.py — PluginDescriptor class (lines 88–145)
src/cleveragents/infrastructure/plugins/manager.py — activate_plugin() (lines 222–273)

Impact

Silent incompatibility: A plugin built for v3.5.0 can be loaded against v3.6.0 without any warning, even if the plugin API changed between versions.
Runtime crashes: Incompatible plugins will fail at runtime with cryptic errors rather than a clear "incompatible version" message at activation time.
No upgrade path: When CleverAgents upgrades, there is no mechanism to detect which plugins need to be updated.

Steps to Reproduce

Inspect src/cleveragents/infrastructure/plugins/types.py — PluginDescriptor has no min_core_version field
Inspect src/cleveragents/infrastructure/plugins/manager.py — activate_plugin() has no version check

Suggested Fix

Add version compatibility fields to PluginDescriptor:

min_core_version: str = Field(default="0.0.0", description="Minimum CleverAgents version required")
max_core_version: str | None = Field(default=None, description="Maximum CleverAgents version supported")

Add compatibility check in activate_plugin():

from cleveragents import __version__
from packaging.version import Version

def _check_version_compatibility(self, descriptor: PluginDescriptor) -> None:
    current = Version(__version__)
    if descriptor.min_core_version and current < Version(descriptor.min_core_version):
        raise PluginLoadError(
            f"Plugin '{descriptor.name}' requires CleverAgents >= {descriptor.min_core_version}, "
            f"but current version is {__version__}"
        )
    if descriptor.max_core_version and current > Version(descriptor.max_core_version):
        raise PluginLoadError(
            f"Plugin '{descriptor.name}' requires CleverAgents <= {descriptor.max_core_version}, "
            f"but current version is {__version__}"
        )

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: uat-tester

## Bug Report **Feature Area**: Plugin Architecture — Plugin Versioning **Milestone**: v3.6.0 **Severity**: Critical (v3.6.0 deliverable: plugin versioning/compatibility checks) ### What Was Tested Analyzed `src/cleveragents/infrastructure/plugins/types.py` (`PluginDescriptor`) and `src/cleveragents/infrastructure/plugins/manager.py` (`PluginManager.activate_plugin()`) for version compatibility checking. ### Expected Behavior (from spec) The spec (§Extensibility, §Plugin Architecture Overview) and the v3.6.0 milestone describe a plugin architecture where plugins declare compatibility with specific versions of CleverAgents core. When a plugin is activated, the system should verify that the current core version satisfies the plugin's declared requirements. The `PluginDescriptor` should include fields like: - `min_core_version`: Minimum CleverAgents version required (e.g., `"3.6.0"`) - `max_core_version`: Maximum CleverAgents version supported (optional) - `api_version`: Plugin API version the plugin was built against The `PluginManager.activate_plugin()` should check these constraints before loading. ### Actual Behavior `PluginDescriptor` only has a `version` field for the plugin's own version, with no fields for core compatibility: ```python class PluginDescriptor(BaseModel): name: str version: str = Field(default="0.0.0", ...) # Plugin's own version only author: str = Field(default="", ...) description: str = Field(default="", ...) module_path: str = Field(default="", ...) class_name: str = Field(default="", ...) extension_points: list[str] = Field(default_factory=list, ...) dependencies: list[str] = Field(default_factory=list, ...) state: PluginState = Field(default=PluginState.DISCOVERED, ...) # MISSING: min_core_version, max_core_version, api_version ``` `PluginManager.activate_plugin()` performs no version compatibility checks: ```python def activate_plugin(self, name: str) -> None: # ... loads class, creates instance, sets ACTIVATED # NO version compatibility check anywhere ``` ### Code Location - `src/cleveragents/infrastructure/plugins/types.py` — `PluginDescriptor` class (lines 88–145) - `src/cleveragents/infrastructure/plugins/manager.py` — `activate_plugin()` (lines 222–273) ### Impact 1. **Silent incompatibility**: A plugin built for v3.5.0 can be loaded against v3.6.0 without any warning, even if the plugin API changed between versions. 2. **Runtime crashes**: Incompatible plugins will fail at runtime with cryptic errors rather than a clear "incompatible version" message at activation time. 3. **No upgrade path**: When CleverAgents upgrades, there is no mechanism to detect which plugins need to be updated. ### Steps to Reproduce 1. Inspect `src/cleveragents/infrastructure/plugins/types.py` — `PluginDescriptor` has no `min_core_version` field 2. Inspect `src/cleveragents/infrastructure/plugins/manager.py` — `activate_plugin()` has no version check ### Suggested Fix 1. Add version compatibility fields to `PluginDescriptor`: ```python min_core_version: str = Field(default="0.0.0", description="Minimum CleverAgents version required") max_core_version: str | None = Field(default=None, description="Maximum CleverAgents version supported") ``` 2. Add compatibility check in `activate_plugin()`: ```python from cleveragents import __version__ from packaging.version import Version def _check_version_compatibility(self, descriptor: PluginDescriptor) -> None: current = Version(__version__) if descriptor.min_core_version and current < Version(descriptor.min_core_version): raise PluginLoadError( f"Plugin '{descriptor.name}' requires CleverAgents >= {descriptor.min_core_version}, " f"but current version is {__version__}" ) if descriptor.max_core_version and current > Version(descriptor.max_core_version): raise PluginLoadError( f"Plugin '{descriptor.name}' requires CleverAgents <= {descriptor.max_core_version}, " f"but current version is {__version__}" ) ``` --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester

HAL9000 added the

labels

2026-04-09 08:41:13 +00:00

HAL9000 added this to the v3.6.0 milestone

2026-04-09 08:41:13 +00:00

HAL9000 added

and removed

labels

2026-04-09 08:43:29 +00:00

HAL9000 modified the milestone from v3.6.0 to v3.2.0

2026-04-09 08:46:47 +00:00

HAL9000 added

and removed

labels

2026-04-09 08:47:07 +00:00

HAL9000 commented

2026-04-09 08:49:02 +00:00

Author

Owner

Label compliance fix applied:

Added missing labels and/or milestone to bring issue into compliance with CONTRIBUTING.md

Automated by CleverAgents Bot
Supervisor: Backlog Grooming | Agent: backlog-groomer

Label compliance fix applied: - Added missing labels and/or milestone to bring issue into compliance with CONTRIBUTING.md --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: backlog-groomer

HAL9000 added a new dependency

2026-04-09 08:49:40 +00:00

#5711 EPIC: Plugin Architecture Extensions — Plugin Manager, CLI & Lifecycle (v3.6.0)

HAL9000 referenced this issue

2026-04-09 09:03:20 +00:00

feat(plugins): implement PluginManager lifecycle state machine and PluginDescriptor compatibility fields #5747

HAL9000 referenced this issue

2026-04-09 09:03:59 +00:00

[AUTO-PROJ-OWN] Project Owner Report (Cycle 10) #5748

HAL9000 referenced this issue

2026-04-09 09:12:13 +00:00

EPIC: Plugin Architecture Extensions — Plugin Manager, CLI & Lifecycle (v3.6.0) #5711