cleveragents-core/docs/reference/actor_hierarchy.md

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:

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:

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:

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

skills:
  - local/file-ops
  - local/git-ops

lsp

Explicit binding (list of server names):

lsp:
  - local/pyright
  - local/clangd

Auto binding:

lsp:
  auto: true

lsp_capabilities

lsp_capabilities:
  - diagnostics
  - hover
  - definitions

Or expose all:

lsp_capabilities: all

lsp_context_enrichment

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.