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

Browse Source 
The spec had three inconsistent YAML formats for custom resource types
across different sections. The canonical format is defined in
docs/schema/resource_type.schema.yaml. Update spec examples to match:

- physical_or_virtual -> resource_kind (matches schema field name)
- cli_arguments -> cli_args (matches schema field name)
- allowed_parent_types -> parent_types (matches schema field name)
- checkpointable (top-level) -> capabilities.checkpoint (matches schema)
- readable/writable/sandboxable -> read/write/sandbox (matches schema)
- handler: ClassName -> handler: module:ClassName (matches schema format)
- classification -> resource_kind (fixes extensibility section)
- child_types: [{type: x}] -> child_types: [x] (matches schema items)
- document auto_discovery as the place for per-child discovery settings

Also update ResourceTypeRecord UML class diagram to match schema fields.

ISSUES CLOSED: #5622
This commit is contained in:
HAL 9000
2026-04-09 08:11:17 +00:00
committed by Forgejo
parent 0fe78e7eff
commit 6eb7ceb3fd
1 changed files with 30 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/specification.md
+29 -28
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>
- 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;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>
<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