cleveragents/cleveragents-core

Fork 3

Bug: `agents actor add` bypasses v3 ActorConfigSchema validation — uses legacy v2 parser instead #2853

New issue

Open

opened 2026-04-04 20:56:21 +00:00 by freemo · 2 comments

freemo commented

2026-04-04 20:56:21 +00:00

Owner

Metadata

Branch: fix/actor-registry-v3-schema-validation
Commit Message: fix(actor): use ActorConfigSchema v3 validation in ActorRegistry.add() and actor add CLI command
Milestone: v3.2.0
Parent Epic: #392

Background

The specification states that actors are defined via YAML configuration files using the v3 schema (with type: llm/tool/graph, route for graph actors, skills, context_view, role_hint, etc.). The v3 schema is implemented in src/cleveragents/actor/schema.py as ActorConfigSchema.

However, the agents actor add CLI command (src/cleveragents/cli/commands/actor.py) and the ActorRegistry.add() method (src/cleveragents/actor/registry.py) use the legacy v2 parser (ActorConfiguration.from_blob() / ActorConfiguration.load_yaml_text()) instead of the v3 ActorConfigSchema.

This means:

No type validation: The type: llm/tool/graph field is not validated
No graph topology validation: For GRAPH actors, the route (nodes, edges, entry/exit) is not validated
No tool reference validation: Tool references in the actor config are not checked
No context_view/role_hint validation: These v3 fields are ignored
No cycle detection: Graph cycles are not detected at add time
No unreachable node detection: Unreachable nodes are not detected

The ActorLoader (used for file-based discovery) correctly uses ActorConfigSchema, but the ActorRegistry.add() method (used by agents actor add) does not.

Steps to Reproduce

Create an invalid v3 actor YAML file with a GRAPH type but no route field:

name: local/bad-actor
type: graph
model: gpt-4
provider: openai
description: Bad actor without route

Run agents actor add --config bad-actor.yaml
Expected: Validation error — "GRAPH actors require 'route' field"
Actual: Actor is added successfully without validation

Code Location

src/cleveragents/actor/registry.py — ActorRegistry.add() uses ActorConfiguration.load_yaml_text() (v2 parser) instead of ActorConfigSchema
src/cleveragents/cli/commands/actor.py — add() command uses ActorConfiguration.from_blob() (v2 parser)

Subtasks

Audit ActorRegistry.add() in src/cleveragents/actor/registry.py to identify all v2 parser call sites
Audit src/cleveragents/cli/commands/actor.py add() command for v2 parser usage
Replace ActorConfiguration.load_yaml_text() / ActorConfiguration.from_blob() calls with ActorConfigSchema.model_validate() in ActorRegistry.add()
Ensure ActorRegistry.add() raises a descriptive ValueError (or domain-specific exception) on v3 schema validation failure
Update src/cleveragents/cli/commands/actor.py to propagate validation errors from ActorRegistry.add() with a user-friendly CLI error message
Write Behave unit test scenarios covering: LLM actor valid YAML passes, GRAPH actor missing route fails, GRAPH actor with cycle fails, GRAPH actor with unreachable node fails, invalid type field fails, missing context_view / role_hint fields are handled gracefully
Write Robot Framework integration test: agents actor add with invalid GRAPH YAML exits non-zero with descriptive error message
Verify ActorLoader.discover() and ActorRegistry.add() now share the same validation path
Update docstrings on ActorRegistry.add() to document the v3 schema validation contract

Definition of Done

ActorRegistry.add() validates actor YAML using ActorConfigSchema.model_validate() (v3 schema) before persisting
agents actor add with an invalid v3 YAML (e.g., GRAPH actor missing route) exits with a non-zero status code and a descriptive error message
All six validation failure modes (type, graph topology, tool references, context_view/role_hint, cycle detection, unreachable nodes) are covered by Behave unit test scenarios
Robot Framework integration test confirms CLI error behaviour end-to-end
ActorLoader.discover() and ActorRegistry.add() use the same ActorConfigSchema validation path (no divergence)
All nox stages pass (nox -e lint, nox -e typecheck, nox -e unit_tests, nox -e integration_tests)
Coverage >= 97%

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

