cleveragents/cleveragents-core

Fork 3

UAT: `Tool` name validator rejects spec-required server-qualified names — `[[server:]namespace/]name` format not supported #2949

New issue

Open

opened 2026-04-05 02:54:40 +00:00 by freemo · 1 comment

freemo commented

2026-04-05 02:54:40 +00:00

Owner

Metadata

Branch: fix/tool-name-pattern-server-qualified
Commit Message: fix(domain): support server-qualified tool names in _TOOL_NAME_PATTERN
Milestone: v3.7.0
Parent Epic: #392

Bug Report

What Was Tested

The Tool domain model's name validation in src/cleveragents/domain/models/core/tool.py.

Expected Behavior (from spec)

The specification (Glossary, §Tools & Skills) states:

Tool: The atomic unit of execution: a namespaced, independently registered callable operation. [...] Namespaced as [[server:]namespace/]name.

The spec also explicitly states (§Tool Configuration Files, line 21194):

Tools follow the same <namespace>/<name> naming convention as actors, skills, and other entities (e.g., local/run-migrations, cleverthis/validate-api, local/create-subplan). They support optional server-qualified prefixes for multi-server disambiguation (e.g., dev:freemo/custom-analysis).

So tool names like dev:freemo/custom-analysis and prod:cleverthis/deploy-action must be accepted.

Actual Behavior (from code analysis)

The _TOOL_NAME_PATTERN regex in src/cleveragents/domain/models/core/tool.py (line 12) is:

_TOOL_NAME_PATTERN = re.compile(r"^[a-zA-Z0-9_-]+/[a-zA-Z0-9_-]+$")

This only accepts namespace/name (two-part format). It rejects any server-qualified name containing a colon (e.g., dev:freemo/custom-analysis).

The validate_name_format field validator (line ~200) uses this pattern and raises a ValueError for any server-qualified name.

Steps to Reproduce

from cleveragents.domain.models.core.tool import Tool, ToolSource

# This should work per spec but raises ValueError:
tool = Tool(
    name="dev:freemo/custom-analysis",
    description="Custom analysis tool",
    source=ToolSource.BUILTIN,
)
# ValidationError: Tool name must match 'namespace/name' pattern

Code Location

src/cleveragents/domain/models/core/tool.py, line 12: _TOOL_NAME_PATTERN
src/cleveragents/domain/models/core/tool.py, validate_name_format method

Severity

High — prevents multi-server tool registration which is a core spec requirement.

Subtasks

Update _TOOL_NAME_PATTERN in src/cleveragents/domain/models/core/tool.py to accept the full [[server:]namespace/]name format:

_TOOL_NAME_PATTERN = re.compile(
    r"^(?:[a-zA-Z][a-zA-Z0-9_-]*:)?[a-zA-Z][a-zA-Z0-9_-]*/[a-zA-Z][a-zA-Z0-9_-]*$"
)

Update the namespace property to correctly strip the server prefix when parsing server-qualified names (e.g., dev:freemo/custom-analysis → namespace freemo)
Update the short_name property to correctly extract the name component from server-qualified names
Add a server property (or equivalent) to expose the optional server prefix component
Add Behave scenarios covering acceptance of server-qualified tool names (e.g., dev:freemo/custom-analysis, prod:cleverthis/deploy-action)
Add Behave scenarios confirming two-part names (namespace/name) still accepted
Add Behave scenarios confirming invalid formats are still rejected
Run nox -e typecheck to confirm no type regressions
Run nox (all default sessions), fix any errors

Definition of Done

_TOOL_NAME_PATTERN accepts dev:freemo/custom-analysis and prod:cleverthis/deploy-action
_TOOL_NAME_PATTERN continues to accept local/run-migrations and cleverthis/validate-api
_TOOL_NAME_PATTERN rejects malformed names (e.g., bare name, ns/, /name, a:b:c/name)
namespace and short_name properties correctly parse all three-part server-qualified names
Behave scenarios added and passing for all new acceptance and rejection cases
Commit created with message: fix(domain): support server-qualified tool names in _TOOL_NAME_PATTERN
Code pushed to branch fix/tool-name-pattern-server-qualified and PR merged
All nox stages pass
Coverage >= 97%

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

