From 6a4b617517b0edade7aefd640eee16b457113bdd Mon Sep 17 00:00:00 2001 From: CleverThis Date: Thu, 9 Apr 2026 06:59:10 +0000 Subject: [PATCH] docs(spec): align subgraph node field from actor_path to actor_ref (top-level) Relates to #5427 The spec previously documented the subgraph node config field as actor_path inside the config block. The implementation (schema.py) uses actor_ref as a top-level field on NodeDefinition, not inside config. This commit aligns the spec with the implementation: - Renames actor_path -> actor_ref - Clarifies that actor_ref is a top-level field, NOT inside config - Adds actor_ref, lsp_binding, and tool_sources to the Node Definition table - Updates the node type-specific config table to note subgraph uses no config Note: The compiler (compiler.py) still has a bug reading node.config.get('actor_ref') instead of node.actor_ref. That is a separate implementation fix tracked in #5427. --- docs/specification.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/specification.md b/docs/specification.md index 4accaad8b..8196cee39 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -20547,7 +20547,10 @@ For `type: graph` actors, the `route` field defines the graph structure: | `type` | string | Yes | Node type: `agent`, `tool`, `conditional`, or `subgraph`. | | `name` | string | Yes | Human-readable node name. | | `description` | string | Yes | Node purpose and behavior. | -| `config` | object | No | Type-specific configuration (see below). | +| `config` | object | No | Type-specific configuration (see below). Not used by `subgraph` nodes. | +| `actor_ref` | string | No | Namespaced actor reference for `subgraph` nodes (e.g., `local/my-sub-actor`). Top-level field — **not** inside `config`. Must follow `namespace/name` format. | +| `lsp_binding` | object | No | Per-node LSP server binding (optional). | +| `tool_sources` | array | No | Tool source references for this node (optional). | **Node type-specific config:** @@ -20556,7 +20559,7 @@ For `type: graph` actors, the `route` field defines the graph structure: | `agent` | `model`, `prompt`, `tools` | LLM agent with optional tools | | `tool` | `tool_name`, `parameters` | Deterministic tool execution | | `conditional` | `conditions[].check`, `conditions[].route_to` | Routes based on state conditions (Python expressions) | -| `subgraph` | `actor_path` | Embeds another actor as a nested workflow | +| `subgraph` | *(none — use top-level `actor_ref` field)* | Embeds another actor as a nested workflow. Set `actor_ref: namespace/actor-name` at the node level, not inside `config`. | **Edge Definition:** -- 2.52.0