UAT: agents tool add fails when YAML config uses spec-required tool: wrapper key #1471

Closed
opened 2026-04-02 19:15:15 +00:00 by freemo · 2 comments
Owner

Metadata

  • Branch: fix/tool-add-yaml-wrapper-key
  • Commit Message: fix(cli): handle tool: wrapper key in agents tool add YAML config
  • Milestone: v3.2.0
  • Parent Epic: #374

Background and context

The specification (docs/specification.md, Tool Configuration section) defines tool YAML files using a tool: wrapper key alongside a cleveragents: version header:

cleveragents:
  version: "3.0"

tool:
  name: local/run-migrations
  description: "Run database migrations"
  source: custom
  code: |
    def run(params):
        return {}

However, the CLI implementation in src/cleveragents/cli/commands/tool.py (lines 243–247) passes the entire parsed YAML dict directly to Tool.from_config():

config_dict = yaml.safe_load(raw)
tool = Tool.from_config(config_dict)

Since Tool.from_config() expects name, description, and source at the top level, it raises "Tool config must include 'name'" whenever a user follows the spec-prescribed format. This is a spec-vs-implementation mismatch discovered during UAT.

Current behavior

Running agents tool add with a spec-compliant YAML file (containing the tool: wrapper key) raises:

Error: Tool config must include 'name'

Reproduction:

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

spec_yaml = '''
cleveragents:
  version: "3.0"
tool:
  name: local/test-tool
  description: Test
  source: custom
  code: "def run(p): return {}"
'''
data = yaml.safe_load(spec_yaml)
Tool.from_config(data)  # Raises: "Tool config must include 'name'"

Code location: src/cleveragents/cli/commands/tool.py lines 240–247

Expected behavior

agents tool add should successfully parse both YAML formats:

  1. Wrapped format (spec example): top-level tool: key containing the tool fields
  2. Flat format (spec Structure Reference): name, description, source at the top level

The CLI should detect the presence of a tool: key and extract the sub-dict before passing it to Tool.from_config(), consistent with how SkillConfigSchema.from_yaml() handles the skill flat format.

Acceptance criteria

  • agents tool add <file> succeeds when the YAML file uses the tool: wrapper key (spec example format)
  • agents tool add <file> continues to succeed when the YAML file uses the flat format (no wrapper key)
  • An optional cleveragents: version header in the YAML is silently ignored and does not cause an error
  • A clear error message is shown when neither format yields a valid name field
  • All existing agents tool command tests continue to pass

Subtasks

  • Investigate src/cleveragents/cli/commands/tool.py lines 240–247 and confirm the missing extraction logic
  • Add YAML format detection: if parsed dict contains a tool: key, extract config_dict["tool"] before calling Tool.from_config()
  • Strip the cleveragents: version header key if present (ignore it gracefully)
  • Add unit tests covering: wrapped format, flat format, wrapped + version header, missing name error path
  • Tests (Behave): Add scenario for agents tool add with spec-format YAML
  • Tests (Robot): Add integration test for agents tool add with both YAML formats
  • 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 (fix(cli): handle tool: wrapper key in agents tool add YAML config), 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 (fix/tool-add-yaml-wrapper-key).
  • 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%

Supporting information

  • Spec reference: docs/specification.md — Tool Configuration section (wrapped format) and Structure Reference section (flat format)
  • Related implementation: src/cleveragents/cli/commands/tool.py lines 240–247
  • Analogous working pattern: SkillConfigSchema.from_yaml() in the skill CLI
  • Parent Legendary: #374 Actors, Skills & Tool Execution (Workstream C)
  • Discovered during UAT testing on 2026-04-02

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-uat-tester

