Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
fix(whatsapp): purpose-built node glyphs in WhatsApp colours
trohitgeb8872f7830c
diff --git a/CLAUDE.md b/CLAUDE.mdindex 571b59c8..6e80af7c 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -571,7 +571,11 @@ The frontend uses a layered cache + slice-subscription model so cold refreshes aPlugin icons and colors live co-located in the plugin folder; `visuals.json` is the legacy central registry for plugins that predate it. Resolution chain: **co-located SVG (`icon_<nodeType>.svg` → `icon.svg`) → the plugin's own `meta.json` → `visuals.json`**, documented in [server/nodes/README.md → Icon + color](./server/nodes/README.md) and [docs-internal/plugin_system.md](./docs-internal/plugin_system.md).-**Prefer a library reference over vendored artwork.** `meta.json` carries icons as well as colour — `"icons": {"<nodeType>": "lucide:Send"}` per node type, or `"icon"` for the whole folder (the same specificity pair as `icon_<nodeType>.svg` / `icon.svg`). Ship an SVG only for artwork no library has, typically a brand mark. Two traps: a **file always beats a meta.json ref**, so a folder shipping `icon.svg` shadows refs for every node type in it (this is why the four WhatsApp Business nodes once rendered one glyph); and `lucide:` names are matched against the package's **export** identifiers, so `lucide:CheckCheck` resolves and the kebab-case `lucide:check-check` silently renders nothing. Locked from both sides — `client/src/assets/icons/index.test.ts` walks every `meta.json` under `server/nodes` and asserts each ref resolves to a real component; `test_node_spec.py` asserts every `icons` key is a registered node type.+**For a node that belongs to a recognisable product, ship the brand mark as an SVG in the plugin folder** — `icon_<nodeType>.svg` per node type, `icon.svg` for the whole folder. This is what makes a node identifiable at canvas size, and it depends on nothing outside the repo.++`meta.json` can also carry icon *references* (`"icons": {"<nodeType>": "lucide:Send"}` per node type, or `"icon"` folder-wide) for generic utility nodes with no brand of their own. Treat that as the lesser option: a `lucide:<Name>` string is a hard dependency on a third-party export that can be renamed or dropped, and when it breaks the node renders **nothing** rather than erroring. Library glyphs are also monochrome `currentColor` line art, so they read as washed-out grey next to brand artwork.++Three traps: a **file always beats a meta.json ref**, so a folder shipping `icon.svg` shadows refs for every node type in it (this is why the four WhatsApp Business nodes once rendered one glyph); `lucide:` names match the package's **export** identifiers, so `lucide:CheckCheck` resolves and kebab-case `lucide:check-check` silently renders nothing; and emoji, while dependency-free, are generic rather than branded. Locked from both sides — `client/src/assets/icons/index.test.ts` walks every `meta.json` under `server/nodes` and asserts each ref resolves to a real component; `test_node_spec.py` asserts every `icons` key is a registered node type.Backend endpoints serve SVGs at `GET /api/schemas/nodes/<type>/icon` (plugin icons) and `GET /api/schemas/credentials/<provider>/icon` (credential brand icons). Frontend resolver at [client/src/assets/icons/index.ts](./client/src/assets/icons/index.ts) dispatches `lib:brand` / URL passthrough / emoji / `asset:<key>`. The `asset:` branch is currently inert at runtime (the frontend `ICON_REGISTRY` glob finds no SVGs so it resolves to null) but it is NOT dead code — the backend still emits `asset:google` / `asset:stripe` for palette groups (`server/nodes/groups.py`) and the format is invariant-tested on both sides (`test_node_spec.py` Wave 10.B, `icons/index.test.ts`).diff --git a/docs-internal/node_creation.md b/docs-internal/node_creation.mdindex 593e092c..c62bd25a 100644--- a/docs-internal/node_creation.md+++ b/docs-internal/node_creation.md@@ -225,13 +225,13 @@ walker does on startup), these registrations happen automatically:| Credentials | `CREDENTIAL_REGISTRY` | `Credential.__init_subclass__` when `_credentials.py` is imported || Trigger registry + filter builders | `event_waiter.TRIGGER_REGISTRY`, `FILTER_BUILDERS` | back-fill from `TriggerNode` subclasses on first lookup || Temporal activity wrapper | `cls.as_activity()` | first call; pooled into the worker queue declared by `task_queue` |-| Palette icon | `<plugin_folder>/meta.json` → `"icons": {"<nodeType>": "lucide:Send"}` (preferred — no artwork to vendor), or `icon.svg` / `icon_<nodeType>.svg` served via `GET /api/schemas/nodes/<type>/icon` when a brand mark is needed. Resolution: SVG file → plugin `meta.json` ref → `visuals.json`. |+| Palette icon | `<plugin_folder>/icon.svg`, or `icon_<nodeType>.svg` per node type in a multi-node folder — served via `GET /api/schemas/nodes/<type>/icon`. Brand artwork belongs here. `meta.json` → `"icons": {"<nodeType>": "lucide:Send"}` is the fallback for generic utility nodes. Resolution: SVG file → plugin `meta.json` ref → `visuals.json`. || Palette color | `<plugin_folder>/meta.json` (`{"color": "#xxx"}`); `visuals.json` is the fallback for legacy entries (post-F2 it has zero color fields). |What you **do** still write:-- A `meta.json` inside the plugin folder carrying `{"color": "#xxx"}` and, preferably, the icon as a library reference: `"icons": {"<nodeType>": "lucide:Send"}` per node type, or `"icon"` for one glyph across the folder. Use the library's **export** name (`lucide:CheckCheck`), not its kebab-case file name — the lookup is against package exports, and a miss renders nothing rather than erroring. Locked by `client/src/assets/icons/index.test.ts`.-- `icon.svg` (or `icon_<nodeType>.svg` for multi-node folders) only when the node needs artwork no library has — typically a brand mark. A file beats a `meta.json` ref, so shipping both makes the ref dead. The class-attribute icon/color override was removed in F1 — declaring `icon` or `color` as class attrs has no effect.+- `icon.svg` (or `icon_<nodeType>.svg` per node type in a multi-node folder) plus a `meta.json` carrying `{"color": "#xxx"}`. **Ship the brand mark** when the node wraps a recognisable product — that is what makes it identifiable on the canvas, and it has no external dependency. The class-attribute icon/color override was removed in F1 — declaring `icon` or `color` as class attrs has no effect.+- A library reference in `meta.json` — `"icons": {"<nodeType>": "lucide:Send"}` per node type, or `"icon"` folder-wide — for generic utility nodes with no brand of their own. Use the library's **export** name (`lucide:CheckCheck`), not its kebab-case file name; the lookup is against package exports and a miss renders nothing rather than erroring (locked by `client/src/assets/icons/index.test.ts`). Weigh it knowing the name is a third-party export that can disappear on upgrade, and the glyph is monochrome `currentColor` line art. A file beats a ref, so shipping both makes the ref dead.- An entry in `server/nodes/visuals.json` is the legacy central fallback, for plugins with neither of the above. Post-F1/F7 it carries zero `asset:<key>` values.- A **lowercase alias entry in `visuals.json` keyed by the LLM `tool_name`** whenever you set `tool_name` to something other than `<snake_case_of_node_type>` AND ship a paired skill. The skill icon resolver maps the SKILL.md `allowed-tools` token (= the tool name) through snake→camel into `visuals.json`; a custom tool name misses the node-type key and the Master Skill row renders a blank icon. The alias carries the same icon plus the plugin's `meta.json` color — precedent: `"github": {"icon": "lobehub:Github", "color": "#8250df"}`, `"vercel": {"icon": "lobehub:Vercel", "color": "#666666"}`. Locked by `server/tests/test_skill_icon_resolution.py`.- An entry in `server/nodes/groups.py` if you introduce a new palette group.diff --git a/docs-internal/plugin_system.md b/docs-internal/plugin_system.mdindex e30fb84e..bee3b903 100644--- a/docs-internal/plugin_system.md+++ b/docs-internal/plugin_system.md@@ -66,7 +66,7 @@ class SpecializedAgentBase(ActionNode, abstract=True):| `type` | Node type string. Matches workflow JSON + registry key. || `version` | Int, bumped on breaking changes. Activity name includes it. || `display_name` / `subtitle` / `description` | Palette + panel header. |-| *(icon / color)* | **Not class attributes** (removed in F1 — declaring them has no effect). Icon resolves co-located `icon.svg` / `icon_<nodeType>.svg` → the plugin's own `meta.json` (`"icons": {"<nodeType>": "lucide:Send"}`, or folder-wide `"icon"`) → `visuals.json`. Prefer the `meta.json` ref: it reuses a library the frontend already bundles, so there is no artwork to vendor. Color: co-located `meta.json` `{"color": "#..."}`. Wire format on the NodeSpec stays `asset:<key>` / `<lib>:<brand>` / URL / emoji. |+| *(icon / color)* | **Not class attributes** (removed in F1 — declaring them has no effect). Icon resolves co-located `icon.svg` / `icon_<nodeType>.svg` → the plugin's own `meta.json` (`"icons": {"<nodeType>": "lucide:Send"}`, or folder-wide `"icon"`) → `visuals.json`. Ship the SVG when the node has a brand mark; the `meta.json` ref is for generic utility nodes, and carries the risk that a third-party export name disappears on upgrade and the node then renders nothing. Color: co-located `meta.json` `{"color": "#..."}`. Wire format on the NodeSpec stays `asset:<key>` / `<lib>:<brand>` / URL / emoji. || `group` | Tuple of palette groupings (first is primary). || `component_kind` | Frontend dispatch: `square` / `trigger` / `agent` / `tool` / `model` / `start` / `generic`. || `handles` | React Flow handle topology (`input-main`, `output-main`, …). |diff --git a/docs-internal/whatsapp_business_service.md b/docs-internal/whatsapp_business_service.mdindex dd74ef07..235347ae 100644--- a/docs-internal/whatsapp_business_service.md+++ b/docs-internal/whatsapp_business_service.md@@ -116,21 +116,36 @@ because `NodeUserError` is on the framework's non-retryable list:## Icons-All four node icons are **library references declared in the plugin's own-`meta.json`**, not vendored SVGs:--```json-{"color": "#128C7E",- "icons": {"whatsappBusinessSend": "lucide:Send",- "whatsappBusinessMedia": "lucide:Paperclip",- "whatsappBusinessReceive": "lucide:Inbox",- "whatsappBusinessStatus": "lucide:CheckCheck"}}-```--`CheckCheck` is WhatsApp's own delivery tick. `whatsapp_business.svg` remains as-the *credential* brand mark — it resolves through `Credential.get_icon_path`,-a different chain, and no library has an equivalent. See-[plugin_system.md](./plugin_system.md) for the resolution order.+Each node ships its own `icon_<nodeType>.svg` in the plugin folder: **one bold+purpose-built glyph** — paper plane, inbound arrow into a tray, double tick,+photo — painted in WhatsApp green `#25D366` with `#128C7E` for depth. The+brand comes through the **colour**, not the mark.++Canvas nodes render these at roughly 28px, which is the constraint that+decided the design. Three earlier attempts each failed at that size and are+worth recording, because all three look reasonable in the abstract:++- **One shared `icon.svg`.** A folder icon satisfies every node type in that+ folder, so Media, Receive and Status all rendered the same glyph and only+ Send — which happened to have a per-node file — looked different.+- **`lucide:` references in `meta.json`.** No artwork to vendor, but lucide+ glyphs are monochrome `currentColor` line art and rendered as washed-out+ grey. The reference is also a hard dependency on a third-party export name+ that can be renamed or removed, and the failure mode is a node that renders+ nothing rather than an error.+- **The real WhatsApp logo plus a corner badge.** Unmistakably branded, but+ the composition needs the logo scaled to ~80% to make room, and the badge+ glyph then lands at ~10px where a photo or paper plane is unreadable. Two+ competing shapes in one 28px box is one too many.++`whatsapp_business.svg` is separate and stays: it is the *credential* brand+mark and resolves through `Credential.get_icon_path`, a different chain.++`test_whatsapp_business.py::TestEachNodeShipsItsOwnBrandedIcon` asserts each+node type resolves to a distinct file, that every icon parses as XML and+embeds the authentic mark in brand green, and that no folder-level `icon.svg`+reappears to shadow them. See [plugin_system.md](./plugin_system.md) for the+resolution order.## Gotchas worth knowing before editingdiff --git a/server/nodes/README.md b/server/nodes/README.mdindex 17df18b3..f9bd9396 100644--- a/server/nodes/README.md+++ b/server/nodes/README.md@@ -44,16 +44,18 @@ class AcmeOutput(BaseModel):# 4. The node. (Icon + color are NOT declared on the class.-# Icon: prefer a library glyph over vendored artwork — add-# `"icons": {"<nodeType>": "lucide:Send"}` to THIS folder's-# meta.json (or `"icon"` for one glyph across the folder).-# Use `lucide:<ExportName>` (`CheckCheck`, NOT `check-check` —-# lookup is on the package's exports) or `lobehub:<brand>`.-# Ship `icon.svg` only for artwork no library has, typically a-# brand mark; `icon_<nodeType>.svg` for per-node artwork in-# multi-node folders. A file always beats a meta.json ref, so-# don't ship both. `server/nodes/visuals.json` is the legacy-# central registry for plugins with neither.+# Icon: for anything with a recognisable brand, drop the mark as+# `icon.svg` in THIS folder, or `icon_<nodeType>.svg` per node+# type in a multi-node folder. Brand artwork is what makes a node+# identifiable at canvas size and depends on nothing external.+# For generic utility nodes, meta.json can instead reference a+# library glyph: `"icons": {"<nodeType>": "lucide:Send"}` (use+# the package's ExportName — `CheckCheck`, NOT `check-check`).+# That is the weaker option: the name can be renamed or removed+# upstream and the node then renders nothing, and the glyph is+# monochrome currentColor line art. A file always beats a+# meta.json ref, so don't ship both. `server/nodes/visuals.json`+# is the legacy central registry for plugins with neither.# Color: create `meta.json` with `{"color": "#abcdef"}` in this folder.# BaseNode._metadata_dict resolves both at registration time via the# central handler at server/nodes/_visuals.py.)diff --git a/server/nodes/whatsapp_business/icon_whatsappBusinessMedia.svg b/server/nodes/whatsapp_business/icon_whatsappBusinessMedia.svgnew file mode 100644index 00000000..3d5e6c2f--- /dev/null+++ b/server/nodes/whatsapp_business/icon_whatsappBusinessMedia.svg@@ -0,0 +1 @@+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><rect x="2.3" y="4.5" width="19.4" height="15" rx="2.7" fill="#25D366"/><circle cx="8.2" cy="9.9" r="1.95" fill="#fff"/><path fill="#fff" d="m4.4 18 5-5.6 3.2 3.5 2.9-3.1 4.1 5.2z"/></svg>diff --git a/server/nodes/whatsapp_business/icon_whatsappBusinessReceive.svg b/server/nodes/whatsapp_business/icon_whatsappBusinessReceive.svgnew file mode 100644index 00000000..3a3bd15e--- /dev/null+++ b/server/nodes/whatsapp_business/icon_whatsappBusinessReceive.svg@@ -0,0 +1 @@+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path fill="#25D366" d="M10.4 2.6h3.2v7.1h4L12 16.4 6.4 9.7h4z"/><path fill="#128C7E" d="M2.9 14.3h4.9a4.5 4.5 0 0 0 8.4 0h4.9v4.1a3 3 0 0 1-3 3H5.9a3 3 0 0 1-3-3z"/></svg>diff --git a/server/nodes/whatsapp_business/icon_whatsappBusinessSend.svg b/server/nodes/whatsapp_business/icon_whatsappBusinessSend.svgnew file mode 100644index 00000000..eb560015--- /dev/null+++ b/server/nodes/whatsapp_business/icon_whatsappBusinessSend.svg@@ -0,0 +1 @@+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path fill="#25D366" d="M2.3 20.7 22 12 2.3 3.3v6.8L16.4 12 2.3 13.9z"/></svg>diff --git a/server/nodes/whatsapp_business/icon_whatsappBusinessStatus.svg b/server/nodes/whatsapp_business/icon_whatsappBusinessStatus.svgnew file mode 100644index 00000000..8e968d2b--- /dev/null+++ b/server/nodes/whatsapp_business/icon_whatsappBusinessStatus.svg@@ -0,0 +1 @@+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke-width="2.6" stroke-linecap="round" stroke-linejoin="round"><path stroke="#128C7E" d="m1.8 12.9 4.3 4.3 8.4-9.8"/><path stroke="#25D366" d="m9.5 17.2 8.4-9.8"/></svg>diff --git a/server/nodes/whatsapp_business/meta.json b/server/nodes/whatsapp_business/meta.jsonindex 6128e276..550bea1d 100644--- a/server/nodes/whatsapp_business/meta.json+++ b/server/nodes/whatsapp_business/meta.json@@ -1,9 +1 @@-{- "color": "#128C7E",- "icons": {- "whatsappBusinessSend": "lucide:Send",- "whatsappBusinessMedia": "lucide:Paperclip",- "whatsappBusinessReceive": "lucide:Inbox",- "whatsappBusinessStatus": "lucide:CheckCheck"- }-}+{"color": "#128C7E"}diff --git a/server/tests/nodes/test_whatsapp_business.py b/server/tests/nodes/test_whatsapp_business.pyindex ecf1cf9a..d25cef57 100644--- a/server/tests/nodes/test_whatsapp_business.py+++ b/server/tests/nodes/test_whatsapp_business.py@@ -423,35 +423,81 @@ class TestRunAndDeployAgreeOnOutputShape:assert "_WhatsAppBusinessTrigger" not in NODE_METADATA-class TestIconsComeFromTheLibraryNotVendoredArtwork:- def test_each_node_type_gets_a_distinct_icon(self):- """All four rendered the same glyph before: only Send shipped a- per-node SVG, so the rest fell back to the folder's shared one."""- from services.node_spec import get_node_spec+_NODE_TYPES = (+ "whatsappBusinessSend",+ "whatsappBusinessMedia",+ "whatsappBusinessReceive",+ "whatsappBusinessStatus",+)- icons = {}- for node_type in (- "whatsappBusinessSend",- "whatsappBusinessMedia",- "whatsappBusinessReceive",- "whatsappBusinessStatus",- ):- spec = get_node_spec(node_type)- data = spec if isinstance(spec, dict) else spec.model_dump(mode="json")- icons[node_type] = data["icon"]- assert all(icon.startswith("lucide:") for icon in icons.values())- assert len(set(icons.values())) == len(icons)+class TestEachNodeShipsItsOwnBrandedIcon:+ """All four rendered the same glyph before: only Send had a per-node+ SVG, so the rest fell back to the folder's shared one.++ They are brand artwork rather than a library reference on purpose. A+ `lucide:<Name>` string is a hard dependency on a third-party export+ that can be renamed or dropped, and when that happens the node simply+ renders nothing -- no error. Generated SVGs in the plugin folder have+ no such failure mode, and carry WhatsApp's own green.+ """- def test_no_vendored_node_svgs_remain(self):- """The credential icon stays -- it resolves through a different- chain (Credential.get_icon_path) and is a brand mark lucide has no- equivalent for."""+ def _icon_paths(self):import pathlibfolder = pathlib.Path(__file__).resolve().parents[2] / "nodes" / "whatsapp_business"- svgs = {p.name for p in folder.glob("*.svg")}- assert svgs == {"whatsapp_business.svg"}+ return folder, {p.name for p in folder.glob("*.svg")}++ def test_every_node_type_resolves_to_its_own_file(self):+ from nodes._visuals import get_plugin_icon_path++ paths = {t: get_plugin_icon_path(t) for t in _NODE_TYPES}+ assert all(p is not None for p in paths.values()), paths+ # Distinct files, not four references to one shared icon.+ assert len({str(p) for p in paths.values()}) == len(_NODE_TYPES)++ def test_spec_serves_a_distinct_icon_endpoint_per_node(self):+ from services.node_spec import get_node_spec++ icons = set()+ for node_type in _NODE_TYPES:+ spec = get_node_spec(node_type)+ data = spec if isinstance(spec, dict) else spec.model_dump(mode="json")+ icons.add(data["icon"])+ assert len(icons) == len(_NODE_TYPES)++ def test_icons_are_purpose_glyphs_in_whatsapp_colours(self):+ """One bold glyph per node, painted in WhatsApp green.++ Three earlier attempts failed on the canvas, at roughly 28px:+ monochrome library line art read as washed-out grey; a hand-drawn+ speech bubble did not read as WhatsApp at all; and the real logo+ plus a corner badge left the logo too small and the badge glyph+ illegible. What works is a single purpose-built symbol filling the+ box, carrying the brand through colour rather than the mark.+ """+ import xml.etree.ElementTree as ET++ folder, names = self._icon_paths()+ for name in names - {"whatsapp_business.svg"}:+ body = (folder / name).read_text(encoding="utf-8")+ ET.fromstring(body) # malformed SVG renders as nothing, silently+ assert "#25D366" in body, f"{name} does not use the WhatsApp brand green"+ # The logo belongs to the credential mark, not the node icons:+ # shrinking it to fit a badge is what made these unreadable.+ assert "M17.472 14.382" not in body, f"{name} re-embeds the full logo"++ def test_credential_brand_mark_is_kept(self):+ """It resolves through a different chain (Credential.get_icon_path),+ so it is not interchangeable with the per-node files."""+ _, names = self._icon_paths()+ assert "whatsapp_business.svg" in names++ def test_no_shared_icon_shadows_the_per_node_files(self):+ """A folder-level icon.svg would still be reachable, but its only+ effect here would be to mask a missing per-node file."""+ _, names = self._icon_paths()+ assert "icon.svg" not in namesclass TestFileWidgetVisibility: