forked from HAL9000/cleveragents-core
aditya
e476d2de0e
Extend actor YAML schema to support hierarchical graphs with explicit node types (agent, tool, conditional, subgraph), per-node LSP bindings (lsp_binding with server, languages, auto, capabilities), and tool-source references (skills, mcp_servers, agent_skills). Add schema validation for namespaced actor references, duplicate node IDs, edge target existence, and graph reachability — all nodes must be reachable from entry_node via explicit edges or conditional node routing targets. Update loader to report YAML parse errors with precise line/column positions and schema validation errors with dotted field paths and remediation hints pointing to docs/reference/actor_config.md. Add docs/reference/actor_config.md as the practical configuration reference covering hierarchical graph examples, node type table, topology rules, and common error cases with fix guidance. Refresh examples/actors/graph_workflow.yaml to replace deprecated actor_path with actor_ref. Add benchmarks/actor_yaml_bench.py for schema load overhead. Tests: 95 Behave scenarios, 10 Robot smoke tests (including hierarchical loader smoke test), security scan clean, coverage 99% (threshold 97%). ISSUES CLOSED: #157
166 lines
4.1 KiB
Markdown
166 lines
4.1 KiB
Markdown
# Actor Hierarchy and Advanced YAML Extensions
|
|
|
|
This document covers the advanced actor YAML schema extensions introduced
|
|
in **M2.1.actor-yaml**: per-node LSP bindings, tool-source references,
|
|
subgraph actor references, and actor-level skill/LSP fields.
|
|
|
|
## Overview
|
|
|
|
Actor YAML configurations can define multi-node graph workflows. The
|
|
M2.1 extensions add fine-grained control over:
|
|
|
|
| Feature | Scope | Purpose |
|
|
|---------|-------|---------|
|
|
| `lsp_binding` | Per-node | Bind specific LSP servers to individual graph nodes |
|
|
| `tool_sources` | Per-node | Declare where a node's tools come from (skills, MCP, builtins) |
|
|
| `actor_ref` | Per-node (subgraph) | Reference another actor by namespaced name |
|
|
| `skills` | Actor-level | List of skill references available to the actor |
|
|
| `lsp` | Actor-level | Default LSP server bindings for the actor |
|
|
| `lsp_capabilities` | Actor-level | Filter which LSP capabilities are exposed |
|
|
| `lsp_context_enrichment` | Actor-level | Control automatic context injection |
|
|
|
|
## Per-Node LSP Binding
|
|
|
|
Different nodes in a graph can have different LSP configurations:
|
|
|
|
```yaml
|
|
nodes:
|
|
- id: strategist
|
|
type: agent
|
|
name: Strategy Planner
|
|
description: Plans with read-only LSP
|
|
lsp_binding:
|
|
server: local/pyright
|
|
languages:
|
|
- python
|
|
capabilities:
|
|
- diagnostics
|
|
- hover
|
|
|
|
- id: implementer
|
|
type: agent
|
|
name: Implementer
|
|
description: Full LSP auto-binding
|
|
lsp_binding:
|
|
auto: true
|
|
```
|
|
|
|
### `NodeLspBinding` Fields
|
|
|
|
| Field | Type | Default | Description |
|
|
|-------|------|---------|-------------|
|
|
| `server` | `string` | `null` | Namespaced LSP server name (e.g. `local/pyright`) |
|
|
| `languages` | `list[string]` | `[]` | Languages for language-based resolution |
|
|
| `auto` | `bool` | `false` | Auto-resolve from project resources |
|
|
| `capabilities` | `list[string]` | `null` | Capability filter for this node |
|
|
|
|
## Tool-Source References
|
|
|
|
Nodes can declare their tool sources explicitly:
|
|
|
|
```yaml
|
|
nodes:
|
|
- id: executor
|
|
type: agent
|
|
name: Executor
|
|
description: Has multiple tool sources
|
|
tool_sources:
|
|
- type: skill
|
|
name: local/file-ops
|
|
- type: mcp
|
|
name: local/filesystem
|
|
- type: builtin
|
|
group: git_operations
|
|
```
|
|
|
|
### `ToolSourceRef` Fields
|
|
|
|
| Field | Type | Required | Description |
|
|
|-------|------|----------|-------------|
|
|
| `type` | `string` | Yes | `skill`, `mcp`, `builtin`, or `custom` |
|
|
| `name` | `string` | No | Namespaced name (for `skill` and `mcp`) |
|
|
| `group` | `string` | No | Group identifier (for `builtin`) |
|
|
|
|
## Subgraph Actor References
|
|
|
|
Subgraph nodes can reference other actors by namespaced name:
|
|
|
|
```yaml
|
|
nodes:
|
|
- id: review
|
|
type: subgraph
|
|
name: Code Review
|
|
description: Delegates to code-reviewer
|
|
actor_ref: local/code-reviewer
|
|
```
|
|
|
|
The `actor_ref` field must be in `namespace/name` format.
|
|
|
|
## Actor-Level Fields
|
|
|
|
### `skills`
|
|
|
|
```yaml
|
|
skills:
|
|
- local/file-ops
|
|
- local/git-ops
|
|
```
|
|
|
|
### `lsp`
|
|
|
|
Explicit binding (list of server names):
|
|
|
|
```yaml
|
|
lsp:
|
|
- local/pyright
|
|
- local/clangd
|
|
```
|
|
|
|
Auto binding:
|
|
|
|
```yaml
|
|
lsp:
|
|
auto: true
|
|
```
|
|
|
|
### `lsp_capabilities`
|
|
|
|
```yaml
|
|
lsp_capabilities:
|
|
- diagnostics
|
|
- hover
|
|
- definitions
|
|
```
|
|
|
|
Or expose all:
|
|
|
|
```yaml
|
|
lsp_capabilities: all
|
|
```
|
|
|
|
### `lsp_context_enrichment`
|
|
|
|
```yaml
|
|
lsp_context_enrichment:
|
|
diagnostics: true
|
|
type_annotations: false
|
|
max_diagnostics_per_file: 50
|
|
```
|
|
|
|
## Validation Error Messages
|
|
|
|
Validation errors now include field-path context:
|
|
|
|
| Error | Example Message |
|
|
|-------|-----------------|
|
|
| Bad entry node | `Entry node 'missing' not found in route.entry_node. Valid node IDs: [a, b]` |
|
|
| Bad exit node | `Exit node 'missing' not found in route.exit_nodes. Valid node IDs: [a, b]` |
|
|
| Bad edge ref | `Edge from_node 'ghost' not found at route.edges[0]. Valid node IDs: [a, b]` |
|
|
| Duplicate IDs | `route.nodes: Duplicate node IDs found: ['dup']. Each node ID must be unique.` |
|
|
| Cycle | `route: graph contains a cycle involving nodes: [a → b]. Hint: remove or redirect edges.` |
|
|
|
|
## Complete Example
|
|
|
|
See `examples/actors/hierarchical_workflow.yaml` for a full working example
|
|
combining all these features.
|