UAT: `ActorLoader._resolve_tools()` warns instead of failing when a tool reference is unresolved — violates spec loading contract #3711

New issue

Open

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

freemo commented

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

Owner

Metadata

Branch: fix/actor-loader-fail-on-unresolved-tool-ref
Commit Message: fix(actor): raise ValidationError instead of warning when tool reference is unresolved in ActorLoader
Milestone: None (Backlog)
Parent Epic: #235

Background and Context

Per docs/specification.md §Actor Loading:

"The loader must resolve all tool references within the actor's definition against the ToolRegistry. If a referenced tool does not exist, the loading process for that actor must fail with a clear error message."

The current implementation in src/cleveragents/actor/loader.py only logs a warning and appends to self._warnings when a tool reference cannot be resolved. It does not fail the loading process as the spec requires.

Current Behavior

ActorLoader._resolve_tools() (lines ~200–215 of loader.py):

def _resolve_tools(self, config: ActorConfigSchema) -> None:
    if self._tool_registry is None:
        return
    for tool_ref in config.tools:
        if isinstance(tool_ref, str):
            spec = self._tool_registry.get(tool_ref)
            if spec is None:
                msg = (
                    f"Unresolved tool reference '{tool_ref}' "
                    f"in actor '{config.name}'"
                )
                logger.warning(msg)
                self._warnings.append(msg)  # BUG: only warns, does not fail

When a tool reference cannot be resolved, the actor is still loaded successfully. The caller receives a warning in loader.warnings but the actor is registered as if it were valid.

Expected Behavior

Per the specification, when a tool reference cannot be resolved, the loading process for that actor must fail with a clear error message. The _resolve_tools() method should raise a ValidationError (from cleveragents.core.exceptions) instead of appending to self._warnings.

The corrected behavior:

def _resolve_tools(self, config: ActorConfigSchema) -> None:
    if self._tool_registry is None:
        return
    for tool_ref in config.tools:
        if isinstance(tool_ref, str):
            spec = self._tool_registry.get(tool_ref)
            if spec is None:
                raise ValidationError(
                    f"Unresolved tool reference '{tool_ref}' "
                    f"in actor '{config.name}'"
                )

Impact

Actors with invalid tool references are silently loaded and registered, leading to runtime failures when the actor attempts to invoke the missing tool.
The spec's loading contract is violated — callers cannot rely on a successfully loaded actor having all its tool references resolved.
The loader.warnings list provides a false sense of security — callers may not check warnings, leading to silent failures.

Steps to Reproduce

Create an actor YAML file that references a tool that does not exist in the ToolRegistry.
Instantiate ActorLoader with a ToolRegistry that does not contain the referenced tool.
Call loader.discover().
Expected: ValidationError is raised with a clear message about the unresolved tool reference.
Actual: discover() succeeds, the actor is loaded, and loader.warnings contains the unresolved tool message.

Code Location

src/cleveragents/actor/loader.py — _resolve_tools() method (approximately lines 200–215)

Subtasks

Write a TDD failing Behave scenario (@tdd_expected_fail) asserting that ActorLoader.discover() raises ValidationError when a tool reference is unresolved
Change _resolve_tools() to raise ValidationError instead of appending to self._warnings
Remove the logger.warning(msg) and self._warnings.append(msg) lines for unresolved tool references
Verify that discover() propagates the ValidationError to the caller
Remove @tdd_expected_fail tag once fix is in place
Verify nox -e typecheck passes
Verify nox -e unit_tests passes with coverage >= 97%
Run nox (all default sessions), fix any errors

Definition of Done

ActorLoader.discover() raises ValidationError when any tool reference in an actor's definition cannot be resolved in the ToolRegistry
The error message clearly identifies the unresolved tool reference and the actor name
No actor with unresolved tool references is registered in the cache
Behave BDD scenarios cover this behavior
All nox stages pass
Coverage >= 97%

Backlog note: This issue was discovered during autonomous UAT testing of the Actor System feature area. 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

