freemo
71177c6e1a
CI / lint (push) Failing after 18s
CI / build (push) Successful in 18s
CI / helm (push) Successful in 29s
CI / quality (push) Successful in 37s
CI / security (push) Failing after 52s
CI / typecheck (push) Failing after 58s
CI / coverage (push) Has been skipped
CI / benchmark-regression (push) Has been skipped
CI / unit_tests (push) Failing after 1m58s
CI / docker (push) Has been skipped
CI / benchmark-publish (push) Has been cancelled
CI / e2e_tests (push) Has been cancelled
CI / integration_tests (push) Has been cancelled
CI / status-check (push) Has been cancelled
- CHANGELOG: add [Unreleased] entries for TUI first-run experience (#1391), session Markdown export (#1004), and UKO provenance/temporal versioning (#891) - README: add first-run experience and Markdown transcript export bullets - docs/api/tui.md: new TUI API reference covering first-run, persona system, input routing, slash commands, session export/import, and widgets - docs/api/index.md: add TUI entry to module index - docs/api/resource.md: document DatabaseResourceHandler and DevcontainerHandler full protocol implementations with method tables and examples - docs/architecture.md: expand UKO section with provenance/temporal versioning details; update TUI design decision summary - mkdocs.yml: add TUI page to API Reference nav ISSUES CLOSED: #1391 #1004 #891
155 lines
5.1 KiB
Markdown
155 lines
5.1 KiB
Markdown
# `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/ADR-008-resource-system.md),
|
|
[ADR-036](../adr/ADR-036-resource-dag-operational-semantics.md), and
|
|
[ADR-042](../adr/ADR-042-resource-type-inheritance.md) 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).
|
|
|
|
```python
|
|
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`.
|
|
|
|
```python
|
|
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:
|
|
|
|
```python
|
|
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.
|
|
|
|
```python
|
|
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.
|
|
|
|
```python
|
|
from cleveragents.resource.handlers import DevcontainerHandler
|
|
|
|
handler = DevcontainerHandler()
|
|
children = await handler.list_children("my-devcontainer:/workspace")
|
|
```
|