Skip to content

Self-improving AI Employees for everyone

feat(nodes): Wave 10.A + 10.C — plugin scaffold, each node owns its own data

trohitg892da10a6f0f
diff --git a/server/main.py b/server/main.py
index e45188a9..4d8efe20 100644
--- a/server/main.py
+++ b/server/main.py
@@ -64,6 +64,11 @@ async def lifespan(app: FastAPI):
# Startup
_startup_log("Lifespan startup begin")
+ # Wave 10.C: discover node plugins so their register_node() calls
+ # populate the four registries before any router serves NodeSpec.
+ # Side-effect import; the package __init__ walks its submodules.
+ import nodes # noqa: F401
+
# Wire dependency injection
container.wire(modules=[
"routers.workflow",
diff --git a/server/models/node_metadata.py b/server/models/node_metadata.py
index dd5293c3..0d634fa0 100644
--- a/server/models/node_metadata.py
+++ b/server/models/node_metadata.py
@@ -12,22 +12,45 @@ fast iteration during the migration — switch to a TypedDict / Pydantic
model once the schema stabilises.
"""
-from typing import Any, Optional, TypedDict
+from typing import Any, Literal, Optional, TypedDict
+
+
+class NodeHandle(TypedDict, total=False):
+ """One React Flow handle on a node. Wave 10.A replaces the
+ frontend-hardcoded `AGENT_CONFIGS` handle topology.
+ """
+
+ name: str # "input-skill", "output-top", ...
+ kind: Literal["input", "output"]
+ position: Literal["top", "bottom", "left", "right"]
+ offset: str # CSS % e.g. "25%"; optional
+ label: str # tooltip
+ role: str # "main" / "skill" / "tools" / "memory" / "task" / "teammates" / "model"
class NodeMetadata(TypedDict, total=False):
+ # Existing (Wave 6):
displayName: str
- icon: str
+ icon: str # emoji | "asset:<key>" | SVG data URI
group: list[str]
subtitle: str
description: str
version: int
- # Wave 6: per-node UI panel hints lifted from the legacy frontend
- # INodeUIHints. Carries flags like isChatTrigger / isConsoleSink /
- # hasCodeEditor / isMemoryPanel / isToolPanel / etc. Empty dict when
- # the node doesn't need any panel-level toggles.
+ # Per-node UI panel hints lifted from the legacy frontend INodeUIHints.
+ # Flags like isChatTrigger / isConsoleSink / hasCodeEditor / isMemoryPanel.
uiHints: dict[str, object]
+ # Wave 10.A — full visual contract:
+ color: str # hex or dracula token e.g. "#bd93f9"
+ componentKind: Literal[ # frontend component dispatch key
+ "square", "circle", "trigger", "start",
+ "agent", "chat", "tool", "model", "generic",
+ ]
+ handles: list[NodeHandle] # replaces AGENT_CONFIGS topology
+ credentials: list[str] # provider keys
+ hideOutputHandle: bool # replaces NO_OUTPUT_NODE_TYPES
+ visibility: Literal["all", "normal", "dev"] # replaces SIMPLE_MODE_CATEGORIES
+
# Seeded incrementally per Wave 6 Phase 3 sub-commit. Sub-commit 3a
# covers utility + code + process + workflow groups (12 types). Later
diff --git a/server/nodes/__init__.py b/server/nodes/__init__.py
new file mode 100644
index 00000000..9b47d4cd
--- /dev/null
+++ b/server/nodes/__init__.py
@@ -0,0 +1,72 @@
+"""Per-node plugin modules (Wave 10.C).
+
+Each ``.py`` file in this package registers one node (or a family of
+closely related nodes) via ``services.node_registry.register_node``. We
+walk the package at import time so every module's ``register_node(...)``
+call runs before the FastAPI app starts serving NodeSpec endpoints.
+
+To add a new node, create ``server/nodes/<name>.py`` with:
+
+ from typing import Literal
+ from pydantic import Field
+ from models.nodes import BaseNodeParams
+ from services.node_registry import register_node
+
+ class MyParams(BaseNodeParams):
+ type: Literal["myNode"]
+ query: str = Field(default="", json_schema_extra={"placeholder": "Search..."})
+
+ async def handle_my_node(node_id, node_type, params, context):
+ return {"success": True, "result": {...}}
+
+ register_node(
+ type="myNode",
+ metadata={
+ "displayName": "My Node",
+ "icon": "asset:my_icon",
+ "group": ["tool"],
+ "color": "#8be9fd",
+ "componentKind": "square",
+ "handles": [
+ {"name": "input-main", "kind": "input", "position": "left", "role": "main"},
+ {"name": "output-main", "kind": "output", "position": "right", "role": "main"},
+ ],
+ "description": "...",
+ "version": 1,
+ },
+ input_model=MyParams,
+ handler=handle_my_node,
+ )
+
+Zero edits required in any other file. The node appears in the editor
+at the next backend restart.
+"""
+
+from __future__ import annotations
+
+import importlib
+import logging
+import pkgutil
+
+logger = logging.getLogger(__name__)
+
+
+def _discover() -> list[str]:
+ """Import every submodule so its ``register_node`` side effect runs.
+ Returns the list of module names imported, for logging."""
+ imported: list[str] = []
+ for module_info in pkgutil.iter_modules(__path__):
+ name = module_info.name
+ if name.startswith("_"):
+ continue
+ full_name = f"{__name__}.{name}"
+ try:
+ importlib.import_module(full_name)
+ imported.append(name)
+ except Exception:
+ logger.exception("Failed to import node plugin %s", full_name)
+ return imported
+
+
+_DISCOVERED = _discover()
+logger.info("node plugins loaded: %s", _DISCOVERED or "(none yet)")
diff --git a/server/services/node_executor.py b/server/services/node_executor.py
index 243a9444..90a4a810 100644
--- a/server/services/node_executor.py
+++ b/server/services/node_executor.py
@@ -121,7 +121,16 @@ class NodeExecutor:
self._handlers = self._build_handler_registry()
def _build_handler_registry(self) -> Dict[str, Callable]:
- """Build handler registry with service dependencies bound via partial."""
+ """Build handler registry with service dependencies bound via partial.
+
+ Plugin handlers registered via ``services.node_registry.register_node``
+ win over the legacy hardcoded entries below; this lets per-node
+ plugin modules in ``server/nodes/*.py`` override the dispatcher
+ without touching this file. Plugin handlers are closed over their
+ own dependencies at module import time, so no ``partial`` wiring
+ is needed here.
+ """
+ from services.node_registry import _HANDLER_REGISTRY as _PLUGIN_HANDLERS
registry = {
# Workflow control
'start': handle_start,
@@ -229,6 +238,10 @@ class NodeExecutor:
for node_type in ANDROID_SERVICE_NODE_TYPES:
registry[node_type] = partial(handle_android_service, android_service=self.android_service)
+ # Plugin handlers last: they win over the legacy entries above,
+ # enabling incremental migration (Wave 10.C strangler fig).
+ registry.update(_PLUGIN_HANDLERS)
+
return registry
async def execute(
diff --git a/server/services/node_registry.py b/server/services/node_registry.py
new file mode 100644
index 00000000..f45e41de
--- /dev/null
+++ b/server/services/node_registry.py
@@ -0,0 +1,78 @@
+"""Unified node registration (Wave 10.C).
+
+One decorator, one file per node. Each node's own module declares its
+own metadata (displayName, icon, color, handles, componentKind, ...),
+Pydantic input model, output model, and handler, and calls
+``register_node(...)`` at import time. Discovery of ``server/nodes/*.py``
+happens via ``server/nodes/__init__.py``'s ``pkgutil.walk_packages``.
+
+Adding a new node = one Python module. Zero cross-cutting edits. Zero
+frontend change. The NodeSpec envelope served at
+``GET /api/schemas/nodes/{type}/spec.json`` picks up everything.
+
+This is a **strangler fig** over the existing four registries:
+ models/node_metadata.NODE_METADATA
+ services/node_input_schemas._DIRECT_MODELS
+ services/node_output_schemas.NODE_OUTPUT_SCHEMAS
+ services/node_executor._build_handler_registry()
+
+``register_node`` writes to the first three directly and to an
+additional ``_HANDLER_REGISTRY`` dict that ``node_executor`` reads on
+startup. Legacy entries that were seeded before ``register_node``
+remain untouched — migration is incremental.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Optional, Type
+
+from pydantic import BaseModel
+
+from models.node_metadata import NODE_METADATA, NodeMetadata
+from services.node_input_schemas import _DIRECT_MODELS
+from services.node_output_schemas import NODE_OUTPUT_SCHEMAS
+
+
+_HANDLER_REGISTRY: dict[str, Callable] = {}
+
+
+def register_node(
+ *,
+ type: str,
+ metadata: NodeMetadata,
+ input_model: Optional[Type[BaseModel]] = None,
+ output_model: Optional[Type[BaseModel]] = None,
+ handler: Optional[Callable] = None,
+) -> None:
+ """Register a node's metadata + schemas + handler in one call.
+
+ Idempotent: re-registering the same type replaces the prior entry,
+ which supports module hot-reload during development.
+
+ Only ``type`` and ``metadata`` are required. A node can be handler-
+ free (e.g. a memory / config node that only carries parameters the
+ agent reads from the edge) or schema-free (e.g. a pure visual marker
+ with no runtime effect), though in practice most nodes have both.
+ """
+ NODE_METADATA[type] = metadata
+ if input_model is not None:
+ _DIRECT_MODELS[type] = input_model
+ if output_model is not None:
+ NODE_OUTPUT_SCHEMAS[type] = output_model
+ if handler is not None:
+ _HANDLER_REGISTRY[type] = handler
+
+
+def get_registered_handler(node_type: str) -> Optional[Callable]:
+ """Handler registered via ``register_node``, or None.
+
+ ``NodeExecutor._build_handler_registry`` consults this first and
+ falls back to its built-in dict for types still on the legacy path.
+ """
+ return _HANDLER_REGISTRY.get(node_type)
+
+
+def registered_node_types() -> frozenset[str]:
+ """Types that came in via the plugin path. Useful for tests and for
+ telling the legacy dispatcher which types it must NOT also claim."""
+ return frozenset(_HANDLER_REGISTRY.keys())
diff --git a/server/services/node_spec.py b/server/services/node_spec.py
index acf02dd4..cae54c01 100644
--- a/server/services/node_spec.py
+++ b/server/services/node_spec.py
@@ -71,6 +71,13 @@ def get_node_spec(node_type: str) -> Optional[dict[str, Any]]:
if meta.get("uiHints"):
spec["uiHints"] = meta["uiHints"]
+ # Wave 10.A — full visual contract. Only emit fields when seeded so the
+ # wire format stays compact and unseeded types keep the pre-10 shape.
+ for key in ("color", "componentKind", "handles", "credentials",
+ "hideOutputHandle", "visibility"):
+ if key in meta:
+ spec[key] = meta[key]
+
_spec_cache[node_type] = spec
return spec