## Metadata - **Branch**: `fix/actor-loader-fail-on-unresolved-tool-ref` - **Commit Message**: `fix(actor): raise ValidationError instead of warning when tool reference is unresolved in ActorLoader` - **Milestone**: None (Backlog) - **Parent Epic**: #235 ## Background and Context Per `docs/specification.md` §Actor Loading: > "The loader must resolve all tool references within the actor's definition against the `ToolRegistry`. If a referenced tool does not exist, the loading process for that actor must fail with a clear error message." The current implementation in `src/cleveragents/actor/loader.py` only logs a warning and appends to `self._warnings` when a tool reference cannot be resolved. It does **not** fail the loading process as the spec requires. ## Current Behavior `ActorLoader._resolve_tools()` (lines ~200–215 of `loader.py`): ```python def _resolve_tools(self, config: ActorConfigSchema) -> None: if self._tool_registry is None: return for tool_ref in config.tools: if isinstance(tool_ref, str): spec = self._tool_registry.get(tool_ref) if spec is None: msg = ( f"Unresolved tool reference '{tool_ref}' " f"in actor '{config.name}'" ) logger.warning(msg) self._warnings.append(msg) # BUG: only warns, does not fail ``` When a tool reference cannot be resolved, the actor is still loaded successfully. The caller receives a warning in `loader.warnings` but the actor is registered as if it were valid. ## Expected Behavior Per the specification, when a tool reference cannot be resolved, the loading process for that actor **must fail** with a clear error message. The `_resolve_tools()` method should raise a `ValidationError` (from `cleveragents.core.exceptions`) instead of appending to `self._warnings`. The corrected behavior: ```python def _resolve_tools(self, config: ActorConfigSchema) -> None: if self._tool_registry is None: return for tool_ref in config.tools: if isinstance(tool_ref, str): spec = self._tool_registry.get(tool_ref) if spec is None: raise ValidationError( f"Unresolved tool reference '{tool_ref}' " f"in actor '{config.name}'" ) ``` ## Impact - Actors with invalid tool references are silently loaded and registered, leading to runtime failures when the actor attempts to invoke the missing tool. - The spec's loading contract is violated — callers cannot rely on a successfully loaded actor having all its tool references resolved. - The `loader.warnings` list provides a false sense of security — callers may not check warnings, leading to silent failures. ## Steps to Reproduce 1. Create an actor YAML file that references a tool that does not exist in the `ToolRegistry`. 2. Instantiate `ActorLoader` with a `ToolRegistry` that does not contain the referenced tool. 3. Call `loader.discover()`. 4. **Expected**: `ValidationError` is raised with a clear message about the unresolved tool reference. 5. **Actual**: `discover()` succeeds, the actor is loaded, and `loader.warnings` contains the unresolved tool message. ## Code Location `src/cleveragents/actor/loader.py` — `_resolve_tools()` method (approximately lines 200–215) ## Subtasks - [ ] Write a TDD failing Behave scenario (`@tdd_expected_fail`) asserting that `ActorLoader.discover()` raises `ValidationError` when a tool reference is unresolved - [ ] Change `_resolve_tools()` to raise `ValidationError` instead of appending to `self._warnings` - [ ] Remove the `logger.warning(msg)` and `self._warnings.append(msg)` lines for unresolved tool references - [ ] Verify that `discover()` propagates the `ValidationError` to the caller - [ ] Remove `@tdd_expected_fail` tag once fix is in place - [ ] Verify `nox -e typecheck` passes - [ ] Verify `nox -e unit_tests` passes with coverage >= 97% - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done - [ ] `ActorLoader.discover()` raises `ValidationError` when any tool reference in an actor's definition cannot be resolved in the `ToolRegistry` - [ ] The error message clearly identifies the unresolved tool reference and the actor name - [ ] No actor with unresolved tool references is registered in the cache - [ ] Behave BDD scenarios cover this behavior - [ ] All nox stages pass - [ ] Coverage >= 97% > **Backlog note:** This issue was discovered during autonomous UAT testing of the Actor System feature area. 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:16:22 +00:00

#235 feat(domain): rebaseline plan phases and apply states

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:22:42 +00:00

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

freemo referenced this issue

2026-04-05 22:23:46 +00:00

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