diff --git a/CHANGELOG.md b/CHANGELOG.md index 27a30e7a3..aab6227ab 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,7 @@ Changed `wf10_batch.robot` to be less likely to create files, and `plan_generation_graph.robot` to give more test answers. ## [Unreleased] +- **fix(plan): NamespacedName digit-start validation** (#2145, #2147): `NamespacedName` field validators now reject `namespace` and `name` components whose first character is a digit, raising `pydantic.ValidationError` with message `"must start with a letter"`. BDD constructor scenarios updated to use the `"a Pydantic ValidationError should be raised"` step so the assertion correctly matches the exception type raised by Pydantic model construction. - **fix(cli/plan): plan correct JSON output envelope fix and BDD test coverage** (#8584 / PR #8662): Restructured `agents plan correct --format json` output to nest correction fields under `data.correction` (e.g., `data.correction.mode`) and populate the spec-required CLI envelope with `command="plan correct"`, `status`, `exit_code`, `timing`, and `messages` fields. Added three BDD scenarios in `features/tdd_plan_correct_json_output.feature` validating the envelope structure for both revert and append modes. - **fix(cli): add --url flag to resource add for git resource type** (#6322): Added support for the `--url` flag on `agents resource add git` command, allowing users to specify a remote URL for git resources. The flag is validated to only apply to git resource types. Includes Behave BDD tests in `features/resource_cli_git_url_flag.feature` and Robot Framework integration tests verifying correct URL validation and CLI behavior. - **Session create JSON envelope** (#6441): Fixed `agents session create --format json` returning a flat `data` dict instead of the spec-required nested structure with `data.session`, `data.settings`, and `data.actor_details` sub-objects. The `command` field is now populated correctly. Extended JSON envelope coverage to `agents session list`, `show`, `delete --format json`, `export --output-format json`, and `import --format json` so all session commands emit a structured `messages[].text` field (`"0 sessions listed"`, `"Session details loaded"`, `"Session deleted"`, `"Export completed"`, `"Import completed"`). diff --git a/docs/specification.md b/docs/specification.md index 05b65b8a6..cf52c449d 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -132,13 +132,13 @@ The following standards are integrated into the architecture: ???+ abstract "Tools & Skills" Tool - : The ==atomic unit of execution==: a namespaced, independently registered callable operation. Defined by JSON Schema inputs/outputs, capability metadata (`read_only`, `writes`, `checkpointable`), and a four-stage lifecycle (`discover` / `activate` / `execute` / `deactivate`). Sources: MCP servers, Agent Skills folders, built-ins, or custom Python. Namespaced as `[[server:]namespace/]name`. + : The ==atomic unit of execution==: a namespaced, independently registered callable operation. Defined by JSON Schema inputs/outputs, capability metadata (`read_only`, `writes`, `checkpointable`), and a four-stage lifecycle (`discover` / `activate` / `execute` / `deactivate`). Sources: MCP servers, Agent Skills folders, built-ins, or custom Python. Namespaced as `[[server:]namespace/]name`. Note: The namespacing requirement applies only to registered tools. Anonymous tools use a context-local short name without a namespace prefix. Validation : A Tool subtype adding: a `mode` (`required` | `informational`) controlling whether failure blocks execution; a structured JSON return with mandatory `passed` boolean, optional `data`, and optional `message`. ==Always read-only== (`writes = false`, `checkpointable = false`). May wrap an existing Tool via `wraps` + `transform`. Managed via `agents validation add/attach/detach`; always attached to a resource, optionally scoped to a project or plan. Anonymous Tool - : An inline tool definition embedded in a skill YAML or actor graph node. Same schema as a named tool but unregistered, unnamespaced, and scoped only to its defining context. + : An inline tool definition embedded in a skill YAML or actor graph node. Same schema as a named tool but **unregistered** (never passed to `ToolRegistry.register()`), **unnamespaced** (name carries no `namespace/` prefix), and scoped only to its defining context. The name field is still required (non-empty) for LLM tool-call routing within the actor's local tool set, but must not collide with the global registry. Anonymous tools use a context-local short name (e.g., the bare function name or a skill-scoped identifier). Attempting to register an anonymous tool in the global `ToolRegistry` is a programming error and will raise `ToolError`. Skill : A composable, namespaced collection of tools assembled by referencing named tools, defining inline anonymous tools, including other skills, or exposing MCP server tools and Agent Skills ([AgentSkills.io](https://AgentSkills.io)) tools. Actors reference skills by name to acquire capabilities. Namespaced as `[[server:]namespace/]name`. diff --git a/features/plan_namespaced_name_validation.feature b/features/plan_namespaced_name_validation.feature index 8af83ee88..ffd24aa79 100644 --- a/features/plan_namespaced_name_validation.feature +++ b/features/plan_namespaced_name_validation.feature @@ -6,22 +6,22 @@ Feature: NamespacedName validation # TDD for issue #2145/#2147: Names must start with a letter # --------------------------------------------------------------- - @tdd_issue @tdd_issue_2145 @tdd_issue_2147 @tdd_expected_fail + @tdd_issue @tdd_issue_2145 @tdd_issue_2147 Scenario: NamespacedName.parse() rejects namespace starting with a digit When I parse the namespaced name "123abc/my-action" expecting an error Then a ValueError should be raised And the error message should contain "must start with a letter" - @tdd_issue @tdd_issue_2145 @tdd_issue_2147 @tdd_expected_fail + @tdd_issue @tdd_issue_2145 @tdd_issue_2147 Scenario: NamespacedName constructor rejects name starting with a digit When I construct a NamespacedName with namespace "local" and name "123-action" expecting an error - Then a ValidationError should be raised + Then a Pydantic ValidationError should be raised And the error message should contain "must start with a letter" - @tdd_issue @tdd_issue_2145 @tdd_issue_2147 @tdd_expected_fail + @tdd_issue @tdd_issue_2145 @tdd_issue_2147 Scenario: NamespacedName constructor rejects namespace starting with a digit When I construct a NamespacedName with namespace "999org" and name "valid-name" expecting an error - Then a ValidationError should be raised + Then a Pydantic ValidationError should be raised And the error message should contain "must start with a letter" # --------------------------------------------------------------- diff --git a/src/cleveragents/domain/models/core/plan.py b/src/cleveragents/domain/models/core/plan.py index bcda823a0..6f31d41e1 100644 --- a/src/cleveragents/domain/models/core/plan.py +++ b/src/cleveragents/domain/models/core/plan.py @@ -231,6 +231,9 @@ class NamespacedName(BaseModel): # Namespace should be lowercase alphanumeric with hyphens if not all(c.isalnum() or c == "-" for c in v): raise ValueError("Namespace must be alphanumeric with hyphens only") + # Namespace must start with a letter, not a digit + if v[0].isdigit(): + raise ValueError(f"Namespace {v!r} must start with a letter, not a digit") return v.lower() @field_validator("name") @@ -239,6 +242,9 @@ class NamespacedName(BaseModel): """Validate name format (kebab-case recommended).""" if not v.replace("-", "").replace("_", "").isalnum(): raise ValueError("Name must be alphanumeric with hyphens or underscores") + # Name must start with a letter, not a digit + if v[0].isdigit(): + raise ValueError(f"Name {v!r} must start with a letter, not a digit") return v.lower() @classmethod