Bug: `Tool.from_config()` and `Validation.from_config()` do not handle spec-compliant `tool:` wrapper key and `cleveragents:` version header #2065

New issue

Open

opened 2026-04-03 03:47:30 +00:00 by freemo · 0 comments

freemo commented

2026-04-03 03:47:30 +00:00

Owner

Background and Context

The specification (docs/specification.md) defines the canonical tool YAML configuration format as:

cleveragents:
  version: "3.0"

tool:
  name: local/run-migrations
  description: "Run database migrations for the API service"
  source: custom
  code: |
    return {}

The spec further states (line 30828): "Configuration files may include a top-level cleveragents.version field to indicate which schema version they target (currently "3.0"). When omitted, the latest schema version is assumed."

The domain model layer (Tool.from_config() and Validation.from_config()) does not implement this spec-compliant format. The agents tool add CLI command does correctly strip the tool: wrapper and cleveragents: header before calling Tool.from_config(), but agents validation add does not — it passes the raw dict directly to Validation.from_config(). Neither domain method handles the wrapper natively.

Current Behavior

When a spec-compliant YAML config (with the tool: wrapper key and/or cleveragents: version header) is passed directly to Tool.from_config() or Validation.from_config(), a ValueError is raised:

ValueError: Tool config must include 'name'

This occurs because the methods receive the outer dict {'cleveragents': {'version': '3.0'}, 'tool': {...}} instead of the inner tool definition dict.

Reproduction:

import yaml
from cleveragents.domain.models.core.tool import Tool

spec_yaml = """
cleveragents:
  version: "3.0"
tool:
  name: local/run-migrations
  description: Run database migrations
  source: custom
  code: 'return {}'
"""
config = yaml.safe_load(spec_yaml)
t = Tool.from_config(config)  # Raises ValueError: Tool config must include 'name'

Additionally, agents validation add CLI command passes the raw dict directly to Validation.from_config() without stripping the wrapper, so spec-compliant validation YAML files also fail via the CLI.

Expected Behavior

Both Tool.from_config() and Validation.from_config() should natively accept spec-compliant YAML configs that include:

A top-level tool: wrapper key — the method should extract the tool definition from within it.
A top-level cleveragents: version header — the method should recognise and ignore it (or validate the version).

The agents validation add CLI command should also strip the wrapper before delegating to Validation.from_config(), consistent with how agents tool add already behaves.

Acceptance Criteria

Tool.from_config() accepts a dict with a top-level tool: key and extracts the inner definition
Tool.from_config() accepts a dict with a top-level cleveragents: key and ignores it (or validates the version string)
Validation.from_config() accepts the same spec-compliant wrapper format
agents validation add CLI command strips the tool: wrapper and cleveragents: header before calling Validation.from_config(), consistent with agents tool add
Existing behaviour for flat (no-wrapper) dicts is unchanged — no regression
Behave unit test scenarios cover: flat dict, tool:-wrapped dict, cleveragents:+tool:-wrapped dict, and invalid/missing name cases
Robot Framework integration test covers the agents validation add CLI with a spec-compliant YAML file
All nox default sessions pass
Coverage ≥ 97%

Supporting Information

Affected code locations:

src/cleveragents/domain/models/core/tool.py — Tool.from_config() (~line 430) and Validation.from_config() (~line 530)
src/cleveragents/cli/commands/validation.py — add() command (does not strip wrapper before calling Validation.from_config())
src/cleveragents/cli/commands/tool.py — add() command (reference implementation that correctly strips the wrapper)

Severity: High — spec-compliant YAML files cannot be loaded by the domain model layer directly. Only the agents tool add CLI command handles this correctly; agents validation add and all direct from_config() callers do not.

Reference: docs/specification.md line 30828 — cleveragents.version field description and canonical tool YAML format.

Metadata

Branch: fix/tool-from-config-spec-wrapper
Commit Message: fix(domain): handle spec-compliant tool: wrapper and cleveragents: header in from_config()
Milestone: v3.7.0
Parent Epic: #392

Subtasks

