cleveragents/cleveragents-core
4
0
Fork 3
Code Issues 6.0k Pull Requests 115 Actions Packages Projects Releases Wiki Activity

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

Merged
HAL9000 merged 2 commits from spec/resource-type-yaml-format-canonical-5622 into master 2026-06-19 06:04:42 +00:00
Conversation 24 Commits 2 Files Changed 2
+38 -30
2 changed files with 38 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CHANGELOG.md
+8 -1
View File
@@ -1227,6 +1227,13 @@ Documentation Report (Cycle N)` issues every 10 cycles (~3.3 hours). The manager
### Fixed
- **Custom resource type YAML format** (#5622): Corrected three inconsistent YAML format
examples in `docs/specification.md` to match the canonical format defined in
`docs/schema/resource_type.schema.yaml`. Field names updated: `resource_kind`,
`cli_args`, `parent_types`, `capabilities.read/write/sandbox/checkpoint`,
`handler: module:ClassName`, and `child_types` as flat string list. Added documentation
explaining per-child-type auto-discovery configuration in the `auto_discovery` block.
- **Plan Concurrency Race Condition** (#7989): Fixed critical race condition in `execute_plan()` and
`apply_plan()` where concurrent CLI/worker sessions could simultaneously modify the same plan,
corrupting plan state. `LockService` is now wired into the plan lifecycle with plan-level advisory
@@ -1399,4 +1406,4 @@ iteration` and data corruption under concurrent plan execution. All public
- **TUI -- Permission Question Widget**: A new inline `PermissionQuestionWidget`
renders permission requests directly in the conversation stream for single-key
operations. Users can allow/reject with single-key shortcuts (`a`/`A`/`r`/`R`),
navigate with arrow keys, confirm with `Enter`, or press `v` to open the full
navigate with arrow keys, confirm with `Enter`, or press `v` to open the full
docs/specification.md
+30 -29
View File
@@ -24676,17 +24676,16 @@ Custom resource types are defined in YAML configuration files and registered via
<span style="color: cyan; font-weight: 600;">resource_type</span>:
<span style="color: cyan; font-weight: 600;">name</span>: local/database
<span style="color: cyan; font-weight: 600;">description</span>: <span style="color: #66cc66;">&quot;A SQL database (PostgreSQL, MySQL, SQLite, etc.)&quot;</span>
<span style="color: cyan; font-weight: 600;">physical_or_virtual</span>: physical
<span style="color: cyan; font-weight: 600;">resource_kind</span>: physical
<span style="color: cyan; font-weight: 600;">user_addable</span>: <span style="color: magenta; font-weight: 600;">true</span>
<span style="opacity: 0.7;"> # CLI arguments for `agents resource add local/database`</span>
<span style="color: cyan; font-weight: 600;">cli_arguments</span>:
<span style="color: cyan; font-weight: 600;">cli_args</span>:
- <span style="color: cyan;">name</span>: connection-string
<span style="color: cyan; font-weight: 600;">type</span>: string
<span style="color: cyan; font-weight: 600;">required</span>: <span style="color: magenta; font-weight: 600;">true</span>
<span style="color: cyan; font-weight: 600;">description</span>: <span style="color: #66cc66;">&quot;Database connection string (e.g., postgresql://host/dbname)&quot;</span>
<span style="color: cyan; font-weight: 600;">validation</span>:
<span style="color: cyan; font-weight: 600;">pattern</span>: <span style="color: #66cc66;">&quot;^(postgresql|mysql|sqlite)://&quot;</span>
<span style="color: cyan; font-weight: 600;">validation_pattern</span>: <span style="color: #66cc66;">&quot;^(postgresql|mysql|sqlite)://&quot;</span>
- <span style="color: cyan;">name</span>: schema
<span style="color: cyan; font-weight: 600;">type</span>: string
<span style="color: cyan; font-weight: 600;">required</span>: <span style="color: magenta; font-weight: 600;">false</span>
@@ -24699,31 +24698,33 @@ Custom resource types are defined in YAML configuration files and registered via
<span style="opacity: 0.7;"> # Sandbox and handler</span>
<span style="color: cyan; font-weight: 600;">sandbox_strategy</span>: transaction_rollback
<span style="color: cyan; font-weight: 600;">handler</span>: DatabaseHandler
<span style="color: cyan; font-weight: 600;">checkpointable</span>: <span style="color: magenta; font-weight: 600;">true</span>
<span style="color: cyan; font-weight: 600;">handler</span>: myorg.handlers:DatabaseHandler
<span style="opacity: 0.7;"> # Allowed parent types (empty means can be top-level)</span>
<span style="color: cyan; font-weight: 600;">allowed_parent_types</span>: []
<span style="color: cyan; font-weight: 600;">parent_types</span>: []
<span style="opacity: 0.7;"> # Child types</span>
<span style="color: cyan; font-weight: 600;">child_types</span>:
- <span style="color: cyan;">type</span>: local/db-schema
<span style="color: cyan; font-weight: 600;">auto_discover</span>: <span style="color: magenta; font-weight: 600;">true</span>
<span style="color: cyan; font-weight: 600;">manual_link</span>: <span style="color: magenta; font-weight: 600;">false</span>
<span style="color: cyan; font-weight: 600;">description</span>: <span style="color: #66cc66;">&quot;Discovered database schemas&quot;</span>
- <span style="color: cyan;">type</span>: local/db-table
<span style="color: cyan; font-weight: 600;">auto_discover</span>: <span style="color: magenta; font-weight: 600;">true</span>
<span style="color: cyan; font-weight: 600;">manual_link</span>: <span style="color: magenta; font-weight: 600;">false</span>
<span style="color: cyan; font-weight: 600;">description</span>: <span style="color: #66cc66;">&quot;Discovered tables within schemas&quot;</span>
- local/db-schema
- local/db-table
<span style="opacity: 0.7;"> # Per-child-type discovery configuration lives in `auto_discovery`</span>
<span style="color: cyan; font-weight: 600;">auto_discovery</span>:
<span style="color: cyan; font-weight: 600;">enabled</span>: <span style="color: magenta; font-weight: 600;">true</span>
<span style="color: cyan; font-weight: 600;">strategy</span>: schema_scan
<span style="color: cyan; font-weight: 600;">manual_link</span>: <span style="color: magenta; font-weight: 600;">false</span>
<span style="color: cyan; font-weight: 600;">description</span>: <span style="color: #66cc66;">&quot;Automatically discover schemas and tables for child resources&quot;</span>
<span style="opacity: 0.7;"> # Capabilities</span>
<span style="color: cyan; font-weight: 600;">capabilities</span>:
<span style="color: cyan; font-weight: 600;">readable</span>: <span style="color: magenta; font-weight: 600;">true</span>
<span style="color: cyan; font-weight: 600;">writable</span>: <span style="color: magenta; font-weight: 600;">true</span>
<span style="color: cyan; font-weight: 600;">sandboxable</span>: <span style="color: magenta; font-weight: 600;">true</span>
<span style="color: cyan; font-weight: 600;">checkpointable</span>: <span style="color: magenta; font-weight: 600;">true</span>
<span style="color: cyan; font-weight: 600;">read</span>: <span style="color: magenta; font-weight: 600;">true</span>
<span style="color: cyan; font-weight: 600;">write</span>: <span style="color: magenta; font-weight: 600;">true</span>
<span style="color: cyan; font-weight: 600;">sandbox</span>: <span style="color: magenta; font-weight: 600;">true</span>
<span style="color: cyan; font-weight: 600;">checkpoint</span>: <span style="color: magenta; font-weight: 600;">true</span>
</code></pre></div>
The `auto_discovery` block replaces the former per-child `auto_discover` / `manual_link` YAML objects. Handlers expose their discovery knobs there while `child_types` remains a flat list of allowed resource type names.
When this type is registered:
<div class="highlight"><pre><code>
agents resource type add <span style="color: cyan;">--config</span> ./resource-types/database.yaml
@@ -25210,11 +25211,11 @@ class ResourceTypeRecord {
+ name : String
+ description : String
+ source : String
+ physical_or_virtual : PhysVirt
+ resource_kind : PhysVirt
+ user_addable : Boolean
+ cli_arguments : List<CLIArgument>
+ allowed_parent_types : List<String>
+ child_types : Map<String, ChildTypeConfig>
+ cli_args : List<CLIArgument>
+ parent_types : List<String>
+ child_types : List<String>
+ sandbox_strategy : String
+ handler : String
+ capabilities : Capabilities
@@ -46864,11 +46865,11 @@ New resource types extend CleverAgents to manage any kind of resource:
<span style="color: cyan; font-weight: 600;">resource_type</span>:
<span style="color: cyan; font-weight: 600;">name</span>: <span style="color: #66cc66;">local/docker-registry</span>
<span style="color: cyan; font-weight: 600;">description</span>: <span style="color: #66cc66;">"Docker container registry"</span>
<span style="color: cyan; font-weight: 600;">classification</span>: <span style="color: #66cc66;">physical</span>
<span style="color: cyan; font-weight: 600;">resource_kind</span>: <span style="color: #66cc66;">physical</span>
<span style="color: cyan; font-weight: 600;">user_addable</span>: <span style="color: #66cc66;">true</span>
<span style="color: cyan; font-weight: 600;">cli_args</span>:
- <span style="color: cyan; font-weight: 600;">name</span>: <span style="color: #66cc66;">registry_url</span>
- <span style="color: cyan; font-weight: 600;">name</span>: <span style="color: #66cc66;">registry-url</span>
<span style="color: cyan; font-weight: 600;">type</span>: <span style="color: #66cc66;">string</span>
<span style="color: cyan; font-weight: 600;">required</span>: <span style="color: #66cc66;">true</span>
- <span style="color: cyan; font-weight: 600;">name</span>: <span style="color: #66cc66;">repository</span>
@@ -46879,16 +46880,16 @@ New resource types extend CleverAgents to manage any kind of resource:
<span style="color: cyan; font-weight: 600;">default</span>: <span style="color: #66cc66;">"latest"</span>
<span style="color: cyan; font-weight: 600;">sandbox_strategy</span>: <span style="color: #66cc66;">none</span> <span style="color: #888;"># Docker images are immutable</span>
<span style="color: cyan; font-weight: 600;">handler</span>: <span style="color: #66cc66;">docker_registry_handler</span>
<span style="color: cyan; font-weight: 600;">handler</span>: <span style="color: #66cc66;">myorg.handlers:DockerRegistryHandler</span>
<span style="color: cyan; font-weight: 600;">child_types</span>:
- <span style="color: cyan; font-weight: 600;">type</span>: <span style="color: #66cc66;">local/docker-image</span>
<span style="color: cyan; font-weight: 600;">relationship</span>: <span style="color: #66cc66;">contains</span>
<span style="color: cyan; font-weight: 600;">auto_discover</span>: <span style="color: #66cc66;">true</span>
- <span style="color: #66cc66;">local/docker-image</span>
<span style="opacity: 0.7;"> # Auto-discovery controls per-child discovery behavior</span>
<span style="color: cyan; font-weight: 600;">auto_discovery</span>:
<span style="color: cyan; font-weight: 600;">enabled</span>: <span style="color: #66cc66;">true</span>
<span style="color: cyan; font-weight: 600;">strategy</span>: <span style="color: #66cc66;">list_tags</span>
<span style="color: cyan; font-weight: 600;">manual_link</span>: <span style="color: #66cc66;">false</span>
</code></pre></div>
#### Custom Index Backends