2.9 KiB
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
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).