## Metadata - **Branch**: `fix/tool-name-pattern-server-qualified` - **Commit Message**: `fix(domain): support server-qualified tool names in _TOOL_NAME_PATTERN` - **Milestone**: v3.7.0 - **Parent Epic**: #392 ## Bug Report ### What Was Tested The `Tool` domain model's name validation in `src/cleveragents/domain/models/core/tool.py`. ### Expected Behavior (from spec) The specification (Glossary, §Tools & Skills) states: > Tool: The atomic unit of execution: a namespaced, independently registered callable operation. [...] Namespaced as `[[server:]namespace/]name`. The spec also explicitly states (§Tool Configuration Files, line 21194): > Tools follow the same `<namespace>/<name>` naming convention as actors, skills, and other entities (e.g., `local/run-migrations`, `cleverthis/validate-api`, `local/create-subplan`). They support optional server-qualified prefixes for multi-server disambiguation (e.g., `dev:freemo/custom-analysis`). So tool names like `dev:freemo/custom-analysis` and `prod:cleverthis/deploy-action` must be accepted. ### Actual Behavior (from code analysis) The `_TOOL_NAME_PATTERN` regex in `src/cleveragents/domain/models/core/tool.py` (line 12) is: ```python _TOOL_NAME_PATTERN = re.compile(r"^[a-zA-Z0-9_-]+/[a-zA-Z0-9_-]+$") ``` This only accepts `namespace/name` (two-part format). It rejects any server-qualified name containing a colon (e.g., `dev:freemo/custom-analysis`). The `validate_name_format` field validator (line ~200) uses this pattern and raises a `ValueError` for any server-qualified name. ### Steps to Reproduce ```python from cleveragents.domain.models.core.tool import Tool, ToolSource # This should work per spec but raises ValueError: tool = Tool( name="dev:freemo/custom-analysis", description="Custom analysis tool", source=ToolSource.BUILTIN, ) # ValidationError: Tool name must match 'namespace/name' pattern ``` ### Code Location - `src/cleveragents/domain/models/core/tool.py`, line 12: `_TOOL_NAME_PATTERN` - `src/cleveragents/domain/models/core/tool.py`, `validate_name_format` method ### Severity High — prevents multi-server tool registration which is a core spec requirement. ## Subtasks - [ ] Update `_TOOL_NAME_PATTERN` in `src/cleveragents/domain/models/core/tool.py` to accept the full `[[server:]namespace/]name` format: ```python _TOOL_NAME_PATTERN = re.compile( r"^(?:[a-zA-Z][a-zA-Z0-9_-]*:)?[a-zA-Z][a-zA-Z0-9_-]*/[a-zA-Z][a-zA-Z0-9_-]*$" ) ``` - [ ] Update the `namespace` property to correctly strip the server prefix when parsing server-qualified names (e.g., `dev:freemo/custom-analysis` → namespace `freemo`) - [ ] Update the `short_name` property to correctly extract the name component from server-qualified names - [ ] Add a `server` property (or equivalent) to expose the optional server prefix component - [ ] Add Behave scenarios covering acceptance of server-qualified tool names (e.g., `dev:freemo/custom-analysis`, `prod:cleverthis/deploy-action`) - [ ] Add Behave scenarios confirming two-part names (`namespace/name`) still accepted - [ ] Add Behave scenarios confirming invalid formats are still rejected - [ ] Run `nox -e typecheck` to confirm no type regressions - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done - [ ] `_TOOL_NAME_PATTERN` accepts `dev:freemo/custom-analysis` and `prod:cleverthis/deploy-action` - [ ] `_TOOL_NAME_PATTERN` continues to accept `local/run-migrations` and `cleverthis/validate-api` - [ ] `_TOOL_NAME_PATTERN` rejects malformed names (e.g., bare `name`, `ns/`, `/name`, `a:b:c/name`) - [ ] `namespace` and `short_name` properties correctly parse all three-part server-qualified names - [ ] Behave scenarios added and passing for all new acceptance and rejection cases - [ ] Commit created with message: `fix(domain): support server-qualified tool names in _TOOL_NAME_PATTERN` - [ ] Code pushed to branch `fix/tool-name-pattern-server-qualified` and PR merged - [ ] 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-05 02:54:44 +00:00

freemo added a new dependency

2026-04-05 02:55:00 +00:00

#392 Epic: Actor YAML & Compiler

freemo commented

2026-04-05 03:01:12 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Confirmed
MoSCoW: Should Have

Valid finding verified during batch triage.

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

Issue triaged by project owner: - **State**: Verified - **Priority**: Confirmed - **MoSCoW**: Should Have Valid finding verified during batch triage. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo referenced this issue

2026-04-05 03:36:04 +00:00

[CA-AUTO] UAT Worker — Tools & Tool Registry — Session Tracker #3008

freemo referenced this issue

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

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

freemo referenced this issue

2026-04-05 09:04:55 +00:00

[CA-AUTO] UAT Worker — Tools & Tool Registry — Session Tracker #3008