Files

T

feat(actor): extend hierarchical actor YAML schema and loader

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

2026-02-25 10:30:42 +00:00

4.1 KiB

Raw Blame History

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.

4.1 KiB Raw Blame History