Update Tool.from_config() in src/cleveragents/domain/models/core/tool.py to detect and unwrap a top-level tool: key
Update Tool.from_config() to detect and discard (or version-validate) a top-level cleveragents: key
Apply the same unwrapping logic to Validation.from_config() in the same file
Update agents validation add CLI command (src/cleveragents/cli/commands/validation.py) to strip the tool: wrapper and cleveragents: header before calling Validation.from_config(), mirroring agents tool add
Tests (Behave): Add scenarios for Tool.from_config() with flat dict, tool:-wrapped dict, cleveragents:+tool:-wrapped dict, and missing-name error cases
Tests (Behave): Add scenarios for Validation.from_config() with the same input variants
Tests (Robot): Add integration test for agents validation add with a spec-compliant YAML file containing the tool: wrapper and cleveragents: header
Verify coverage ≥ 97% via nox -s coverage_report
Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation.
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly.
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 The specification (`docs/specification.md`) defines the canonical tool YAML configuration format as: ```yaml cleveragents: version: "3.0" tool: name: local/run-migrations description: "Run database migrations for the API service" source: custom code: | return {} ``` The spec further states (line 30828): *"Configuration files may include a top-level `cleveragents.version` field to indicate which schema version they target (currently `"3.0"`). When omitted, the latest schema version is assumed."* The domain model layer (`Tool.from_config()` and `Validation.from_config()`) does not implement this spec-compliant format. The `agents tool add` CLI command **does** correctly strip the `tool:` wrapper and `cleveragents:` header before calling `Tool.from_config()`, but `agents validation add` does **not** — it passes the raw dict directly to `Validation.from_config()`. Neither domain method handles the wrapper natively. ## Current Behavior When a spec-compliant YAML config (with the `tool:` wrapper key and/or `cleveragents:` version header) is passed directly to `Tool.from_config()` or `Validation.from_config()`, a `ValueError` is raised: ``` ValueError: Tool config must include 'name' ``` This occurs because the methods receive the outer dict `{'cleveragents': {'version': '3.0'}, 'tool': {...}}` instead of the inner tool definition dict. **Reproduction**: ```python import yaml from cleveragents.domain.models.core.tool import Tool spec_yaml = """ cleveragents: version: "3.0" tool: name: local/run-migrations description: Run database migrations source: custom code: 'return {}' """ config = yaml.safe_load(spec_yaml) t = Tool.from_config(config) # Raises ValueError: Tool config must include 'name' ``` Additionally, `agents validation add` CLI command passes the raw dict directly to `Validation.from_config()` without stripping the wrapper, so spec-compliant validation YAML files also fail via the CLI. ## Expected Behavior Both `Tool.from_config()` and `Validation.from_config()` should natively accept spec-compliant YAML configs that include: - A top-level `tool:` wrapper key — the method should extract the tool definition from within it. - A top-level `cleveragents:` version header — the method should recognise and ignore it (or validate the version). The `agents validation add` CLI command should also strip the wrapper before delegating to `Validation.from_config()`, consistent with how `agents tool add` already behaves. ## Acceptance Criteria - [ ] `Tool.from_config()` accepts a dict with a top-level `tool:` key and extracts the inner definition - [ ] `Tool.from_config()` accepts a dict with a top-level `cleveragents:` key and ignores it (or validates the version string) - [ ] `Validation.from_config()` accepts the same spec-compliant wrapper format - [ ] `agents validation add` CLI command strips the `tool:` wrapper and `cleveragents:` header before calling `Validation.from_config()`, consistent with `agents tool add` - [ ] Existing behaviour for flat (no-wrapper) dicts is unchanged — no regression - [ ] Behave unit test scenarios cover: flat dict, `tool:`-wrapped dict, `cleveragents:`+`tool:`-wrapped dict, and invalid/missing `name` cases - [ ] Robot Framework integration test covers the `agents validation add` CLI with a spec-compliant YAML file - [ ] All `nox` default sessions pass - [ ] Coverage ≥ 97% ## Supporting Information **Affected code locations**: - `src/cleveragents/domain/models/core/tool.py` — `Tool.from_config()` (~line 430) and `Validation.from_config()` (~line 530) - `src/cleveragents/cli/commands/validation.py` — `add()` command (does not strip wrapper before calling `Validation.from_config()`) - `src/cleveragents/cli/commands/tool.py` — `add()` command (reference implementation that correctly strips the wrapper) **Severity**: High — spec-compliant YAML files cannot be loaded by the domain model layer directly. Only the `agents tool add` CLI command handles this correctly; `agents validation add` and all direct `from_config()` callers do not. **Reference**: `docs/specification.md` line 30828 — `cleveragents.version` field description and canonical tool YAML format. ## Metadata - **Branch**: `fix/tool-from-config-spec-wrapper` - **Commit Message**: `fix(domain): handle spec-compliant tool: wrapper and cleveragents: header in from_config()` - **Milestone**: v3.7.0 - **Parent Epic**: #392 ## Subtasks - [ ] Update `Tool.from_config()` in `src/cleveragents/domain/models/core/tool.py` to detect and unwrap a top-level `tool:` key - [ ] Update `Tool.from_config()` to detect and discard (or version-validate) a top-level `cleveragents:` key - [ ] Apply the same unwrapping logic to `Validation.from_config()` in the same file - [ ] Update `agents validation add` CLI command (`src/cleveragents/cli/commands/validation.py`) to strip the `tool:` wrapper and `cleveragents:` header before calling `Validation.from_config()`, mirroring `agents tool add` - [ ] Tests (Behave): Add scenarios for `Tool.from_config()` with flat dict, `tool:`-wrapped dict, `cleveragents:`+`tool:`-wrapped dict, and missing-`name` error cases - [ ] Tests (Behave): Add scenarios for `Validation.from_config()` with the same input variants - [ ] Tests (Robot): Add integration test for `agents validation add` with a spec-compliant YAML file containing the `tool:` wrapper and `cleveragents:` header - [ ] Verify coverage ≥ 97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - 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.7.0 milestone

2026-04-03 03:47:33 +00:00

freemo added a new dependency

2026-04-03 03:48:01 +00:00

#392 Epic: Actor YAML & Compiler

freemo referenced this issue

2026-04-03 03:49:47 +00:00

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

freemo self-assigned this

2026-04-03 16:58:11 +00:00