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

docs(spec): fix custom resource type YAML example to match implementation format
CI / lint (pull_request) Successful in 22s
Details
CI / security (pull_request) Successful in 56s
Details
CI / typecheck (pull_request) Successful in 1m17s
Details
CI / quality (pull_request) Successful in 30s
Details
CI / build (pull_request) Successful in 26s
Details
CI / helm (pull_request) Successful in 25s
Details
CI / push-validation (pull_request) Successful in 15s
Details
CI / e2e_tests (pull_request) Successful in 3m16s
Details
CI / integration_tests (pull_request) Successful in 7m36s
Details
CI / unit_tests (pull_request) Successful in 8m30s
Details
CI / docker (pull_request) Successful in 2m31s
Details
CI / coverage (pull_request) Successful in 12m19s
Details
CI / status-check (pull_request) Successful in 1s
Details
CI / benchmark-publish (pull_request) Has been skipped
Details
CI / benchmark-regression (pull_request) Successful in 57m40s
Details

Browse Source 
Relates to #5622

The §Custom Resource Types section showed an incorrect YAML format with:
- resource_type: wrapper (not supported by implementation)
- cleveragents: version header (not supported)
- physical_or_virtual: (implementation uses resource_kind:)
- cli_arguments: (implementation uses cli_args:)
- allowed_parent_types: (implementation uses parent_types:)
- handler: DatabaseHandler (string, implementation expects object with class/module)
- capabilities.readable/writable/sandboxable/checkpointable (implementation uses read/write/sandbox/checkpoint)

Updated the database.yaml example to use the correct flat format that matches
ResourceTypeSpec.from_config() in resource_type.py:
- Flat format (no resource_type: wrapper)
- resource_kind: physical (not physical_or_virtual:)
- cli_args: (not cli_arguments:)
- parent_types: (not allowed_parent_types:)
- handler: {class: ..., module: ...} (object format)
- capabilities: {read, write, sandbox, checkpoint}

The §Resource Type Configuration Files section (line ~34780) already uses the
correct format and serves as the authoritative reference.
This commit is contained in:
HAL 9000
2026-04-09 08:45:37 +00:00
parent ee2024046f
commit 6175e4aba0
1 changed files with 43 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/specification.md
+43 -47
View File
@@ -24503,58 +24503,54 @@ Custom resource types are defined in YAML configuration files and registered via
<div class="highlight"><pre><code>
<span style="opacity: 0.7;"># File: resource-types/database.yaml</span>
<span style="color: cyan; font-weight: 600;">cleveragents</span>:
<span style="color: cyan; font-weight: 600;">version</span>: <span style="color: #66cc66;">&quot;3.0&quot;</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;">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="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;">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_args</span>:
- <span style="color: cyan; font-weight: 600;">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_pattern</span>: <span style="color: #66cc66;">&quot;^(postgresql|mysql|sqlite)://&quot;</span>
- <span style="color: cyan; font-weight: 600;">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>
<span style="color: cyan; font-weight: 600;">description</span>: <span style="color: #66cc66;">&quot;Default schema to use&quot;</span>
- <span style="color: cyan; font-weight: 600;">name</span>: read-only
<span style="color: cyan; font-weight: 600;">type</span>: boolean
<span style="color: cyan; font-weight: 600;">required</span>: <span style="color: magenta; font-weight: 600;">false</span>
<span style="color: cyan; font-weight: 600;">default</span>: <span style="color: magenta; font-weight: 600;">false</span>
<span style="color: cyan; font-weight: 600;">description</span>: <span style="color: #66cc66;">&quot;Whether the database should be treated as read-only&quot;</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;">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;">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>
<span style="color: cyan; font-weight: 600;">description</span>: <span style="color: #66cc66;">&quot;Default schema to use&quot;</span>
- <span style="color: cyan;">name</span>: read-only
<span style="color: cyan; font-weight: 600;">type</span>: boolean
<span style="color: cyan; font-weight: 600;">required</span>: <span style="color: magenta; font-weight: 600;">false</span>
<span style="color: cyan; font-weight: 600;">default</span>: <span style="color: magenta; font-weight: 600;">false</span>
<span style="color: cyan; font-weight: 600;">description</span>: <span style="color: #66cc66;">&quot;Whether the database should be treated as read-only&quot;</span>
<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>:
<span style="color: cyan; font-weight: 600;">class</span>: DatabaseHandler
<span style="color: cyan; font-weight: 600;">module</span>: cleveragents.resource.handlers.database
<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="opacity: 0.7;"># Parent types (empty means can be top-level)</span>
<span style="color: cyan; font-weight: 600;">parent_types</span>: []
<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="opacity: 0.7;"># Child types</span>
<span style="color: cyan; font-weight: 600;">child_types</span>:
- <span style="color: cyan; font-weight: 600;">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; font-weight: 600;">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="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>
<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="opacity: 0.7;"># Capabilities</span>
<span style="color: cyan; font-weight: 600;">capabilities</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>
When this type is registered: