# Actor Hierarchy and Advanced YAML Extensions

This document covers the advanced actor YAML schema extensions: per-node
LSP bindings, tool-source references, subgraph actor references, and
actor-level skill/LSP fields.

**Module:** `cleveractors.actor.schema`

## Overview

Actor YAML configurations can define multi-node graph workflows. These
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 |

The `LspBinding` objects extracted from per-node configurations are available
on `CompiledActor.metadata.lsp_bindings` after compilation. The host
application is responsible for starting the LSP servers at runtime.

## 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 reference other actors by namespaced name using the
`actor_ref` field (not `config.actor_path`):

```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. The compiler
records this reference in `CompiledActor.metadata.subgraph_refs` for
cross-actor cycle detection; the host resolves the actual actor at
execution time.

## Actor-Level Fields

### `skills`

List of skill references available to the actor and its nodes:

```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`

Filter which LSP capabilities are exposed to this actor:

```yaml
lsp_capabilities:
  - diagnostics
  - hover
  - definitions
```

Or expose all:

```yaml
lsp_capabilities: all
```

### `lsp_context_enrichment`

Control automatic context injection from LSP:

```yaml
lsp_context_enrichment:
  diagnostics: true
  type_annotations: false
  max_diagnostics_per_file: 50
```

## Validation Error Messages

Validation errors 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

```yaml
name: workflows/dev-pipeline
type: graph
description: Multi-agent development pipeline with LSP and tool-source control
version: "1.0"
provider: openai
model: gpt-4

# Actor-level declarations
skills:
  - local/file-ops
  - local/git-ops
lsp:
  - local/pyright
lsp_capabilities:
  - diagnostics
  - hover

route:
  nodes:
    - id: planner
      type: agent
      name: Planner
      description: Plans the implementation strategy
      config:
        model: gpt-4
        prompt: "Analyze requirements and create a plan."
      lsp_binding:
        server: local/pyright
        languages:
          - python
        capabilities:
          - diagnostics
      tool_sources:
        - type: skill
          name: local/file-ops

    - id: implementer
      type: agent
      name: Implementer
      description: Implements the plan
      config:
        model: gpt-4
        prompt: "Implement the changes per the plan."
      lsp_binding:
        auto: true
      tool_sources:
        - type: skill
          name: local/file-ops
        - type: skill
          name: local/git-ops
        - type: mcp
          name: local/filesystem

    - id: reviewer
      type: subgraph
      name: Code Reviewer
      description: Delegates to the code-review actor
      actor_ref: local/code-reviewer

  edges:
    - from_node: planner
      to_node: implementer
    - from_node: implementer
      to_node: reviewer

  entry_node: planner
  exit_nodes:
    - reviewer
```

## See Also

- [Actor YAML Schema](actors_schema.md) — full field reference
- [Actor Configuration Guide](actor_config.md) — practical authoring guide
- [Actor Compiler](actor_compiler.md) — how LSP bindings are extracted during compilation