cleveragents-core/docs/api/resource.md

cleveragents.resource — Resource System

The resource package provides the resource type schema, handler infrastructure, and the type-inheritance resolution system. Resources are the managed external entities (files, databases, containers, LSP servers, cloud services) that plans read from and write to.

See ADR-008, ADR-036, and ADR-042 for design rationale.

---

Type Inheritance

resolve_inheritance_chain(type_name, registry) → list[str]

Returns the full inheritance chain for a resource type, from the type itself up to the root. Raises ResourceTypeCircularInheritanceError if a cycle is detected, or ResourceTypeInheritanceDepthError if the chain exceeds MAX_CHAIN_DEPTH (default: 16).

from cleveragents.resource import resolve_inheritance_chain

chain = resolve_inheritance_chain("container.docker", registry)
# → ["container.docker", "container", "resource"]

resolve_fields(type_name, registry) → dict[str, Any]

Merges field definitions from the full inheritance chain, with child fields overriding parent fields.

is_subtype_of(child, parent, registry) → bool

Returns True if child is a subtype of parent.

from cleveragents.resource import is_subtype_of

is_subtype_of("container.docker", "container", registry)  # True

find_subtypes(parent, registry) → list[str]

Returns all registered types that are subtypes of parent.

validate_chain(chain) → None

Validates a pre-computed inheritance chain for cycles and depth.

TypeRegistryMap

Type alias: dict[str, ResourceTypeDefinition]. The registry maps type names to their definitions.

---

Inheritance Errors

Exception	Description
ResourceTypeCircularInheritanceError	Cycle detected in type hierarchy
ResourceTypeInheritanceDepthError	Chain exceeds MAX_CHAIN_DEPTH
ResourceTypeParentNotFoundError	Parent type not registered
ResourceTypeParentRemovalError	Attempt to remove a type that has children

---

Constants

Constant	Value	Description
MAX_CHAIN_DEPTH	16	Maximum inheritance chain depth

---

Resource Handlers

Resource handlers live in cleveragents.resource.handlers and implement CRUD, checkpoint, and rollback operations for specific resource types. Built-in handlers include:

Handler	Resource Types
Database handler	sqlite, postgresql, mysql, duckdb
Container handler	container.docker, container.podman
LSP handler	lsp.*
File handler	file, directory
Cloud handler	cloud.*

Each handler implements the ResourceHandler protocol:

class ResourceHandler(Protocol):
    async def read(self, resource_id: str, context: ...) -> Any: ...
    async def write(self, resource_id: str, data: Any, context: ...) -> None: ...
    async def delete(self, resource_id: str, context: ...) -> None: ...
    async def list_children(self, resource_id: str, context: ...) -> list[str]: ...
    async def diff(self, resource_id: str, other_id: str, context: ...) -> str: ...
    async def checkpoint(self, resource_id: str) -> str: ...
    async def rollback(self, resource_id: str, checkpoint_id: str) -> None: ...
    async def create_sandbox(self, resource_id: str) -> "Sandbox": ...

---

DatabaseResourceHandler

Full CRUD and checkpoint/rollback for SQLite and remote databases.

Method	SQLite	PostgreSQL / MySQL / DuckDB
read()	Queries sqlite_master for schema	Not supported (returns graceful failure)
write(sql)	Executes SQL statement	Not supported
delete()	DROP TABLE IF EXISTS	Not supported
list_children()	Lists tables and views	Not supported
diff()	Content-hash schema comparison	Not supported
create_checkpoint()	SAVEPOINT <name>	Not supported
rollback_to()	ROLLBACK TO SAVEPOINT <name>	Not supported

Remote database operations return a structured not-supported result rather than raising.

from cleveragents.resource.handlers import DatabaseResourceHandler

handler = DatabaseResourceHandler()
checkpoint_id = await handler.checkpoint("my-db")
await handler.rollback("my-db", checkpoint_id)

---

DevcontainerHandler

Full protocol implementation for container.devcontainer resources.

Method	Implementation
delete()	devcontainer exec rm -rf <path>
list_children()	devcontainer exec ls -1 <path>
diff()	Content-hash comparison of resource state
create_sandbox()	Delegates to BaseResourceHandler with lazy activation

All methods return graceful failure results for missing or stopped containers rather than raising exceptions.

from cleveragents.resource.handlers import DevcontainerHandler

handler = DevcontainerHandler()
children = await handler.list_children("my-devcontainer:/workspace")