UAT: PluginError hierarchy does not inherit from CleverAgentsError — plugin exceptions bypass structured error handling pipeline #3685

New issue

Open

opened 2026-04-05 21:35:14 +00:00 by freemo · 1 comment

freemo commented

2026-04-05 21:35:14 +00:00

Owner

Background and Context

Per docs/specification.md §8.1 and §9.4, all application-specific exceptions MUST inherit from a common CleverAgentsError base class. The spec explicitly calls out PluginError as a required exception type that must be part of the main exception hierarchy.

The current implementation in src/cleveragents/infrastructure/plugins/exceptions.py defines PluginError and its subclasses as direct descendants of Python's built-in Exception, completely bypassing the project-wide exception hierarchy.

Current Behavior

# src/cleveragents/infrastructure/plugins/exceptions.py
class PluginError(Exception):  # BUG: should be CleverAgentsError
    """Base exception for all plugin-related errors."""

class PluginLoadError(PluginError): ...
class PluginNotFoundError(PluginError): ...
class ProtocolMismatchError(PluginError): ...

The following assertion fails:

from cleveragents.infrastructure.plugins.exceptions import PluginError
from cleveragents.core.exceptions import CleverAgentsError

assert issubclass(PluginError, CleverAgentsError)  # FAILS

Expected Behavior

PluginError must inherit from CleverAgentsError (imported from cleveragents.core.exceptions), making all plugin exceptions first-class citizens of the application exception hierarchy:

from cleveragents.core.exceptions import CleverAgentsError

class PluginError(CleverAgentsError):  # CORRECT
    """Base exception for all plugin-related errors."""

Impact

Plugin errors cannot be caught by top-level except CleverAgentsError handlers
classify_error() in core/error_handling.py will not map plugin errors to proper error codes — they fall through to generic INTERNAL only if they happen to be CleverAgentsError
map_domain_error() in a2a/errors.py will not correctly classify plugin errors
Plugin errors bypass the structured error handling pipeline entirely, violating the spec's architectural contract

Code Location

src/cleveragents/infrastructure/plugins/exceptions.py lines 1–30

Fix Required

Import CleverAgentsError from cleveragents.core.exceptions
Change class PluginError(Exception) → class PluginError(CleverAgentsError)
All subclasses (PluginLoadError, PluginNotFoundError, ProtocolMismatchError) inherit the fix transitively

Metadata

Branch: fix/plugin-error-inherits-cleveragents-error
Commit Message: fix(plugins): make PluginError inherit from CleverAgentsError per spec §8.1
Milestone: v3.6.0
Parent Epic: #397

Subtasks

Write TDD issue-capture Behave scenario tagged @tdd_expected_fail asserting issubclass(PluginError, CleverAgentsError) (fails before fix)
Add import of CleverAgentsError from cleveragents.core.exceptions in src/cleveragents/infrastructure/plugins/exceptions.py
Change class PluginError(Exception) to class PluginError(CleverAgentsError)
Verify PluginLoadError, PluginNotFoundError, and ProtocolMismatchError all transitively satisfy issubclass(X, CleverAgentsError)
Verify classify_error() in core/error_handling.py now correctly classifies plugin errors (add/update Behave scenario)
Verify map_domain_error() in a2a/errors.py now correctly maps plugin errors (add/update Behave scenario)
Remove @tdd_expected_fail tag once fix is in place and all scenarios pass
Run nox -e typecheck — Pyright must pass with no suppressions
Run nox -e unit_tests — all Behave scenarios pass
Run nox -e coverage_report — coverage ≥ 97%
Run nox (all default sessions) — all gates pass

Definition of Done

