cleveragents-core/docs/reference/resources.md

Resource Registry

The Resource Registry manages resource types and resource instances in CleverAgents. Resource types define schemas, sandbox strategies, and handler implementations. Resource instances are registered entries that plans operate on during execution.

Built-in Resource Types

CleverAgents ships with two built-in types, available without registration:

Type	Kind	Sandbox Strategy	Handler
git-checkout	physical	git_worktree	GitCheckoutHandler
fs-directory	physical	copy_on_write	FsDirectoryHandler

Built-in types are registered idempotently at startup via ResourceRegistryService.bootstrap_builtin_types().

Resource Type Fields

Each ResourceTypeSpec defines a resource type schema:

Field	Type	Description
name	str	Unique name (built-in: bare, custom: namespace/name)
description	str	Human-readable description
resource_kind	ResourceKind	physical or virtual
sandbox_strategy	SandboxStrategy	Default sandbox isolation strategy
user_addable	bool	Whether users can register instances of this type
built_in	bool	Whether this is a built-in type
cli_args	list[ResourceTypeArgument]	CLI argument definitions for registration
parent_types	list[str]	Allowed parent type names in the DAG
child_types	list[str]	Allowed child type names in the DAG
handler	str | None	Handler ref in module:Class format
capabilities	dict[str, bool]	read, write, sandbox, checkpoint flags
auto_discovery	dict | None	Auto-discovery rules (see below)
equivalence	dict | None	Virtual resource deduplication config

Custom Types

Custom types are defined in YAML and registered via CLI or API:

name: myteam/python-package
description: A Python package directory
resource_kind: physical
sandbox_strategy: copy_on_write
user_addable: true
cli_args:
  - name: path
    type: path
    required: true
    description: Path to the package root
parent_types:
  - git-checkout
child_types:
  - fs-directory

Register with: agents resource type add path/to/type.yaml

Resource Instance Fields

Each Resource represents a registered asset:

Field	Type	Description
resource_id	str (ULID)	Unique identifier
name	str | None	Optional namespaced name
resource_type_name	str	Type this resource belongs to
classification	PhysVirt	physical or virtual
description	str | None	Human-readable description
location	str | None	Filesystem path (physical resources)
sandbox_strategy	SandboxStrategy | None	Per-resource sandbox override
content_hash	str | None	Hash of resource contents for change detection
parents	list[str]	Parent resource IDs in the DAG
children	list[str]	Child resource IDs in the DAG
properties	dict	Type-specific key-value properties
capabilities	ResourceCapabilities	readable, writable, sandboxable, checkpointable
created_at	datetime	Registration timestamp
updated_at	datetime	Last modification timestamp

Registry Service API

Type Operations

Method	Description
bootstrap_builtin_types()	Register built-in types (idempotent)
register_type(config_path)	Register a custom type from YAML
list_types(namespace=)	List types, optionally filtered
show_type(name)	Get a type by name

Resource Operations

Method	Description
register_resource(type_name, name=, location=, ...)	Create and register an instance
list_resources(type_name=)	List resources, optionally by type
show_resource(name_or_id)	Get by namespaced name or ULID

DAG Operations

Method	Description
link_child(parent, child)	Link a child to a parent
unlink_child(parent, child)	Remove a parent-child link
get_children(name_or_id)	Get direct children
get_resource_tree(name_or_id, depth=, type_filter=)	Recursive tree traversal

For DAG rules, cycle detection, type compatibility, and auto-discovery details, see Resource DAG.

Discovery Behavior

Auto-Discovery

Resource types can define auto-discovery rules that materialize child resources automatically:

auto_discovery:
  enabled: true
  rules:
    - type: fs-directory
      pattern: "*/"
    - type: fs-file
      pattern: "*"

When auto_discover_children(resource_id) is called:

1. The resource and its type are looked up.
2. Each discovery rule is evaluated:
   • The child type must exist in the registry.
   • The child type must be compatible with the parent type (per child_types).
3. New child resources are created with auto_discovered = true.
4. Links are created in the resource_links table.

Auto-discovery is triggered:

• When a resource is first registered
• When resource contents change
• On demand via CLI (agents resource discover)

Local-Mode Discovery

In local mode (the default), discovery operates against the local filesystem. The registry creates placeholder resource entries based on discovery rules; actual file enumeration is delegated to resource handlers at sandbox creation time.

Database Schema

resource_types Table

Column	Type	Description
name	String(128)	Primary key
namespace	String(64)	Namespace (or builtin)
description	Text	Human-readable description
resource_kind	String(16)	physical or virtual
sandbox_strategy	String(32)	Default sandbox strategy
user_addable	Boolean	User registration allowed
built_in	Boolean	Built-in type flag
handler	String(256)	Handler module:Class ref
args_schema_json	Text	CLI args JSON
allowed_parent_types_json	Text	Allowed parent types JSON
allowed_child_types_json	Text	Allowed child types JSON
auto_discover_json	Text	Auto-discovery config JSON
capabilities_json	Text	Capabilities JSON
equivalence_json	Text	Equivalence config JSON
source	String(256)	Registration source
created_at	String(30)	ISO-8601 timestamp
updated_at	String(30)	ISO-8601 timestamp

resources Table

Column	Type	Description
resource_id	String(26)	ULID primary key
namespaced_name	String(256)	Optional namespaced name (unique)
namespace	String(64)	Namespace extracted from name
type_name	String(128)	FK to resource_types.name
resource_kind	String(16)	physical or virtual
location	Text	Filesystem path
description	Text	Human-readable description
read_only	Boolean	Read-only flag
auto_discovered	Boolean	Created by auto-discovery
sandbox_strategy	String(32)	Per-resource sandbox override
content_hash	String(128)	Content hash for change detection
properties_json	Text	Type-specific properties JSON
metadata_json	Text	Additional metadata JSON
created_at	String(30)	ISO-8601 timestamp
updated_at	String(30)	ISO-8601 timestamp

resource_links Table

See Resource DAG for link table schema.

Source

• Domain models: src/cleveragents/domain/models/core/resource.py, resource_type.py
• Service: src/cleveragents/application/services/resource_registry_service.py
• Migration: src/cleveragents/infrastructure/database/migrations/versions/b1_001_resource_registry_tables.py
• CLI: src/cleveragents/cli/commands/resource.py
• Specification: docs/specification.md — Resource Registry sections