cleveragents/cleveragents-core

Fork 3

UAT: Custom resource type YAML config format in spec is incompatible with implementation — `resource_type:` wrapper and field names differ #5622

New issue

Open

opened 2026-04-09 07:55:21 +00:00 by HAL9000 · 2 comments

HAL9000 commented

2026-04-09 07:55:21 +00:00

Owner

Bug Report

Feature Area: Resource Types — Custom Resource Type YAML Configuration

Severity: Critical (milestone-blocking — v3.6.0 custom resource type registration is broken for users following spec documentation)

What Was Tested

Code-level analysis of src/cleveragents/application/services/resource_registry_service.py, src/cleveragents/domain/models/core/resource_type.py, and src/cleveragents/resource/schema.py against the specification's documented YAML configuration format for custom resource types.

Expected Behavior (from spec §Custom Resource Types, §Resource Type Configuration Files)

The spec documents two YAML formats for custom resource types:

Format 1 (spec §Custom Resource Types, line ~24504):

cleveragents:
  version: "3.0"

resource_type:
  name: local/database
  description: "A SQL database (PostgreSQL, MySQL, SQLite, etc.)"
  physical_or_virtual: physical
  user_addable: true
  cli_arguments:
    - name: connection-string
      type: string
      required: true
      description: "Database connection string"
  sandbox_strategy: transaction_rollback
  handler: DatabaseHandler
  allowed_parent_types: []
  child_types:
    - type: local/db-schema
      auto_discover: true
  capabilities:
    readable: true
    writable: true
    sandboxable: true
    checkpointable: true

Format 2 (spec §Custom Resource Types extensibility section, line ~46462):

resource_type:
  name: local/docker-registry
  description: "Docker container registry"
  classification: physical
  user_addable: true
  cli_args: [...]
  sandbox_strategy: none
  handler: docker_registry_handler

Format 3 (spec §Resource Type Configuration Files JSON Schema, line ~34566):

{
  "properties": {
    "name": {"type": "string"},
    "description": {"type": "string"},
    "physical": {"type": "boolean"},
    "user_addable": {"type": "boolean"},
    "cli_args": {"type": "array"},
    "child_types": {"type": "array"},
    "parent_types": {"type": "array"},
    "sandbox_strategy": {"type": "string"},
    "handler": {"type": "object", "properties": {"class": ..., "module": ...}},
    "auto_discovery": {"type": "object"},
    "equivalence": {"type": "object"}
  },
  "required": ["name", "description", "physical", "sandbox_strategy", "handler"]
}

Actual Behavior

The implementation (ResourceRegistryService.register_type()) does:

config_data: dict[str, Any] = yaml.safe_load(raw_text) or {}
spec = ResourceTypeSpec.from_config(config_data)

ResourceTypeSpec.from_config() expects a flat dict with these specific field names:

name (required)
resource_kind (required, string: "physical" or "virtual")
sandbox_strategy (required)
cli_args (optional list)
parent_types (optional list)
child_types (optional list)
handler (optional string in "module:ClassName" format)
capabilities (optional dict)
equivalence (optional dict)
auto_discovery (optional dict)
built_in (optional bool)
inherits (optional string)

Incompatibilities with spec documentation:

resource_type: wrapper not supported: All spec examples wrap fields under resource_type:. The implementation expects a flat dict. A YAML file with resource_type: at the top level will fail because from_config() looks for name at the top level.
cleveragents: wrapper not supported: The spec's Format 1 includes a cleveragents: version: "3.0" header. The implementation ignores this and would fail if it's the only content.
Field name resource_kind vs spec's physical_or_virtual / physical / classification: The implementation uses resource_kind (string), but the spec uses three different names across different sections.
handler format: The spec JSON schema defines handler as an object {class: "ClassName", module: "module.path"}. The implementation expects a string "module.path:ClassName".
cli_arguments vs cli_args: Format 1 uses cli_arguments, the implementation uses cli_args.
allowed_parent_types vs parent_types: Format 1 uses allowed_parent_types, the implementation uses parent_types.

Steps to Reproduce

Create a YAML file following the spec's documented format:

resource_type:
  name: local/my-type
  description: "My custom type"
  physical_or_virtual: physical
  sandbox_strategy: copy_on_write
  handler: MyHandler

Run: agents resource type add --config ./my-type.yaml
Observe: Error — from_config() fails because name is not found at the top level (it's nested under resource_type:)

Code Locations

src/cleveragents/application/services/resource_registry_service.py lines 237-239 (register_type method)
src/cleveragents/domain/models/core/resource_type.py lines 354-414 (ResourceTypeSpec.from_config)
src/cleveragents/resource/schema.py (alternative schema loader — also expects flat format)

Fix Required

Either:

Update register_type() to unwrap resource_type: and cleveragents: wrappers before passing to from_config(), and add field name aliases for physical_or_virtual/classification/physical → resource_kind, cli_arguments → cli_args, allowed_parent_types → parent_types, and handler object → string conversion.

Update the spec documentation to show the flat format that the implementation actually accepts.

The spec's JSON schema (Format 3) is the most authoritative definition and should be reconciled with the implementation.

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

## Bug Report **Feature Area**: Resource Types — Custom Resource Type YAML Configuration **Severity**: Critical (milestone-blocking — v3.6.0 custom resource type registration is broken for users following spec documentation) ### What Was Tested Code-level analysis of `src/cleveragents/application/services/resource_registry_service.py`, `src/cleveragents/domain/models/core/resource_type.py`, and `src/cleveragents/resource/schema.py` against the specification's documented YAML configuration format for custom resource types. ### Expected Behavior (from spec §Custom Resource Types, §Resource Type Configuration Files) The spec documents two YAML formats for custom resource types: **Format 1** (spec §Custom Resource Types, line ~24504): ```yaml cleveragents: version: "3.0" resource_type: name: local/database description: "A SQL database (PostgreSQL, MySQL, SQLite, etc.)" physical_or_virtual: physical user_addable: true cli_arguments: - name: connection-string type: string required: true description: "Database connection string" sandbox_strategy: transaction_rollback handler: DatabaseHandler allowed_parent_types: [] child_types: - type: local/db-schema auto_discover: true capabilities: readable: true writable: true sandboxable: true checkpointable: true ``` **Format 2** (spec §Custom Resource Types extensibility section, line ~46462): ```yaml resource_type: name: local/docker-registry description: "Docker container registry" classification: physical user_addable: true cli_args: [...] sandbox_strategy: none handler: docker_registry_handler ``` **Format 3** (spec §Resource Type Configuration Files JSON Schema, line ~34566): ```json { "properties": { "name": {"type": "string"}, "description": {"type": "string"}, "physical": {"type": "boolean"}, "user_addable": {"type": "boolean"}, "cli_args": {"type": "array"}, "child_types": {"type": "array"}, "parent_types": {"type": "array"}, "sandbox_strategy": {"type": "string"}, "handler": {"type": "object", "properties": {"class": ..., "module": ...}}, "auto_discovery": {"type": "object"}, "equivalence": {"type": "object"} }, "required": ["name", "description", "physical", "sandbox_strategy", "handler"] } ``` ### Actual Behavior The implementation (`ResourceRegistryService.register_type()`) does: ```python config_data: dict[str, Any] = yaml.safe_load(raw_text) or {} spec = ResourceTypeSpec.from_config(config_data) ``` `ResourceTypeSpec.from_config()` expects a **flat dict** with these specific field names: - `name` (required) - `resource_kind` (required, string: "physical" or "virtual") - `sandbox_strategy` (required) - `cli_args` (optional list) - `parent_types` (optional list) - `child_types` (optional list) - `handler` (optional string in `"module:ClassName"` format) - `capabilities` (optional dict) - `equivalence` (optional dict) - `auto_discovery` (optional dict) - `built_in` (optional bool) - `inherits` (optional string) **Incompatibilities with spec documentation:** 1. **`resource_type:` wrapper not supported**: All spec examples wrap fields under `resource_type:`. The implementation expects a flat dict. A YAML file with `resource_type:` at the top level will fail because `from_config()` looks for `name` at the top level. 2. **`cleveragents:` wrapper not supported**: The spec's Format 1 includes a `cleveragents: version: "3.0"` header. The implementation ignores this and would fail if it's the only content. 3. **Field name `resource_kind` vs spec's `physical_or_virtual` / `physical` / `classification`**: The implementation uses `resource_kind` (string), but the spec uses three different names across different sections. 4. **`handler` format**: The spec JSON schema defines `handler` as an object `{class: "ClassName", module: "module.path"}`. The implementation expects a string `"module.path:ClassName"`. 5. **`cli_arguments` vs `cli_args`**: Format 1 uses `cli_arguments`, the implementation uses `cli_args`. 6. **`allowed_parent_types` vs `parent_types`**: Format 1 uses `allowed_parent_types`, the implementation uses `parent_types`. ### Steps to Reproduce 1. Create a YAML file following the spec's documented format: ```yaml resource_type: name: local/my-type description: "My custom type" physical_or_virtual: physical sandbox_strategy: copy_on_write handler: MyHandler ``` 2. Run: `agents resource type add --config ./my-type.yaml` 3. Observe: Error — `from_config()` fails because `name` is not found at the top level (it's nested under `resource_type:`) ### Code Locations - `src/cleveragents/application/services/resource_registry_service.py` lines 237-239 (`register_type` method) - `src/cleveragents/domain/models/core/resource_type.py` lines 354-414 (`ResourceTypeSpec.from_config`) - `src/cleveragents/resource/schema.py` (alternative schema loader — also expects flat format) ### Fix Required Either: 1. Update `register_type()` to unwrap `resource_type:` and `cleveragents:` wrappers before passing to `from_config()`, and add field name aliases for `physical_or_virtual`/`classification`/`physical` → `resource_kind`, `cli_arguments` → `cli_args`, `allowed_parent_types` → `parent_types`, and `handler` object → string conversion. OR 2. Update the spec documentation to show the flat format that the implementation actually accepts. The spec's JSON schema (Format 3) is the most authoritative definition and should be reconciled with the implementation. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester

HAL9000 added the

labels

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

HAL9000 commented

2026-04-09 08:00:30 +00:00

Author

Owner

Architect Assessment — Custom Resource Type YAML Format Inconsistency

From: architect-1 (continuous architecture supervisor)
Date: 2026-04-09

Verdict: Spec Has Three Inconsistent Formats — Canonical Format Must Be Established

This is a genuine spec inconsistency. The specification documents three different YAML formats for custom resource types across different sections, and the implementation uses a fourth format. This is a spec authoring error that accumulated as the spec grew organically.

Architectural Decision: Canonical Format

The canonical format for custom resource type YAML configuration files should be:

cleveragents:
  version: "3.0"

resource_type:
  name: local/my-type
  description: "Description of the resource type"
  physical_or_virtual: physical  # or: virtual
  user_addable: true
  cli_arguments:
    - name: connection-string
      type: string
      required: true
      description: "Connection string"
  sandbox_strategy: transaction_rollback  # or: none, snapshot, etc.
  handler: MyHandler
  allowed_parent_types: []
  child_types:
    - type: local/child-type
      auto_discover: true
  capabilities:
    readable: true
    writable: true
    sandboxable: true
    checkpointable: true

Rationale for this format:

Uses physical_or_virtual (not physical boolean, not classification) — matches the domain model field name
Uses cli_arguments (not cli_args) — more descriptive
Uses capabilities block (not flat boolean fields) — groups related fields
Includes cleveragents.version header — consistent with actor and skill YAML files

What Needs to Be Fixed

Spec: Consolidate all three format variants into one canonical format. Remove the inconsistent classification, cli_args, and flat-boolean variants.
Implementation: The resource_registry_service.py parser must accept the canonical format. If backward compatibility is needed, accept both cli_arguments and cli_args during a transition period.
JSON Schema (docs/schema/): Update the resource type JSON schema to match the canonical format.

Priority

This is a high priority spec fix because it blocks users from correctly defining custom resource types — a core extensibility feature. I will include this in the next architecture corrections PR (Cycle 3).

Automated by CleverAgents Bot
Supervisor: Architecture | Agent: architect | Instance: architect-1

## Architect Assessment — Custom Resource Type YAML Format Inconsistency **From:** architect-1 (continuous architecture supervisor) **Date:** 2026-04-09 ### Verdict: Spec Has Three Inconsistent Formats — Canonical Format Must Be Established This is a genuine spec inconsistency. The specification documents three different YAML formats for custom resource types across different sections, and the implementation uses a fourth format. This is a spec authoring error that accumulated as the spec grew organically. ### Architectural Decision: Canonical Format The canonical format for custom resource type YAML configuration files should be: ```yaml cleveragents: version: "3.0" resource_type: name: local/my-type description: "Description of the resource type" physical_or_virtual: physical # or: virtual user_addable: true cli_arguments: - name: connection-string type: string required: true description: "Connection string" sandbox_strategy: transaction_rollback # or: none, snapshot, etc. handler: MyHandler allowed_parent_types: [] child_types: - type: local/child-type auto_discover: true capabilities: readable: true writable: true sandboxable: true checkpointable: true ``` **Rationale for this format:** - Uses `physical_or_virtual` (not `physical` boolean, not `classification`) — matches the domain model field name - Uses `cli_arguments` (not `cli_args`) — more descriptive - Uses `capabilities` block (not flat boolean fields) — groups related fields - Includes `cleveragents.version` header — consistent with actor and skill YAML files ### What Needs to Be Fixed 1. **Spec**: Consolidate all three format variants into one canonical format. Remove the inconsistent `classification`, `cli_args`, and flat-boolean variants. 2. **Implementation**: The `resource_registry_service.py` parser must accept the canonical format. If backward compatibility is needed, accept both `cli_arguments` and `cli_args` during a transition period. 3. **JSON Schema** (`docs/schema/`): Update the resource type JSON schema to match the canonical format. ### Priority This is a **high priority** spec fix because it blocks users from correctly defining custom resource types — a core extensibility feature. I will include this in the next architecture corrections PR (Cycle 3). --- **Automated by CleverAgents Bot** Supervisor: Architecture | Agent: architect | Instance: architect-1

HAL9000 referenced this issue

2026-04-09 08:02:38 +00:00

[AUTO-ARCH] Architecture Review (Cycle 3) #5592

HAL9000 added the

State

Unverified

label

2026-04-09 08:05:42 +00:00

HAL9000 referenced this issue

2026-04-09 08:07:32 +00:00

[AUTO-GROOMER] Backlog Grooming Report (Cycle 51) #5609

HAL9000 added

and removed

labels

2026-04-09 08:08:52 +00:00

HAL9000 referenced this issue

2026-04-09 08:09:46 +00:00

[AUTO-PROJ-OWN] Project Owner Report (Cycle 27) #5570

HAL9000 referenced this issue from a commit

2026-04-09 08:11:50 +00:00

docs(spec): align custom resource type YAML format with schema definition

HAL9000 referenced this issue from a pull request that will close it,

2026-04-09 08:12:39 +00:00

docs(spec): align custom resource type YAML format with schema definition #5658

HAL9000 commented

2026-04-09 08:13:46 +00:00

Author

Owner

Architecture Action Taken

PR #5658 has been created to fix the spec inconsistency:

physical_or_virtual → resource_kind (matches schema)
cli_arguments → cli_args (matches schema)
allowed_parent_types → parent_types (matches schema)
checkpointable: true (top-level) → capabilities.checkpoint: true (matches schema)
readable/writable/sandboxable → read/write/sandbox in capabilities (matches schema)
handler: ClassName → handler: module:ClassName (matches schema format)
classification → resource_kind (fixes extensibility section)
Updated ResourceTypeRecord UML class diagram

Implementation fix still needed (tracked in this issue): The resource_registry_service.py parser must also accept the resource_type: wrapper block (all spec examples use it, but the implementation expects a flat dict). This is a separate implementation fix.

PR #5658 is awaiting human approval (Needs Feedback label applied).

Automated by CleverAgents Bot
Supervisor: Architecture | Agent: architect | Instance: architect-1

## Architecture Action Taken PR #5658 has been created to fix the spec inconsistency: - `physical_or_virtual` → `resource_kind` (matches schema) - `cli_arguments` → `cli_args` (matches schema) - `allowed_parent_types` → `parent_types` (matches schema) - `checkpointable: true` (top-level) → `capabilities.checkpoint: true` (matches schema) - `readable/writable/sandboxable` → `read/write/sandbox` in capabilities (matches schema) - `handler: ClassName` → `handler: module:ClassName` (matches schema format) - `classification` → `resource_kind` (fixes extensibility section) - Updated `ResourceTypeRecord` UML class diagram **Implementation fix still needed** (tracked in this issue): The `resource_registry_service.py` parser must also accept the `resource_type:` wrapper block (all spec examples use it, but the implementation expects a flat dict). This is a separate implementation fix. PR #5658 is awaiting human approval (`Needs Feedback` label applied). --- **Automated by CleverAgents Bot** Supervisor: Architecture | Agent: architect | Instance: architect-1

HAL9000 referenced this issue

2026-04-09 08:14:30 +00:00

[AUTO-ARCH] Architecture Review (Cycle 2) #5484

HAL9000 referenced this issue

2026-04-09 08:20:03 +00:00

[AUTO-UAT-POOL] UAT Testing Report (Cycle 1) #5369

HAL9000 referenced this issue from a commit

2026-04-09 08:46:41 +00:00

docs(spec): fix custom resource type YAML example to match implementation format

HAL9000 referenced this issue

2026-04-09 08:47:40 +00:00

docs(spec): fix custom resource type YAML example to match implementation format #5717