## Metadata - **Branch**: `fix/actor-registry-v3-schema-validation` - **Commit Message**: `fix(actor): use ActorConfigSchema v3 validation in ActorRegistry.add() and actor add CLI command` - **Milestone**: v3.2.0 - **Parent Epic**: #392 ## Background The specification states that actors are defined via YAML configuration files using the v3 schema (with `type: llm/tool/graph`, `route` for graph actors, `skills`, `context_view`, `role_hint`, etc.). The v3 schema is implemented in `src/cleveragents/actor/schema.py` as `ActorConfigSchema`. However, the `agents actor add` CLI command (`src/cleveragents/cli/commands/actor.py`) and the `ActorRegistry.add()` method (`src/cleveragents/actor/registry.py`) use the **legacy v2 parser** (`ActorConfiguration.from_blob()` / `ActorConfiguration.load_yaml_text()`) instead of the v3 `ActorConfigSchema`. This means: 1. **No type validation**: The `type: llm/tool/graph` field is not validated 2. **No graph topology validation**: For GRAPH actors, the `route` (nodes, edges, entry/exit) is not validated 3. **No tool reference validation**: Tool references in the actor config are not checked 4. **No context_view/role_hint validation**: These v3 fields are ignored 5. **No cycle detection**: Graph cycles are not detected at add time 6. **No unreachable node detection**: Unreachable nodes are not detected The `ActorLoader` (used for file-based discovery) correctly uses `ActorConfigSchema`, but the `ActorRegistry.add()` method (used by `agents actor add`) does not. ## Steps to Reproduce 1. Create an invalid v3 actor YAML file with a GRAPH type but no `route` field: ```yaml name: local/bad-actor type: graph model: gpt-4 provider: openai description: Bad actor without route ``` 2. Run `agents actor add --config bad-actor.yaml` 3. **Expected**: Validation error — "GRAPH actors require 'route' field" 4. **Actual**: Actor is added successfully without validation ## Code Location - `src/cleveragents/actor/registry.py` — `ActorRegistry.add()` uses `ActorConfiguration.load_yaml_text()` (v2 parser) instead of `ActorConfigSchema` - `src/cleveragents/cli/commands/actor.py` — `add()` command uses `ActorConfiguration.from_blob()` (v2 parser) ## Subtasks - [ ] Audit `ActorRegistry.add()` in `src/cleveragents/actor/registry.py` to identify all v2 parser call sites - [ ] Audit `src/cleveragents/cli/commands/actor.py` `add()` command for v2 parser usage - [ ] Replace `ActorConfiguration.load_yaml_text()` / `ActorConfiguration.from_blob()` calls with `ActorConfigSchema.model_validate()` in `ActorRegistry.add()` - [ ] Ensure `ActorRegistry.add()` raises a descriptive `ValueError` (or domain-specific exception) on v3 schema validation failure - [ ] Update `src/cleveragents/cli/commands/actor.py` to propagate validation errors from `ActorRegistry.add()` with a user-friendly CLI error message - [ ] Write Behave unit test scenarios covering: LLM actor valid YAML passes, GRAPH actor missing `route` fails, GRAPH actor with cycle fails, GRAPH actor with unreachable node fails, invalid `type` field fails, missing `context_view` / `role_hint` fields are handled gracefully - [ ] Write Robot Framework integration test: `agents actor add` with invalid GRAPH YAML exits non-zero with descriptive error message - [ ] Verify `ActorLoader.discover()` and `ActorRegistry.add()` now share the same validation path - [ ] Update docstrings on `ActorRegistry.add()` to document the v3 schema validation contract ## Definition of Done - [ ] `ActorRegistry.add()` validates actor YAML using `ActorConfigSchema.model_validate()` (v3 schema) before persisting - [ ] `agents actor add` with an invalid v3 YAML (e.g., GRAPH actor missing `route`) exits with a non-zero status code and a descriptive error message - [ ] All six validation failure modes (type, graph topology, tool references, context_view/role_hint, cycle detection, unreachable nodes) are covered by Behave unit test scenarios - [ ] Robot Framework integration test confirms CLI error behaviour end-to-end - [ ] `ActorLoader.discover()` and `ActorRegistry.add()` use the same `ActorConfigSchema` validation path (no divergence) - [ ] All nox stages pass (`nox -e lint`, `nox -e typecheck`, `nox -e unit_tests`, `nox -e integration_tests`) - [ ] Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added this to the v3.2.0 milestone

