Skip to content

Self-improving AI Employees for everyone

feat(schemas): per-plugin icon endpoint + NodeSpec URL emission

trohitg57286f380444
diff --git a/server/nodes/_visuals.py b/server/nodes/_visuals.py
index f9325dd1..95e97dc8 100644
--- a/server/nodes/_visuals.py
+++ b/server/nodes/_visuals.py
@@ -1,25 +1,34 @@
"""Central handler for node visuals (icon + color).
-Every node plugin's icon and color live in ``visuals.json`` next to
-this module. The base ``BaseNode`` class consults
-:func:`get_icon` / :func:`get_color` at registration time when a
-subclass doesn't set the class attribute itself.
-
-Single source of truth — change the icon for ``aiAgent`` here once
-and every consumer (palette, parameter panel, canvas) picks it up
-the next time the backend NodeSpec cache rehydrates.
-
-Adding a new node: add an entry to ``visuals.json`` (or rely on the
-empty default — the icon resolver falls back to the empty string,
-which the frontend renders as a placeholder). Node files do NOT
-declare ``icon`` or ``color`` themselves.
+Two icon sources co-exist by design (per RFC §6.5):
+
+1. **Per-plugin ``icon.svg``** co-located with the plugin folder
+ (e.g. ``server/nodes/telegram/icon.svg``). Resolved at runtime via
+ :func:`get_plugin_icon_path`. Preferred for new plugins; served
+ by ``GET /api/schemas/nodes/{type}/icon`` (see ``routers/schemas.py``).
+
+2. **``visuals.json``** for emoji entries and library-icon
+ (``lobehub:<brand>``) entries that don't map to a file. Resolved
+ via :func:`get_icon` / :func:`get_color`.
+
+``BaseNode._metadata_dict`` checks the per-folder path first and
+falls back to ``visuals.json``. The frontend resolver dispatches by
+the wire-format prefix (URL paths route to ``<img>``; ``asset:``,
+``lobehub:``, emoji each have their own branch).
+
+Adding a new node:
+- Drop ``icon.svg`` into the plugin folder, OR
+- Add an entry to ``visuals.json`` (emoji or ``lobehub:<brand>``).
+
+Node files do NOT declare ``icon`` or ``color`` themselves.
"""
from __future__ import annotations
+import inspect
import json
from pathlib import Path
-from typing import Dict
+from typing import Dict, Optional
_VISUALS_PATH = Path(__file__).resolve().parent / "visuals.json"
@@ -66,6 +75,45 @@ def get_color(node_type: str) -> str:
return str(entry.get("color", ""))
+def get_plugin_icon_path(node_type: str, variant: str = "light") -> Optional[Path]:
+ """Return the on-disk path to a plugin's co-located ``icon.svg``.
+
+ ``variant="dark"`` looks for ``icon.dark.svg`` first and falls back
+ to ``icon.svg`` if the dark variant is missing.
+
+ Resolution:
+ 1. Look up the plugin class via :func:`services.node_registry.get_node_class`.
+ 2. Resolve the class's source file via ``inspect.getfile``.
+ 3. The plugin folder is the file's parent directory — equally
+ correct for single-file plugins (``server/nodes/tool/calc.py``
+ → parent ``server/nodes/tool/``) and self-contained-folder
+ plugins (``server/nodes/telegram/telegram_send.py`` → parent
+ ``server/nodes/telegram/``).
+ 4. Return ``<plugin_dir>/icon.svg`` (or dark variant) if it exists.
+
+ Returns ``None`` when the type is unknown or no ``icon.svg`` is
+ present — caller falls back to :func:`get_icon` (visuals.json).
+ """
+ # Local import to avoid a top-level circular dep (node_registry
+ # itself doesn't import _visuals, but plugin modules import both).
+ from services.node_registry import get_node_class
+
+ cls = get_node_class(node_type)
+ if cls is None:
+ return None
+ try:
+ plugin_dir = Path(inspect.getfile(cls)).resolve().parent
+ except (TypeError, OSError):
+ return None
+
+ if variant == "dark":
+ dark = plugin_dir / "icon.dark.svg"
+ if dark.exists():
+ return dark
+ icon = plugin_dir / "icon.svg"
+ return icon if icon.exists() else None
+
+
def get_skill(node_type: str) -> str:
"""Return the teaching skill folder name registered for ``node_type``.
diff --git a/server/routers/schemas.py b/server/routers/schemas.py
index 42650bdf..d37eba46 100644
--- a/server/routers/schemas.py
+++ b/server/routers/schemas.py
@@ -7,8 +7,10 @@ the design rationale and docs-internal/schema_source_of_truth_rfc.md
for the frontend consumer (useNodeOutputSchemaQuery).
"""
-from fastapi import APIRouter, HTTPException, Response
+from fastapi import APIRouter, HTTPException, Query, Response
+from fastapi.responses import FileResponse
+from nodes._visuals import get_plugin_icon_path
from services.node_input_schemas import (
get_node_input_schema,
list_node_types_with_input_schema,
@@ -83,6 +85,36 @@ async def get_node_spec_endpoint(node_type: str, response: Response):
return spec
[email protected]("/nodes/{node_type}/icon")
+async def get_node_icon(
+ node_type: str,
+ variant: str = Query("light", pattern="^(light|dark)$"),
+):
+ """Return the plugin folder's co-located ``icon.svg``.
+
+ Per RFC §6.5 — backend is the sole authority on plugin assets.
+ The frontend resolver dispatches by wire format: URLs route to
+ ``<img src=...>``; ``asset:<key>`` / ``lobehub:<brand>`` / emoji
+ each have their own branch in ``client/src/assets/icons/index.ts``.
+
+ - ``?variant=dark``: serve ``icon.dark.svg`` if present, fall back
+ to ``icon.svg``.
+ - 200: SVG bytes with ``image/svg+xml`` + long cache headers.
+ - 404: no per-folder icon — frontend falls back to the bundled
+ ``ICON_REGISTRY`` (Wave 11 legacy path) via the ``asset:<key>``
+ string in ``visuals.json``.
+ """
+
+ path = get_plugin_icon_path(node_type, variant=variant)
+ if path is None:
+ raise HTTPException(status_code=404, detail=f"No icon for {node_type!r}")
+ return FileResponse(
+ path,
+ media_type="image/svg+xml",
+ headers={"Cache-Control": _LONG_CACHE},
+ )
+
+
@router.get("/nodes/specs")
async def list_specs():
"""List every node type with at least an input model or an output
diff --git a/server/services/plugin/base.py b/server/services/plugin/base.py
index 50fadca5..8ddcca4a 100644
--- a/server/services/plugin/base.py
+++ b/server/services/plugin/base.py
@@ -194,12 +194,21 @@ class BaseNode:
"""Project class attributes onto the :data:`NodeMetadata` TypedDict
expected by the existing node_spec emitter.
- ``icon`` and ``color`` are sourced from
- ``server/nodes/visuals.json`` via the central handler — node
- plugins don't declare them on the class.
+ Icon resolution (per RFC §6.5):
+ 1. Per-plugin ``icon.svg`` co-located with the plugin folder —
+ emitted as a URL routed through ``GET /api/schemas/nodes/<type>/icon``.
+ 2. Fallback to ``visuals.json`` (emoji / ``lobehub:<brand>``).
+
+ ``color`` continues to come from ``visuals.json`` (orthogonal
+ to icon source; a future ``meta.json`` may eventually move
+ colors per-folder too — deferred).
"""
- from nodes._visuals import get_icon, get_color
- icon = get_icon(cls.type)
+ from nodes._visuals import get_icon, get_color, get_plugin_icon_path
+
+ if get_plugin_icon_path(cls.type) is not None:
+ icon = f"/api/schemas/nodes/{cls.type}/icon"
+ else:
+ icon = get_icon(cls.type)
color = get_color(cls.type)
meta: Dict[str, Any] = {
"displayName": cls.display_name or cls.type,