Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
docs(plugins): correct dispatch, handles, credentials and visuals docs
trohitg07c8ea99e396
diff --git a/docs-internal/node_allowlist.md b/docs-internal/node_allowlist.mdindex 8d7d9a86..766ad6cc 100644--- a/docs-internal/node_allowlist.md+++ b/docs-internal/node_allowlist.md@@ -111,4 +111,4 @@ Read via `services.node_allowlist.get_node_allowlist_service().get_config()` —## Backend service-`server/services/node_allowlist.py` reads + parses the JSON via the shared `_str_list()` helper that rejects non-string entries. WS handler `get_node_allowlist` returns the full config dict to the frontend; the hook caches via `useRef` so the fetch runs once per session.+`server/services/node_allowlist.py` reads + parses the JSON via the shared `_str_list()` helper that rejects non-string entries. WS handler `get_node_allowlist` returns the full config dict to the frontend. The hook guards with a `useRef` flag held per component instance, so each mounted consumer (`ComponentPalette`, `CredentialsModal`, `MasterSkillEditor`) fetches once per mount; there is no shared cache across them.diff --git a/docs-internal/node_creation.md b/docs-internal/node_creation.mdindex 6f0255e3..a215d4d6 100644--- a/docs-internal/node_creation.md+++ b/docs-internal/node_creation.md@@ -66,8 +66,8 @@ Stripe is the reference implementation```server/nodes/<provider>/-├── __init__.py # 5 register_* calls (zero logic)-├── _credentials.py # ApiKeyCredential subclass+├── __init__.py # register_* calls only (zero logic)+├── _credentials.py # Credential subclass (Stripe: StripeCredential(Credential))├── _source.py # DaemonEventSource + WebhookSource subclasses├── _handlers.py # WS_HANDLERS via make_lifecycle_handlers()├── _install.py # ensure_<provider>_cli() auto-downloader@@ -98,15 +98,19 @@ reused:1. **Marker-token write after CLI login completes.** The pluginwrites synthetic strings to `auth_service.store_oauth_tokens`- with the provider id matching the catalogue entry's key. CLI-managed- providers set **no** `status_hook` — the catalogue handler at- [`server/routers/websocket.py:handle_get_credential_catalogue`](../server/routers/websocket.py)- resolves them through its `kind == "oauth"` fallback, which keys+ with the provider id matching the catalogue entry's key. Stripe,+ Vercel and GitHub set **no** `status_hook`, so+ `provider_connection_state` in+ [`server/services/credential_registry.py`](../server/services/credential_registry.py)+ (which the catalogue handler calls) resolves them through its+ `kind == "oauth"` branch, which keys`auth_service.get_oauth_tokens(provider_id) is not None` off the- provider id directly to set `provider.stored = true` (the- `status_hook` branch is only for providers that declare one:- google / twitter / telegram). **Same storage API path Google's- OAuth callback uses** — no new abstraction.+ provider id directly to set `provider.stored = true`. The order is+ `stored_check`, then `status_hook`, then `kind`, then+ `connected_check`; the providers that declare a `status_hook` are+ listed in `server/config/credential_providers.json` (the+ `claude_code` / `codex_cli` CLI entries among them). **Same storage+ API path Google's OAuth callback uses** — no new abstraction.```pythonawait auth_service.store_oauth_tokens(@@ -135,8 +139,10 @@ reused:3. **Auto-installer for the CLI binary.** Plugins that wrap a CLIship a `_install.py` with a single `ensure_stripe_cli()`-shapedasync helper:- - Cached path → system PATH (`brew`, `scoop`, `apt`) → workspace- cache → fresh download from GitHub releases.+ - Cached path → system PATH (`brew`, `scoop`, `apt`) → a previous+ download under `<DATA_DIR>/packages/<provider>/bin/`+ (`core.paths.package_dir`) → fresh download from GitHub releases+ into that same directory.- Pinned version constant; `(system, machine) -> asset_name` mapcovering Windows/Linux/Mac × x86_64/arm64.- Returns absolute binary path; subsequent calls hit the cache.@@ -233,7 +239,7 @@ walker does on startup), these registrations happen automatically:| 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>/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). |+| Palette color | `<plugin_folder>/meta.json` (`{"color": "#xxx"}`); `visuals.json` is the fallback for legacy entries. Its only `color` fields are on the lowercase tool-name alias keys (`github`, `vercel`, `gcloud`, `cloudflare`, `data`, `vision`) that the skill icon resolver reads — see below. |What you **do** still write:diff --git a/docs-internal/plugin_system.md b/docs-internal/plugin_system.mdindex 8593658d..8f671673 100644--- a/docs-internal/plugin_system.md+++ b/docs-internal/plugin_system.md@@ -77,7 +77,7 @@ class SpecializedAgentBase(ActionNode, abstract=True):| `credentials` | Sequence of `Credential` subclasses the node uses. More than one is supported — see [Multi-credential nodes](#multi-credential-nodes). || `Params` | Pydantic `BaseModel` — user-facing parameters. Used for both UI rendering and AI tool schemas. || `Output` | Pydantic `BaseModel` — runtime output shape. |-| `usable_as_tool` | `ActionNode` flag — mints a ToolNode adapter for AI invocation. Combined with `component_kind != "model"`, makes the plugin visible to `agentBuilder.add_tool` (catalogue + rebind paths). **Side effect:** setting it auto-sets `hide_input_handle` / `hide_output_handle` to `True` unless the class declares them (`BaseNode.__init_subclass__` in [base.py](../server/services/plugin/base.py), which does the same for `component_kind == "tool"`), so a dual-purpose node that must remain wirable on the canvas has to declare both `False` explicitly. |+| `usable_as_tool` | `ActionNode` flag — mints a ToolNode adapter for AI invocation. Combined with `component_kind != "model"`, makes the plugin visible to `agentBuilder.add_tool` (catalogue + rebind paths). **Side effect:** setting it auto-sets `hide_input_handle` / `hide_output_handle` to `True` unless the class declares them (`BaseNode.__init_subclass__` in [base.py](../server/services/plugin/base.py), which does the same for `component_kind == "tool"`), and `_metadata_dict` adds an `output-tool` handle. The frontend (`SquareNode`) reads the hide flags only when a spec declares no handles; a spec with handles renders exactly what it declares. So a dual-purpose node that must stay wirable on the canvas declares `input-main` / `output-main` in `handles`; setting the flags `False` alone does not add them. || `needs_canvas` | `ClassVar[bool]` — when `True`, the F4.B `AgentWorkflow` tool-dispatch forwards the parent workflow's `nodes`/`edges` into the per-tool activity payload. Today only `AgentBuilderNode` opts in (walks edges to resolve its calling agent). || `task_queue` | Temporal worker pool. See `TaskQueue` constants. || `retry_policy` | `RetryPolicy` dataclass (mirrors `temporalio.common.RetryPolicy`). |@@ -574,7 +574,7 @@ Underscore-prefixed files are package-private; the `nodes` walkerskips them. The two non-underscore `.py` files are the plugin classes(one per node type) — same pattern as every other folder.-### Cross-cutting registries (19 at time of writing, hand-curated below; `grep -rn '^def register_' server/services server/core` also lists the node / group / provider / session-pool registration internals) — use only what your plugin needs+### Cross-cutting registries (hand-curated below; `grep -rn '^def register_' server/services server/core` lists the live set, plus the node / group / provider / session-pool registration internals) — use only what your plugin needs| Concern | Registry module | Register from plugin via ||---|---|---|@@ -601,10 +601,10 @@ skips them. The two non-underscore `.py` files are the plugin classesAll accept idempotent re-imports (same callable / class for thesame key is a no-op; conflicts raise `ValueError`).-**Plugins use only the registries they need.** Telegram uses 7 (no-router); Stripe uses 4 (webhook-driven, no filter/precheck); Android-uses 6 (with router); WhatsApp uses 8. There is no "register every-hook" rule.+**Plugins use only the registries they need.** Telegram registers no+router; Stripe is webhook-driven, with no filter or precheck; Android+registers a router. There is no "register every hook" rule — read a+plugin's `__init__.py` for what it actually registers.### Telegram `__init__.py` (canonical wiring)@@ -1300,20 +1300,23 @@ without any node-specific code in the frontend or in core services:1. **Marker-token write via the existing `auth_service.store_oauth_tokens`API.** Plugin writes synthetic strings (e.g. `"cli-managed"`) on- login completion. The catalogue's existing per-provider `stored`- check at- [`routers/websocket.py:handle_get_credential_catalogue`](../server/routers/websocket.py)- uses- `auth_service.get_oauth_tokens(status_hook) is not None` —- identical to Google's OAuth-callback path. The synthetic tokens- exist purely to flip the existence check; the CLI owns the real- auth.+ login completion. The catalogue's per-provider `stored` flag comes+ from `provider_connection_state` in+ [`services/credential_registry.py`](../server/services/credential_registry.py)+ (called by `handle_get_credential_catalogue` and by the Normal-mode+ employee summaries). It checks, in order: a declarative+ `stored_check`, then `status_hook`+ (`auth_service.get_oauth_tokens(status_hook) is not None` —+ identical to Google's OAuth-callback path), then the provider+ `kind` (`apiKey` / `oauth`), then `connected_check`. The synthetic+ tokens exist purely to flip that existence check; the CLI owns the+ real auth.2. **Generic `credential_catalogue_updated` broadcast.** The pluginemits this event after every state change. The frontend'sexisting handler in[`WebSocketContext.tsx`](../client/src/contexts/WebSocketContext.tsx)- (`case 'credential_catalogue_updated'`, line 1007) invalidates the catalogue query; the modal refetches+ (`case 'credential_catalogue_updated'`) invalidates the catalogue query; the modal refetchesand re-renders. **No new broadcast type, no Zustand entry, no`case '<provider>_status'`.** Frontend has zero references to anyCLI-managed plugin's name.diff --git a/docs-internal/tool_building_pipeline.md b/docs-internal/tool_building_pipeline.mdindex bb0a601a..f85e5d90 100644--- a/docs-internal/tool_building_pipeline.md+++ b/docs-internal/tool_building_pipeline.md@@ -161,7 +161,7 @@ tool or crashing.## 6. Stage 5 — Dispatch (handlers/tools.py)-[`execute_tool(tool_name, tool_args, config)`](../server/services/handlers/tools.py#L75) at line 75:+[`execute_tool(tool_name, tool_args, config)`](../server/services/handlers/tools.py) in `services/handlers/tools.py`:```python1. broadcaster.update_node_status(node_id, "executing", ...)@@ -173,17 +173,16 @@ tool or crashing.4. Return result. Exceptions trigger an "error" broadcast and re-raise.```-[`_dispatch_tool`](../server/services/handlers/tools.py#L146) at line 146 is pure routing — no broadcasting. Routes by `config["node_type"]`:+[`_dispatch_tool`](../server/services/handlers/tools.py) is pure routing — no broadcasting. It checks `config["node_type"]` in this order:-| Pattern | Handler |-|---|---|-| `aiAgent` / `chatAgent` / `<specialized>_agent` | `_execute_delegated_agent` (fire-and-forget background task) |-| `_builtin_check_delegated_tasks` | `_execute_check_delegated_tasks` |-| `batteryMonitor` / `wifiAutomation` / ... (16 service types) | `nodes/android/_base.py::execute_android_service_tool` (line 248; imported at `tools.py:227` — snake_case service ID via `SERVICE_ID_MAP` at `_base.py:25`) |-| `whatsappSend` / `whatsappDb` / `pythonExecutor` / ... | Per-plugin `usable_as_tool=True` handler (the plugin's own `execute()` method) |-| `calculatorTool` / `currentTimeTool` / `taskManager` / `writeTodos` | `_execute_<name>` direct implementations |-| `braveSearch` / `serperSearch` / `perplexitySearch` | `handle_<provider>_search` (httpx async, credential resolution, usage tracking) |-| All else | `_execute_generic` (catch-all) |+| Order | Pattern | Handler |+|---|---|---|+| 1 | `_builtin_skill` | `services.skill_runtime.execute_skill_tool` |+| 2 | Any registered plugin that is not a registered agent (`get_node_class(node_type)`) | The plugin fast path: `plugin_cls().execute_as_tool(tool_args, node_params, ctx)`. This covers every tool plugin, dual-purpose `usable_as_tool` nodes, the Android services, `taskManager` and `proxyConfig`. A plugin that needs to adjust the model's arguments overrides `execute_as_tool` (see §12). |+| 3 | `ANDROID_SERVICE_NODE_TYPES`, `taskManager`, `proxyConfig` | Legacy branches (`execute_android_service_tool`, `_execute_task_manager`, `execute_proxy_config`). Each of these types is a registered plugin, so step 2 handles it first and these branches are not reached today. |+| 4 | `_builtin_check_delegated_tasks` | `_execute_check_delegated_tasks` |+| 5 | A registered agent (`is_registered_agent`: `AI_AGENT_TYPES` or `supports_delegation`) | `_execute_delegated_agent` (fire-and-forget background task) |+| 6 | Anything else | `_execute_generic` (catch-all, logs a warning) |## 7. Gateway-tool pattern (retired)@@ -196,7 +195,7 @@ connect directly to `input-tools`. Legacy`services/workflow_migrations.normalize_legacy_android_toolkit`, and sub-nodeexclusion keys solely on the AI-agent config handles (`input-context` /`input-memory` (legacy compatibility) / `input-tools` / `input-skill` /-`input-teammates`; `execution/models.py:351-359`) — the+`input-teammates`; `ExecutionContext.create` in `execution/models.py`) — the`TOOLKIT_NODE_TYPES` constant is gone.## 8. Internal delegation identities (`delegate_to_*`)@@ -214,7 +213,7 @@ class DelegateToAgentSchema(BaseModel):context: Optional[str] = None```-[`_execute_delegated_agent`](../server/services/handlers/tools.py#L314) at line 314:+[`_execute_delegated_agent`](../server/services/handlers/tools.py) in `services/handlers/tools.py`:1. Generate a `task_id` (`uuid4().hex`).2. Spawn `asyncio.create_task(<child agent execute>)` — fire and forget.@@ -252,7 +251,7 @@ The v1/v2 wire duality was purged; there is no engine-marker refusal path.Some tools bundle a default skill — `writeTodos` ships with `write-todos-skill`, the WhatsApp tools ship with their respective skills. The frontend `useAutoSkillEdges.ts` hook detects these connections at canvas-edit time and auto-creates a phantom skill connection so the LLM gets both the tool schema (for invocation) and the skill instructions (for usage guidance) without the user having to wire two edges.-The `isMasterSkillNode()` helper (`useAutoSkillEdges.ts:35`) resolves via `getCachedNodeSpec(type)?.uiHints?.isMasterSkillEditor === true`, not a hardcoded string match.+The `isMasterSkillNode()` helper in `useAutoSkillEdges.ts` resolves via `getCachedNodeSpec(type)?.uiHints?.isMasterSkillEditor === true`, not a hardcoded string match.## 11. Pytest invariants@@ -271,14 +270,17 @@ server/tests/The shortest path:1. Create the plugin folder: `server/nodes/tool/<plugin>/__init__.py` extending `ToolNode` (or `ActionNode` with `usable_as_tool = True` for dual-purpose).-2. Declare `type`, `display_name`, `Params` (the schema the LLM sees), `Output`, `@Operation`-decorated `execute()`.+2. Declare `type`, `display_name`, `Params` (the schema the LLM sees), `Output`, and an `@Operation`-decorated method (for example `@Operation("search") async def search(self, ctx, params)`); `BaseNode.execute` and `execute_as_tool` dispatch to it.3. Declare the plugin's `tool_name` and, when the LLM-facing wording differs,`tool_description` class variables.4. (Optional) Add a special schema clause to `_get_tool_schema` only when theplugin's `Params` model is not the correct invocation contract.-5. (Optional) Add a dispatch clause to `_dispatch_tool` if your plugin needs- custom handler logic; otherwise the generic per-plugin path runs- `cls.execute()` directly.+5. (Optional) Override `execute_as_tool` on the plugin class when the+ model's arguments need adjusting before the operation runs —+ `AccountScopedNode` in `nodes/discord/_base.py` strips its+ `server_controlled_fields` this way. Do not add a clause to+ `_dispatch_tool`: its plugin fast path already runs `execute_as_tool`+ for every registered plugin.Steps 4-5 are usually unnecessary — most new tools are fully described bytheir plugin class.diff --git a/server/nodes/README.md b/server/nodes/README.mdindex 5fbcceee..ac848651 100644--- a/server/nodes/README.md+++ b/server/nodes/README.md@@ -94,9 +94,13 @@ class AcmeSearchNode(ActionNode):```On server restart this node is:-- in the Component Palette under `search` and `tool`+- in the Component Palette under `search` (the palette files a node under+ the first entry of `group` only; later entries still count for group+ checks such as `isConfigNode`)- runnable via the run button (REST API worker pool)-- invokable by any AI Agent connected to its `output-main`+- invokable by any AI Agent wired to its `output-tool` handle, which+ `usable_as_tool = True` adds to the NodeSpec automatically (connect it to+ the agent's `input-tools`)- emitted as NodeSpec at `GET /api/schemas/nodes/acmeSearch/spec.json`No other edits. Zero frontend changes.@@ -150,7 +154,7 @@ tool/ — calculatorTool / currentTimeTool / writeTodos / taskManager / svision/ — visionAnalyze (vision-delegate AI tool; palette group "tool")context/ — context (RFC-0002 conversation-store opt-in + viewing panel; palette group "memory")utility/ — console / httpRequest / webhookResponse / processManager / team_monitor-workflow/ — start+workflow/ — start / approvalGate ("ask me before sending")skill/ — masterSkill (skill/simple_memory is only an import shim for tool/simple_memory)browser/ — browser (installed Chrome/Edge/Chromium + browser-use CLI; Chrome for Testing opt-in, profiles, live view and user takeover)stripe/ — Stripe (CLI passthrough action + signed-webhook trigger)@@ -181,15 +185,15 @@ these first before writing new code:| Folder | Helper | Purpose ||---|---|---|| `agent/` | `_inline.prepare_agent_call` | One-shot pre-dispatch for every agent (memory + skill + tool + teammate collection) |-| `agent/` | `_specialized.SpecializedAgentBase` | Base for 13 specialized agents |-| `model/` | `_base.ChatModelBase` | 13 chat models inherit → same `@Operation("chat")` body that calls `ai_service.execute_chat` |+| `agent/` | `_specialized.SpecializedAgentBase` | Base for the specialized agents |+| `model/` | `_base.ChatModelBase` | The chat models inherit → same `@Operation("chat")` body that calls `ai_service.execute_chat` || `speech/` + `translate/` | `_config` / `_registry` / `_unifier` / `_providers/` | The multi-vendor shape. Capability data is JSON (`services/plugin/capabilities.CapabilityConfig`), registration is `services/provider_registry`, and each `_providers/<vendor>.py` owns that vendor's auth scheme, request transport and response shape |-| `android/` | `_base.AndroidServiceBase` | 16 Android services inherit; payload translation + `SERVICE_ID_MAP` lives on this base |-| `android/` | `_base.execute_android_service_tool` | AI-tool dispatcher — called from `services/handlers/tools.py` for direct service tools (the `androidTool` aggregator + `execute_android_toolkit` were retired) |+| `android/` | `_base.AndroidServiceBase` | The Android services inherit; payload translation + `SERVICE_ID_MAP` lives on this base |+| `android/` | `_base.execute_android_service_tool` | Legacy AI-tool dispatcher. `services/handlers/tools.py` still has an `ANDROID_SERVICE_NODE_TYPES` branch that calls it, but the plugin fast path in `_dispatch_tool` runs first and sends every registered Android service through `BaseNode.execute_as_tool` (its `invoke` operation), so that branch is not reached today (the `androidTool` aggregator + `execute_android_toolkit` were retired) || `code/` | `_base.CodeExecutorBase` + `_nodejs.NodeJSClient` | Python/JS/TS executors; `monty_executor/` is sandboxed Python via `pydantic-monty` (enforced limits + opt-in capabilities) |-| `google/` | `_base.build_google_service` / `track_google_usage` | 7 Google plugins (OAuth + API) |+| `google/` | `_base.build_google_service` / `track_google_usage` | The Google plugins (OAuth + API) || `google/` | `_gmail.fetch_email_details` / `mark_email_as_read` | gmail + gmail_receive |-| `twitter/` | `_base.call_with_retry` / `format_tweet` / `sync_search_recent` | 4 twitter plugins (XDK + refresh) |+| `twitter/` | `_base.call_with_retry` / `format_tweet` / `sync_search_recent` | The twitter plugins (XDK + refresh) || `whatsapp/` | `_base.*` | whatsappSend / whatsappDb (RPC dispatch via `nodes/whatsapp/_service.py` — `RPCClient` + `whatsapp_rpc_call`) || `social/` | `_base.*` | socialReceive / socialSend || `proxy/` | `proxy_config/__init__.py::execute_proxy_config` | 10-operation matrix; called by both `ProxyConfigNode.dispatch` and `tools.py`'s AI-tool branch |@@ -482,11 +486,15 @@ Full reference: [docs-internal/plugin_system.md → "Self-contained plugin folde`AndroidServiceParams._coerce_parameters`, `WriteTodosParams._coerce_todos`.Do **not** blanket-drop blanks for `str` fields — that turns a `min_length`error into a confusing "field required".-- **`usable_as_tool = True` hides both canvas handles.** It auto-sets- `hide_input_handle` / `hide_output_handle` unless the class declares- them, so a dual-purpose node meant to stay wirable must set both to- `False` explicitly. Symptom: the node runs fine as a tool but cannot be- connected to anything on the canvas.+- **Declare the canvas handles a dual-purpose node needs.**+ `usable_as_tool = True` auto-sets `hide_input_handle` /+ `hide_output_handle` unless the class declares them, and adds an+ `output-tool` handle. The frontend only consults the hide flags when a+ spec declares no handles; a spec with handles renders exactly what it+ declares. So a node that should also chain on the canvas must list+ `input-main` / `output-main` in `handles` — declaring the flags `False`+ alone does not add them. (Several nodes also set both flags `False`,+ and their tests lock that.)- **Never accept a file path and join it onto the workspace yourself.**Use `services.media.coerce_file_param` / `read_media_bytes`. A node thatdid the naive join let `audio_file="../../credentials.db"` read thediff --git a/server/nodes/_visuals.py b/server/nodes/_visuals.pyindex 3243fd08..93180d2c 100644--- a/server/nodes/_visuals.py+++ b/server/nodes/_visuals.py@@ -1,11 +1,12 @@"""Central handler for node visuals (icon + color).-Two icon sources co-exist by design (per RFC §6.5):+Three 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``).+1. **Per-plugin ``icon_<node_type>.svg`` / ``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 any node+ with a recognisable brand; served by+ ``GET /api/schemas/nodes/{type}/icon`` (see ``routers/schemas.py``).2. **Per-plugin ``meta.json``** for library references that need noartwork at all — ``{"icons": {"<node_type>": "lucide:Send"}}``.@@ -24,11 +25,15 @@ dispatches by the wire-format prefix (URL paths route to ``<img>``;branch).Adding a new node, in order of preference:-- Declare ``icons`` / ``icon`` in the plugin's ``meta.json`` pointing at- a library glyph (nothing to draw, nothing to maintain), OR-- Drop ``icon.svg`` into the plugin folder when the node needs artwork- a library does not have — typically a brand mark, OR+- Drop ``icon.svg`` (or ``icon_<node_type>.svg``) into the plugin folder+ when the node belongs to a recognisable product — the brand mark is+ what makes it identifiable at canvas size, OR+- For a generic utility node, declare ``icons`` / ``icon`` in the+ plugin's ``meta.json`` pointing at a library glyph. That is the weaker+ option: a renamed or removed export renders nothing, OR- Add an entry to ``visuals.json`` (legacy central registry).+A file always beats a ``meta.json`` reference for every node type in+that folder, so do not ship both.Node files do NOT declare ``icon`` or ``color`` themselves."""@@ -98,8 +103,10 @@ def get_plugin_icon_ref(node_type: str) -> str:SVG on disk. This is its no-file counterpart, so a plugin can point atan icon that already exists in a library instead of vendoring artwork:- {"color": "#128C7E",- "icons": {"whatsappBusinessSend": "lucide:Send"}}+ {"color": "#ffb86c",+ "icons": {"approvalGate": "lucide:ShieldCheck"}}++ (``nodes/workflow/approval_gate/meta.json``.)Two levels, mirroring the ``icon_<node_type>.svg`` / ``icon.svg`` pair:diff --git a/server/nodes/agent/_specialized.py b/server/nodes/agent/_specialized.pyindex abf2f4a0..c07e5be7 100644--- a/server/nodes/agent/_specialized.py+++ b/server/nodes/agent/_specialized.py@@ -1,12 +1,18 @@-"""Specialized agent base — subclass + set 5 attrs to mint a new agent.+"""Specialized agent base — subclass + set a few class attrs to mint a new agent.All specialized agents (android / coding / web / task / social / travel-/ tool / productivity / payments / consumer / autonomous) share the-``handle_chat_agent`` execution path. The only differences are display-name, icon, colour, subtitle, description. Each agent gets its own file-under ``nodes/agent/`` so the user can find ``android_agent.py``-directly — but the body lives here so changing the dispatch path is a-one-file edit.+/ tool / productivity / payments / consumer / autonomous) and the two+team leads (orchestrator_agent / ai_employee) subclass this. In-process+(and on the per-type activity path) they run ``execute_op`` below, which+calls ``AIService.execute_chat_agent``; with the Temporal+``AgentWorkflow`` enabled they run as that child workflow instead+(``AGENT_WORKFLOW_TYPES`` in ``services/temporal/workflow.py``). The+class-level differences are display name, subtitle and description;+icon and colour are not class attributes — they come from the plugin+folder (``icon.svg`` / ``meta.json``) or ``nodes/visuals.json``. Each+agent has its own folder, ``nodes/agent/<type>/__init__.py``, so the+user can find ``android_agent`` directly — but the body lives here so+changing the dispatch path is a one-file edit."""from __future__ import annotations@@ -90,7 +96,8 @@ class SpecializedAgentOutput(BaseModel):class SpecializedAgentBase(ActionNode, abstract=True):- """Subclass and set type/display_name/icon/color/subtitle/description."""+ """Subclass and set type/display_name/subtitle/description (icon and+ colour come from the plugin folder or ``nodes/visuals.json``)."""component_kind = "agent"requires_context = True@@ -106,10 +113,12 @@ class SpecializedAgentBase(ActionNode, abstract=True):async def execute_op(self, ctx: NodeContext, params: SpecializedAgentParams) -> Any:"""Inlined via ``prepare_agent_call`` (Wave 11.D.6).- All 13 specialized agents + orchestrator + ai_employee route- through :func:`AIService.execute_chat_agent` with identical- pre-dispatch flow. Team-lead teammate injection happens inside- ``prepare_agent_call`` based on ``self.type``.+ Every subclass (the specialized agents plus the orchestrator and+ ai_employee team leads) routes through+ :func:`AIService.execute_chat_agent` with identical pre-dispatch+ flow when it runs here rather than as an ``AgentWorkflow``.+ Team-lead teammate injection happens inside ``prepare_agent_call``+ based on ``self.type``."""from services.plugin.deps import get_ai_service, get_databasediff --git a/server/nodes/android/_base.py b/server/nodes/android/_base.pyindex cc03bf54..37ca6d12 100644--- a/server/nodes/android/_base.py+++ b/server/nodes/android/_base.py@@ -90,11 +90,12 @@ class AndroidServiceOutput(BaseModel):class AndroidServiceBase(ActionNode, abstract=True):- """Subclass and set type/display_name/icon/description.+ """Subclass and set type/display_name/description.- Visual metadata (icon + color) lives in ``server/nodes/visuals.json``- keyed by individual plugin type. The ``_visuals.py`` resolver picks- each entry up at NodeSpec emit time; no class-level ClassVars needed.+ Visual metadata is not a class attribute: each service's colour lives+ in its folder's ``meta.json`` and its icon in ``server/nodes/visuals.json``+ keyed by plugin type. ``BaseNode._metadata_dict`` resolves both through+ ``nodes/_visuals.py`` when the NodeSpec is built."""group = ("android", "service")diff --git a/server/nodes/scraper/tikhub_action/__init__.py b/server/nodes/scraper/tikhub_action/__init__.pyindex 570eb180..033fb28d 100644--- a/server/nodes/scraper/tikhub_action/__init__.py+++ b/server/nodes/scraper/tikhub_action/__init__.py@@ -154,8 +154,9 @@ class TikHubActionNode(ActionNode):credentials = (TikHubCredential,)task_queue = TaskQueue.REST_APIusable_as_tool = True- # usable_as_tool auto-hides both handles unless declared; this node- # must stay wirable on the canvas as well as callable as a tool.+ # usable_as_tool auto-sets both hide flags unless declared. This node+ # stays wirable on the canvas through its declared `handles`; the+ # frontend reads the flags only for a spec with no handles.hide_input_handle = Falsehide_output_handle = Falsediff --git a/server/nodes/skill/__init__.py b/server/nodes/skill/__init__.pyindex d1ec88d0..3bb45e59 100644--- a/server/nodes/skill/__init__.py+++ b/server/nodes/skill/__init__.py@@ -2,8 +2,10 @@Self-contained plugin folder. Owns:-- ``master_skill.py`` -- the :class:`MasterSkillNode` plugin.-- ``simple_memory.py`` -- the :class:`SimpleMemoryNode` plugin.+- ``master_skill/`` -- the :class:`MasterSkillNode` plugin (plus its+ ``_events.py`` skill-lifecycle broadcasts).+- ``simple_memory/`` -- only a compatibility import for older paths; the+ Memory tool plugin itself lives in ``nodes/tool/simple_memory/``.- ``_expander.py`` -- Master-Skill expansion callback registered with:func:`services.plugin.edge_walker.register_master_skill_expander`so the framework-side edge walker doesn't need to know aboutdiff --git a/server/nodes/speech/text_to_speech.py b/server/nodes/speech/text_to_speech.pyindex 5833b05f..18dcacd0 100644--- a/server/nodes/speech/text_to_speech.py+++ b/server/nodes/speech/text_to_speech.py@@ -183,8 +183,9 @@ class TextToSpeechNode(ActionNode):annotations = {"destructive": False, "readonly": False, "open_world": True}task_queue = TaskQueue.REST_APIusable_as_tool = True- # `usable_as_tool` otherwise auto-hides both handles, which would break- # chaining this into Speech to Text on the canvas.+ # `usable_as_tool` would otherwise auto-set both hide flags. The declared+ # `handles` above are what keep this chainable into Speech to Text on the+ # canvas (the frontend reads the flags only for a spec with no handles).hide_input_handle = Falsehide_output_handle = Falseui_hints = {"outputMode": "audio"}diff --git a/server/nodes/stripe/_install.py b/server/nodes/stripe/_install.pyindex 309d4459..994e9fd9 100644--- a/server/nodes/stripe/_install.py+++ b/server/nodes/stripe/_install.py@@ -76,9 +76,10 @@ async def ensure_stripe_cli() -> Path:1. Cached path from a prior call (in-process).2. ``shutil.which("stripe")`` — system install on PATH.3. Previously-downloaded copy at ``package_dir("stripe")/bin/- stripe[.exe]`` (OS cache, see :func:`core.paths.package_dir`).+ stripe[.exe]`` (``<DATA_DIR>/packages/stripe/bin/``, see+ :func:`core.paths.package_dir`).4. Fresh download from GitHub releases under :data:`_VERSION`- into the same OS-cache directory.+ into the same directory."""global _cached_pathif _cached_path and _cached_path.exists():diff --git a/server/nodes/telegram/__init__.py b/server/nodes/telegram/__init__.pyindex f0813186..87311f79 100644--- a/server/nodes/telegram/__init__.py+++ b/server/nodes/telegram/__init__.py@@ -14,14 +14,16 @@ waiter, trigger handler) read at dispatch time:telegram_send.py workflow ActionNode + AI tooltelegram_receive.py workflow TriggerNode-On import, this package self-registers six callbacks:+On import, this package self-registers:- 1. WS handlers -> services.ws_handler_registry- 2. Event filter -> services.event_waiter.FILTER_BUILDERS- 3. Trigger precheck -> services.event_waiter._TRIGGER_PRECHECKS- 4. Status refresh -> services.status_broadcaster._SERVICE_REFRESH_CALLBACKS- 5. Output schemas -> services.node_output_schemas (telegramReceive + telegramSend)- 6. Canary trigger -> services.deployment.canary_registry (telegramReceive)+ - WS handlers -> services.ws_handler_registry+ - Event filter -> services.event_waiter.FILTER_BUILDERS+ - Trigger precheck -> services.event_waiter._TRIGGER_PRECHECKS+ - Status refresh -> services.status_broadcaster._SERVICE_REFRESH_CALLBACKS+ - Output schemas -> services.node_output_schemas (telegramReceive + telegramSend)+ - Canary trigger -> services.deployment.canary_registry (telegramReceive)+ - Shutdown hook -> services.plugin.shutdown_hooks (disconnects the bot+ so its getUpdates slot is released)Adding a new plugin folder follows the same shape -- consumers do notneed to learn its name.@@ -65,8 +67,10 @@ register_output_schema("telegramSend", TelegramSendOutput)# Wave 12 C1 rollout #3: opt telegramReceive into the# TriggerListenerWorkflow consumer path. Producer side:# dispatch_telegram_message_received calls services.events.dispatch.emit-# unconditionally; emit() is gated by Settings.event_framework_enabled-# so the legacy path stays default. See+# unconditionally. emit() is gated by Settings.event_framework_enabled,+# which defaults on, so this canary path is the default. Turning the flag+# off does not restore a legacy path (nothing else dispatches telegram+# messages); see docs-internal/event_framework.md and# services/deployment/canary_registry.py.register_canary_trigger_type(TelegramReceiveNode.type, "com.opencompany.telegram.message.received")diff --git a/server/nodes/translate/translate_text.py b/server/nodes/translate/translate_text.pyindex b891e065..92cc021a 100644--- a/server/nodes/translate/translate_text.py+++ b/server/nodes/translate/translate_text.py@@ -143,7 +143,8 @@ class TranslateTextNode(ActionNode):annotations = {"destructive": False, "readonly": True, "open_world": True}task_queue = TaskQueue.REST_APIusable_as_tool = True- # `usable_as_tool` otherwise auto-hides both handles.+ # `usable_as_tool` would otherwise auto-set both hide flags; the declared+ # `handles` are what keep the node wirable on the canvas.hide_input_handle = Falsehide_output_handle = Falsediff --git a/server/services/credential_registry.py b/server/services/credential_registry.pyindex 9e1955ec..8f63b13d 100644--- a/server/services/credential_registry.py+++ b/server/services/credential_registry.py@@ -395,8 +395,9 @@ async def provider_connection_state(provider: Dict[str, Any], auth_service: Any)if stored_check and stored_check.get("type") == "api_key":state["stored"] = await auth_service.has_valid_key(stored_check.get("key", pid))elif status_hook:- # Status-hook providers (whatsapp, android, twitter, google,- # claude_code, codex_cli) use OAuth tokens for the connection state.+ # Providers that declare ``status_hook`` in credential_providers.json+ # (the messaging, Google / Microsoft and CLI-login entries among+ # them) use OAuth tokens for the connection state.tokens = await auth_service.get_oauth_tokens(status_hook)state["stored"] = tokens is not Noneelif kind == "apiKey":diff --git a/server/services/node_allowlist.py b/server/services/node_allowlist.pyindex 0b990fa0..dfca2889 100644--- a/server/services/node_allowlist.py+++ b/server/services/node_allowlist.py@@ -29,17 +29,21 @@ class NodeAllowlistService:Response shape:show_all: bool- true -> do not filter the palette; every node is visible- (still subject to disabled_groups + disabled_nodes).- false -> show only node types listed in enabled_nodes.+ true -> enabled_nodes is empty: nothing is filtered+ beyond disabled_groups + disabled_nodes.+ false -> only node types listed in enabled_nodes pass.+ With Normal mode on (the default), that list+ governs what Hire may build (see+ ``is_hire_allowed``), not the editor palette; with+ ``VITE_NORMAL_MODE=false`` it filters the palette's+ Normal setting instead.enabled_nodes: list[str]Only meaningful when show_all is false.disabled_groups: list[str]- Absolute blocklist. A node whose first group matches any- entry here is hidden in BOTH normal and dev mode, even- if listed in enabled_nodes. Use to disable an entire- backend group (e.g. 'android' hides all 16 Android- service nodes).+ Absolute blocklist. A node with ANY group in this list is+ blocked in every mode, even if listed in enabled_nodes.+ Use to disable an entire backend group (e.g. 'android'+ hides the Android service nodes).disabled_nodes: list[str]Absolute blocklist by exact node-type identifier. Samemode-independent enforcement as disabled_groups; use@@ -60,8 +64,8 @@ class NodeAllowlistService:dropdown — every entry hides the matching subfolderunder server/skills/. Use when disabling a featurethat also ships its own skill folder (e.g.- 'android_agent' so users can't see the 12 android-- tied skills when android nodes are disabled).+ 'android_agent' so users can't see the android-tied+ skills when android nodes are disabled).Email has no dedicated skill folder (email-tied skillslive under productivity_agent mixed with GoogleWorkspace) so no email entry is needed.diff --git a/server/services/plugin/base.py b/server/services/plugin/base.pyindex 25a2797c..fb2b80d9 100644--- a/server/services/plugin/base.py+++ b/server/services/plugin/base.py@@ -133,9 +133,12 @@ class BaseNode:``version`` integer, bumped for breaking changes``display_name`` shown in palette + parameter panel header``subtitle`` shown under display_name in the node header- ``icon`` Wave 10.B wire format: "asset:k" / "lobehub:b" / emoji- ``color`` hex or dracula token, e.g. "#bd93f9"- ``group`` palette groupings, e.g. ["search", "tool"]+ (icon / color) NOT class attributes: ``_metadata_dict`` resolves+ them from the plugin folder (``icon_<type>.svg`` /+ ``icon.svg``, then ``meta.json``) with+ ``nodes/visuals.json`` as the legacy fallback+ ``group`` palette groupings, e.g. ["search", "tool"]; the+ palette files the node under the first entry``description`` one-line help``handles`` NodeHandle[] — React Flow topology``visibility`` "all" / "normal" / "dev"@@ -314,9 +317,12 @@ class BaseNode:expected by the existing node_spec emitter.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>``).+ 1. Per-plugin ``icon_<type>.svg`` or ``icon.svg`` co-located with+ the plugin folder — emitted as a fingerprinted URL routed through+ ``GET /api/schemas/nodes/<type>/icon``.+ 2. The plugin's ``meta.json`` icon reference (``icons[<type>]``, then+ ``icon``), e.g. ``lucide:Send``.+ 3. Fallback to ``visuals.json`` (emoji / ``lobehub:<brand>``).Color resolution (per RFC §6.6 / F2):1. Per-plugin ``meta.json`` ``color`` field, co-located with thediff --git a/server/tests/test_node_spec.py b/server/tests/test_node_spec.pyindex 6d9e5c32..7f885973 100644--- a/server/tests/test_node_spec.py+++ b/server/tests/test_node_spec.py@@ -1087,9 +1087,9 @@ class TestPluginContractInvariants:# Exception: tool-oriented nodes (component_kind="tool" pure# ToolNodes, or ActionNode + usable_as_tool=True dual-use nodes)# have hide_output_handle auto-derived True via- # BaseNode.__init_subclass__. Their declared handles tuple still- # carries output-tool / output-main for backend awareness, but- # the SquareNode frontend suppresses the default render. The+ # BaseNode.__init_subclass__. Their declared handles (plus the+ # auto-added output-tool) are what SquareNode renders; it reads the+ # hide flags only for a spec with no handles. The# invariant's original intent was "explicit author intent should# be consistent" — auto-derived is not author intent, so skip# those nodes.