UAT: SandboxError hierarchy does not inherit from CleverAgentsError — sandbox exceptions bypass structured error handling pipeline #3771

New issue

Open

opened 2026-04-05 22:35:16 +00:00 by freemo · 0 comments

freemo commented

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

Owner

Background and Context

Per docs/specification.md and the project's error handling philosophy (ADR-005), all application-specific exceptions MUST inherit from CleverAgentsError to ensure consistent error handling, structured logging, and propagation through the top-level error pipeline.

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

Current Behavior

# src/cleveragents/infrastructure/sandbox/protocol.py
class SandboxError(Exception):  # BUG: should be CleverAgentsError
    """Base exception for all sandbox-related errors."""

class SandboxCreationError(SandboxError): ...
class SandboxCommitError(SandboxError): ...
class SandboxRollbackError(SandboxError): ...
class SandboxStateError(SandboxError): ...
class AtomicCommitError(SandboxError): ...

The following assertion fails:

from cleveragents.infrastructure.sandbox.protocol import SandboxError
from cleveragents.core.exceptions import CleverAgentsError
assert issubclass(SandboxError, CleverAgentsError)  # AssertionError

Expected Behavior

SandboxError should inherit from CleverAgentsError (from cleveragents.core.exceptions):

from cleveragents.core.exceptions import CleverAgentsError

class SandboxError(CleverAgentsError):
    """Base exception for all sandbox-related errors."""

All subclasses (SandboxCreationError, SandboxCommitError, SandboxRollbackError, SandboxStateError, AtomicCommitError) would automatically inherit from CleverAgentsError through SandboxError.

Impact

Sandbox exceptions cannot be caught by top-level CleverAgentsError handlers
Structured error logging pipeline is bypassed for all sandbox failures
Inconsistent with the project-wide exception hierarchy pattern
Similar bug already filed for PluginError as issue #3685

Code Location

src/cleveragents/infrastructure/sandbox/protocol.py — lines defining SandboxError and subclasses

Steps to Reproduce

Import SandboxError from cleveragents.infrastructure.sandbox.protocol
Import CleverAgentsError from cleveragents.core.exceptions
Assert issubclass(SandboxError, CleverAgentsError) — this fails

Metadata

Branch: fix/sandbox-error-inherits-cleveragents-error
Commit Message: fix(sandbox): make SandboxError inherit from CleverAgentsError
Milestone: (none — backlog)
Parent Epic: #397

Subtasks

Write TDD issue-capture Behave scenario tagged @tdd_expected_fail asserting issubclass(SandboxError, CleverAgentsError) (fails before fix)
Add import of CleverAgentsError from cleveragents.core.exceptions in src/cleveragents/infrastructure/sandbox/protocol.py
Change class SandboxError(Exception) to class SandboxError(CleverAgentsError)
Verify SandboxCreationError, SandboxCommitError, SandboxRollbackError, SandboxStateError, and AtomicCommitError all transitively satisfy issubclass(X, CleverAgentsError)
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

SandboxError inherits from CleverAgentsError
All SandboxError subclasses transitively inherit from CleverAgentsError
issubclass(SandboxError, CleverAgentsError) passes
issubclass(SandboxCreationError, CleverAgentsError) passes
issubclass(SandboxCommitError, CleverAgentsError) passes
issubclass(SandboxRollbackError, CleverAgentsError) passes
issubclass(SandboxStateError, CleverAgentsError) passes
issubclass(AtomicCommitError, CleverAgentsError) passes
Existing sandbox tests continue to pass
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly: fix(sandbox): make SandboxError inherit from CleverAgentsError
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly: fix/sandbox-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%

Backlog note: This issue was discovered during autonomous operation
on milestone v3.6.0. It does not block milestone completion and has been
placed in the backlog for human review and future milestone assignment.

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