issubclass(PluginError, CleverAgentsError) is True
issubclass(PluginLoadError, CleverAgentsError) is True
issubclass(PluginNotFoundError, CleverAgentsError) is True
issubclass(ProtocolMismatchError, CleverAgentsError) is True
classify_error() correctly maps plugin errors to their proper error codes
map_domain_error() correctly classifies plugin errors in the A2A error path
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly: fix(plugins): make PluginError inherit from CleverAgentsError per spec §8.1
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly: fix/plugin-error-inherits-cleveragents-error
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done
All nox stages pass
Coverage >= 97%

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Background and Context Per `docs/specification.md` §8.1 and §9.4, **all application-specific exceptions MUST inherit from a common `CleverAgentsError` base class**. The spec explicitly calls out `PluginError` as a required exception type that must be part of the main exception hierarchy. The current implementation in `src/cleveragents/infrastructure/plugins/exceptions.py` defines `PluginError` and its subclasses as direct descendants of Python's built-in `Exception`, completely bypassing the project-wide exception hierarchy. ## Current Behavior ```python # src/cleveragents/infrastructure/plugins/exceptions.py class PluginError(Exception): # BUG: should be CleverAgentsError """Base exception for all plugin-related errors.""" class PluginLoadError(PluginError): ... class PluginNotFoundError(PluginError): ... class ProtocolMismatchError(PluginError): ... ``` The following assertion fails: ```python from cleveragents.infrastructure.plugins.exceptions import PluginError from cleveragents.core.exceptions import CleverAgentsError assert issubclass(PluginError, CleverAgentsError) # FAILS ``` ## Expected Behavior `PluginError` must inherit from `CleverAgentsError` (imported from `cleveragents.core.exceptions`), making all plugin exceptions first-class citizens of the application exception hierarchy: ```python from cleveragents.core.exceptions import CleverAgentsError class PluginError(CleverAgentsError): # CORRECT """Base exception for all plugin-related errors.""" ``` ## Impact - Plugin errors **cannot** be caught by top-level `except CleverAgentsError` handlers - `classify_error()` in `core/error_handling.py` will not map plugin errors to proper error codes — they fall through to generic `INTERNAL` only if they happen to be `CleverAgentsError` - `map_domain_error()` in `a2a/errors.py` will not correctly classify plugin errors - Plugin errors **bypass the structured error handling pipeline entirely**, violating the spec's architectural contract ## Code Location `src/cleveragents/infrastructure/plugins/exceptions.py` lines 1–30 ## Fix Required 1. Import `CleverAgentsError` from `cleveragents.core.exceptions` 2. Change `class PluginError(Exception)` → `class PluginError(CleverAgentsError)` 3. All subclasses (`PluginLoadError`, `PluginNotFoundError`, `ProtocolMismatchError`) inherit the fix transitively --- ## Metadata - **Branch**: `fix/plugin-error-inherits-cleveragents-error` - **Commit Message**: `fix(plugins): make PluginError inherit from CleverAgentsError per spec §8.1` - **Milestone**: v3.6.0 - **Parent Epic**: #397 ## Subtasks - [ ] Write TDD issue-capture Behave scenario tagged `@tdd_expected_fail` asserting `issubclass(PluginError, CleverAgentsError)` (fails before fix) - [ ] Add import of `CleverAgentsError` from `cleveragents.core.exceptions` in `src/cleveragents/infrastructure/plugins/exceptions.py` - [ ] Change `class PluginError(Exception)` to `class PluginError(CleverAgentsError)` - [ ] Verify `PluginLoadError`, `PluginNotFoundError`, and `ProtocolMismatchError` all transitively satisfy `issubclass(X, CleverAgentsError)` - [ ] Verify `classify_error()` in `core/error_handling.py` now correctly classifies plugin errors (add/update Behave scenario) - [ ] Verify `map_domain_error()` in `a2a/errors.py` now correctly maps plugin errors (add/update Behave scenario) - [ ] Remove `@tdd_expected_fail` tag once fix is in place and all scenarios pass - [ ] Run `nox -e typecheck` — Pyright must pass with no suppressions - [ ] Run `nox -e unit_tests` — all Behave scenarios pass - [ ] Run `nox -e coverage_report` — coverage ≥ 97% - [ ] Run `nox` (all default sessions) — all gates pass ## Definition of Done - [ ] `issubclass(PluginError, CleverAgentsError)` is `True` - [ ] `issubclass(PluginLoadError, CleverAgentsError)` is `True` - [ ] `issubclass(PluginNotFoundError, CleverAgentsError)` is `True` - [ ] `issubclass(ProtocolMismatchError, CleverAgentsError)` is `True` - [ ] `classify_error()` correctly maps plugin errors to their proper error codes - [ ] `map_domain_error()` correctly classifies plugin errors in the A2A error path - [ ] A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly: `fix(plugins): make PluginError inherit from CleverAgentsError per spec §8.1` - [ ] The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly: `fix/plugin-error-inherits-cleveragents-error` - [ ] The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done - [ ] All nox stages pass - [ ] Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added this to the v3.6.0 milestone

2026-04-05 21:36:00 +00:00

freemo added a new dependency

2026-04-05 21:36:20 +00:00

#397 Epic: Server & Autonomy Infrastructure

freemo commented

2026-04-05 22:12:40 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Critical — Plugin exceptions bypass the entire structured error handling pipeline, violating spec §8.1 and §9.4. This means classify_error() and map_domain_error() cannot properly handle plugin failures.
Milestone: v3.6.0 (already assigned — plugin architecture extensions are in scope)
Story Points: 2 — S — Single-file inheritance change with transitive fix to subclasses; straightforward but requires TDD scenario and verification across error handling paths.
MoSCoW: Must Have — The spec uses "MUST" language for the exception hierarchy requirement. All application exceptions MUST inherit from CleverAgentsError. This is a core architectural contract violation.
Parent Epic: #397

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: ca-project-owner

Issue triaged by project owner: - **State**: Verified - **Priority**: Critical — Plugin exceptions bypass the entire structured error handling pipeline, violating spec §8.1 and §9.4. This means `classify_error()` and `map_domain_error()` cannot properly handle plugin failures. - **Milestone**: v3.6.0 (already assigned — plugin architecture extensions are in scope) - **Story Points**: 2 — S — Single-file inheritance change with transitive fix to subclasses; straightforward but requires TDD scenario and verification across error handling paths. - **MoSCoW**: Must Have — The spec uses "MUST" language for the exception hierarchy requirement. All application exceptions MUST inherit from `CleverAgentsError`. This is a core architectural contract violation. - **Parent Epic**: #397 --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo referenced this issue

2026-04-05 22:16:05 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 (Resumed) #3654

freemo referenced this issue

2026-04-05 22:20:24 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 (Resumed) #3654

freemo referenced this issue

2026-04-05 22:27:14 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 (Resumed) #3654

freemo referenced this issue

2026-04-05 22:32:11 +00:00

UAT: ToolRuntimeError hierarchy does not inherit from CleverAgentsError — tool lifecycle exceptions bypass structured error handling pipeline #3762