2026-04-04 20:56:35 +00:00

freemo added a new dependency

2026-04-04 20:56:45 +00:00

#392 Epic: Actor YAML & Compiler

freemo referenced this issue

2026-04-04 20:57:37 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.7.0 — Session Tracker #2803

freemo referenced this issue

2026-04-04 20:58:22 +00:00

[CA-AUTO] Backlog Groomer — groomer-1 — Session Tracker #2771

freemo referenced this issue

2026-04-04 21:03:15 +00:00

[CA-AUTO] Project Owner — project-owner-1 — Session Tracker #2793

freemo referenced this issue

2026-04-04 21:08:24 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.7.0 — Session Tracker #2803

freemo commented

2026-04-05 06:28:10 +00:00

Author

Owner

Starting implementation on branch fix/actor-registry-v3-schema-validation.

Plan: TDD approach — writing failing Behave tests first, then fixing ActorRegistry.add() and agents actor add CLI to use ActorConfigSchema.model_validate() instead of the legacy v2 ActorConfiguration.load_yaml_text() / ActorConfiguration.from_blob() parsers.

Key changes:

ActorRegistry.add() — replace ActorConfiguration.load_yaml_text() with ActorConfigSchema.model_validate()
agents actor add CLI — propagate v3 validation errors with user-friendly messages
New Behave unit test scenarios covering all 6 validation failure modes
New Robot Framework integration test for CLI error behaviour

Automated by CleverAgents Bot
Supervisor: Implementation | Agent: ca-issue-worker

Starting implementation on branch `fix/actor-registry-v3-schema-validation`. **Plan**: TDD approach — writing failing Behave tests first, then fixing `ActorRegistry.add()` and `agents actor add` CLI to use `ActorConfigSchema.model_validate()` instead of the legacy v2 `ActorConfiguration.load_yaml_text()` / `ActorConfiguration.from_blob()` parsers. **Key changes**: 1. `ActorRegistry.add()` — replace `ActorConfiguration.load_yaml_text()` with `ActorConfigSchema.model_validate()` 2. `agents actor add` CLI — propagate v3 validation errors with user-friendly messages 3. New Behave unit test scenarios covering all 6 validation failure modes 4. New Robot Framework integration test for CLI error behaviour --- **Automated by CleverAgents Bot** Supervisor: Implementation | Agent: ca-issue-worker

freemo referenced this issue

2026-04-05 06:33:04 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.2.0–v3.7.0 — Session Tracker #3094

freemo referenced this issue

2026-04-05 07:21:47 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.2.0–v3.7.0 — Session Tracker #3094

freemo referenced this issue

2026-04-05 20:29:17 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3572

freemo removed this from the v3.2.0 milestone

2026-04-06 22:28:45 +00:00

freemo commented

2026-04-06 22:29:02 +00:00

Author

Owner

This issue has been moved to the backlog as part of an aggressive grooming of the v3.2.0 milestone. It has been deemed non-critical for the minimal viability of the milestone and will be addressed in a future release.