## Background and Context Per `docs/specification.md` and the project's error handling philosophy (ADR-005), **all application-specific exceptions MUST inherit from `CleverAgentsError`** to ensure consistent error handling, structured logging, and propagation through the top-level error pipeline. The current implementation in `src/cleveragents/infrastructure/sandbox/protocol.py` defines `SandboxError` 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/sandbox/protocol.py class SandboxError(Exception): # BUG: should be CleverAgentsError """Base exception for all sandbox-related errors.""" class SandboxCreationError(SandboxError): ... class SandboxCommitError(SandboxError): ... class SandboxRollbackError(SandboxError): ... class SandboxStateError(SandboxError): ... class AtomicCommitError(SandboxError): ... ``` The following assertion fails: ```python from cleveragents.infrastructure.sandbox.protocol import SandboxError from cleveragents.core.exceptions import CleverAgentsError assert issubclass(SandboxError, CleverAgentsError) # AssertionError ``` ## Expected Behavior `SandboxError` should inherit from `CleverAgentsError` (from `cleveragents.core.exceptions`): ```python from cleveragents.core.exceptions import CleverAgentsError class SandboxError(CleverAgentsError): """Base exception for all sandbox-related errors.""" ``` All subclasses (`SandboxCreationError`, `SandboxCommitError`, `SandboxRollbackError`, `SandboxStateError`, `AtomicCommitError`) would automatically inherit from `CleverAgentsError` through `SandboxError`. ## Impact - Sandbox exceptions cannot be caught by top-level `CleverAgentsError` handlers - Structured error logging pipeline is bypassed for all sandbox failures - Inconsistent with the project-wide exception hierarchy pattern - Similar bug already filed for `PluginError` as issue #3685 ## Code Location `src/cleveragents/infrastructure/sandbox/protocol.py` — lines defining `SandboxError` and subclasses ## Steps to Reproduce 1. Import `SandboxError` from `cleveragents.infrastructure.sandbox.protocol` 2. Import `CleverAgentsError` from `cleveragents.core.exceptions` 3. Assert `issubclass(SandboxError, CleverAgentsError)` — this fails --- ## Metadata - **Branch**: `fix/sandbox-error-inherits-cleveragents-error` - **Commit Message**: `fix(sandbox): make SandboxError inherit from CleverAgentsError` - **Milestone**: *(none — backlog)* - **Parent Epic**: #397 ## Subtasks - [ ] Write TDD issue-capture Behave scenario tagged `@tdd_expected_fail` asserting `issubclass(SandboxError, CleverAgentsError)` (fails before fix) - [ ] Add import of `CleverAgentsError` from `cleveragents.core.exceptions` in `src/cleveragents/infrastructure/sandbox/protocol.py` - [ ] Change `class SandboxError(Exception)` to `class SandboxError(CleverAgentsError)` - [ ] Verify `SandboxCreationError`, `SandboxCommitError`, `SandboxRollbackError`, `SandboxStateError`, and `AtomicCommitError` all transitively satisfy `issubclass(X, CleverAgentsError)` - [ ] 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 - [ ] `SandboxError` inherits from `CleverAgentsError` - [ ] All `SandboxError` subclasses transitively inherit from `CleverAgentsError` - [ ] `issubclass(SandboxError, CleverAgentsError)` passes - [ ] `issubclass(SandboxCreationError, CleverAgentsError)` passes - [ ] `issubclass(SandboxCommitError, CleverAgentsError)` passes - [ ] `issubclass(SandboxRollbackError, CleverAgentsError)` passes - [ ] `issubclass(SandboxStateError, CleverAgentsError)` passes - [ ] `issubclass(AtomicCommitError, CleverAgentsError)` passes - [ ] Existing sandbox tests continue to pass - [ ] A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly: `fix(sandbox): make SandboxError inherit from CleverAgentsError` - [ ] The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly: `fix/sandbox-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% > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.6.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added a new dependency

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

#397 Epic: Server & Autonomy Infrastructure

freemo referenced this issue

2026-04-06 06:41:50 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775