98 lines
2.9 KiB
Markdown
98 lines
2.9 KiB
Markdown
# Skill Context & Registry
|
|
|
|
Runtime context and registry for skill execution in CleverAgents v3.
|
|
|
|
## SkillContext
|
|
|
|
The `SkillContext` class provides the runtime environment for skill
|
|
execution. It carries plan/project identifiers, a sandbox root path,
|
|
resource bindings, and a change tracker for recording tool invocations.
|
|
|
|
### Fields
|
|
|
|
| Field | Type | Description |
|
|
|-------|------|-------------|
|
|
| `plan_id` | `str` | Identifier for the current plan |
|
|
| `project_id` | `str` | Identifier for the current project |
|
|
| `sandbox_path` | `Path` | Root path to the execution sandbox |
|
|
| `change_tracker` | `list[dict]` | Recorded tool invocation records |
|
|
| `resource_bindings` | `dict[str, Any]` | Bound resource name → value mapping |
|
|
| `read_only` | `bool` | Whether write operations are forbidden |
|
|
| `metadata` | `dict[str, Any]` | Arbitrary plan/project metadata |
|
|
|
|
### Methods
|
|
|
|
#### `resolve_resource(name: str) -> Any`
|
|
|
|
Look up a bound resource by name from `resource_bindings`. Raises
|
|
`SkillError(RESOLUTION_FAILURE)` if the resource is not found.
|
|
|
|
#### `get_plan_metadata() -> dict[str, Any]`
|
|
|
|
Return a dict containing `plan_id`, `project_id`, and any additional
|
|
metadata stored on the context.
|
|
|
|
#### `get_sandbox_path() -> Path`
|
|
|
|
Return the sandbox root `Path`.
|
|
|
|
#### `is_read_only() -> bool`
|
|
|
|
Check whether this context forbids write operations.
|
|
|
|
#### `register_tool_invocation(tool_name, input_data, output_data, duration_ms)`
|
|
|
|
Record a tool invocation in the change tracker. Each record stores
|
|
the tool name, input/output data, duration, plan ID, and project ID.
|
|
|
|
#### `enforce_write_guard(tool_name: str)`
|
|
|
|
Raise `SkillError(PERMISSION_DENIED)` if the context is read-only and
|
|
a tool attempts to write. Should be called before any write operation.
|
|
|
|
## SkillRegistry
|
|
|
|
The `SkillRegistry` class manages in-memory registration and lookup of
|
|
skill definitions.
|
|
|
|
### Constructor
|
|
|
|
```python
|
|
SkillRegistry(tool_registry=None)
|
|
```
|
|
|
|
Optionally accepts a reference to a Tool Registry service for
|
|
tool-ref validation.
|
|
|
|
### Methods
|
|
|
|
#### `register(skill: SkillDefinition)`
|
|
|
|
Register a skill definition. Raises `SkillError(VALIDATION_ERROR)` if
|
|
a skill with the same name is already registered.
|
|
|
|
#### `unregister(name: str)`
|
|
|
|
Remove a skill from the registry. Raises `SkillError(SKILL_NOT_FOUND)`
|
|
if the skill is not registered.
|
|
|
|
#### `get(name: str) -> SkillDefinition`
|
|
|
|
Look up a skill by name. Raises `SkillError(SKILL_NOT_FOUND)` if not
|
|
found.
|
|
|
|
#### `list_all() -> list[SkillMetadata]`
|
|
|
|
Return metadata for all registered skills, sorted by name.
|
|
|
|
#### `resolve_tools(skill_name: str) -> list[ResolvedToolEntry]`
|
|
|
|
Resolve tool references for a registered skill using the
|
|
`SkillResolver`.
|
|
|
|
#### `validate_skill(skill: SkillDefinition) -> list[str]`
|
|
|
|
Validate tool references exist in the tool registry, inline tools have
|
|
descriptions, and included skills are registered. Returns a list of
|
|
error messages (empty means valid).
|