## Metadata - **Branch**: `fix/tool-add-yaml-wrapper-key` - **Commit Message**: `fix(cli): handle tool: wrapper key in agents tool add YAML config` - **Milestone**: v3.2.0 - **Parent Epic**: #374 ## Background and context The specification (`docs/specification.md`, Tool Configuration section) defines tool YAML files using a `tool:` wrapper key alongside a `cleveragents:` version header: ```yaml cleveragents: version: "3.0" tool: name: local/run-migrations description: "Run database migrations" source: custom code: | def run(params): return {} ``` However, the CLI implementation in `src/cleveragents/cli/commands/tool.py` (lines 243–247) passes the entire parsed YAML dict directly to `Tool.from_config()`: ```python config_dict = yaml.safe_load(raw) tool = Tool.from_config(config_dict) ``` Since `Tool.from_config()` expects `name`, `description`, and `source` at the top level, it raises `"Tool config must include 'name'"` whenever a user follows the spec-prescribed format. This is a spec-vs-implementation mismatch discovered during UAT. ## Current behavior Running `agents tool add` with a spec-compliant YAML file (containing the `tool:` wrapper key) raises: ``` Error: Tool config must include 'name' ``` Reproduction: ```python import yaml from cleveragents.domain.models.core.tool import Tool spec_yaml = ''' cleveragents: version: "3.0" tool: name: local/test-tool description: Test source: custom code: "def run(p): return {}" ''' data = yaml.safe_load(spec_yaml) Tool.from_config(data) # Raises: "Tool config must include 'name'" ``` **Code location**: `src/cleveragents/cli/commands/tool.py` lines 240–247 ## Expected behavior `agents tool add` should successfully parse both YAML formats: 1. **Wrapped format** (spec example): top-level `tool:` key containing the tool fields 2. **Flat format** (spec Structure Reference): `name`, `description`, `source` at the top level The CLI should detect the presence of a `tool:` key and extract the sub-dict before passing it to `Tool.from_config()`, consistent with how `SkillConfigSchema.from_yaml()` handles the skill flat format. ## Acceptance criteria - [ ] `agents tool add <file>` succeeds when the YAML file uses the `tool:` wrapper key (spec example format) - [ ] `agents tool add <file>` continues to succeed when the YAML file uses the flat format (no wrapper key) - [ ] An optional `cleveragents:` version header in the YAML is silently ignored and does not cause an error - [ ] A clear error message is shown when neither format yields a valid `name` field - [ ] All existing `agents tool` command tests continue to pass ## Subtasks - [ ] Investigate `src/cleveragents/cli/commands/tool.py` lines 240–247 and confirm the missing extraction logic - [ ] Add YAML format detection: if parsed dict contains a `tool:` key, extract `config_dict["tool"]` before calling `Tool.from_config()` - [ ] Strip the `cleveragents:` version header key if present (ignore it gracefully) - [ ] Add unit tests covering: wrapped format, flat format, wrapped + version header, missing `name` error path - [ ] Tests (Behave): Add scenario for `agents tool add` with spec-format YAML - [ ] Tests (Robot): Add integration test for `agents tool add` with both YAML formats - [ ] 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 (`fix(cli): handle tool: wrapper key in agents tool add YAML config`), 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 (`fix/tool-add-yaml-wrapper-key`). - 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% ## Supporting information - Spec reference: `docs/specification.md` — Tool Configuration section (wrapped format) and Structure Reference section (flat format) - Related implementation: `src/cleveragents/cli/commands/tool.py` lines 240–247 - Analogous working pattern: `SkillConfigSchema.from_yaml()` in the skill CLI - Parent Legendary: #374 Actors, Skills & Tool Execution (Workstream C) - Discovered during UAT testing on 2026-04-02 --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-uat-tester
freemo added this to the v3.2.0 milestone 2026-04-02 19:15:26 +00:00
freemo self-assigned this 2026-04-02 19:25:12 +00:00
Author
Owner

Issue triaged by project owner:

  • State: Verified
  • Priority: High — Command completely fails when using spec-compliant YAML format. Users following the specification cannot register tools.
  • Milestone: v3.2.0 (already assigned)
  • MoSCoW: Must Have — The spec defines tool: wrapper key as the required YAML format. A command that rejects spec-compliant input is a blocking defect. This is functionally identical to #1472 (skill add wrapper key issue) and both must be fixed.
  • Parent Epic: #374

Valid UAT bug with clear root cause: src/cleveragents/cli/commands/tool.py lines 243–247 pass the raw YAML dict directly to Tool.from_config() without unwrapping the tool: key. The fix should mirror the approach used for #1472.


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

Issue triaged by project owner: - **State**: Verified - **Priority**: High — Command completely fails when using spec-compliant YAML format. Users following the specification cannot register tools. - **Milestone**: v3.2.0 (already assigned) - **MoSCoW**: Must Have — The spec defines `tool:` wrapper key as the required YAML format. A command that rejects spec-compliant input is a blocking defect. This is functionally identical to #1472 (skill add wrapper key issue) and both must be fixed. - **Parent Epic**: #374 Valid UAT bug with clear root cause: `src/cleveragents/cli/commands/tool.py` lines 243–247 pass the raw YAML dict directly to `Tool.from_config()` without unwrapping the `tool:` key. The fix should mirror the approach used for #1472. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner
Author
Owner

Closing — work completed in PR #1498 (merged). The PR fixed agents tool add to handle the spec-required tool: wrapper key in YAML config.


Automated by CleverAgents Bot
Supervisor: Backlog Grooming | Agent: ca-backlog-groomer

Closing — work completed in PR #1498 (merged). The PR fixed `agents tool add` to handle the spec-required `tool:` wrapper key in YAML config. --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: ca-backlog-groomer
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Reference
cleveragents/cleveragents-core#1471
No description provided.