Skip to content

Self-improving AI Employees for everyone

docs(plugins): correct dispatch, handles, credentials and visuals docs

trohitg07c8ea99e396
diff --git a/docs-internal/node_allowlist.md b/docs-internal/node_allowlist.md
index 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.md
index 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 plugin
writes 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.
```python
await auth_service.store_oauth_tokens(
@@ -135,8 +139,10 @@ reused:
3. **Auto-installer for the CLI binary.** Plugins that wrap a CLI
ship a `_install.py` with a single `ensure_stripe_cli()`-shaped
async 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` map
covering 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.md
index 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` walker
skips 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 classes
All accept idempotent re-imports (same callable / class for the
same 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 plugin
emits this event after every state change. The frontend's
existing 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 refetches
and re-renders. **No new broadcast type, no Zustand entry, no
`case '<provider>_status'`.** Frontend has zero references to any
CLI-managed plugin's name.
diff --git a/docs-internal/tool_building_pipeline.md b/docs-internal/tool_building_pipeline.md
index 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`:
```python
1. 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-node
exclusion 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 the
plugin'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 by
their plugin class.
diff --git a/server/nodes/README.md b/server/nodes/README.md
index 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 / s
vision/ — 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 that
did the naive join let `audio_file="../../credentials.db"` read the
diff --git a/server/nodes/_visuals.py b/server/nodes/_visuals.py
index 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 no
artwork 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 at
an 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.py
index 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_database
diff --git a/server/nodes/android/_base.py b/server/nodes/android/_base.py
index 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__.py
index 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_API
usable_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 = False
hide_output_handle = False
diff --git a/server/nodes/skill/__init__.py b/server/nodes/skill/__init__.py
index 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 about
diff --git a/server/nodes/speech/text_to_speech.py b/server/nodes/speech/text_to_speech.py
index 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_API
usable_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 = False
hide_output_handle = False
ui_hints = {"outputMode": "audio"}
diff --git a/server/nodes/stripe/_install.py b/server/nodes/stripe/_install.py
index 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_path
if _cached_path and _cached_path.exists():
diff --git a/server/nodes/telegram/__init__.py b/server/nodes/telegram/__init__.py
index 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 tool
telegram_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 not
need 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.py
index 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_API
usable_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 = False
hide_output_handle = False
diff --git a/server/services/credential_registry.py b/server/services/credential_registry.py
index 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 None
elif kind == "apiKey":
diff --git a/server/services/node_allowlist.py b/server/services/node_allowlist.py
index 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. Same
mode-independent enforcement as disabled_groups; use
@@ -60,8 +64,8 @@ class NodeAllowlistService:
dropdown — every entry hides the matching subfolder
under server/skills/. Use when disabling a feature
that 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 skills
live under productivity_agent mixed with Google
Workspace) so no email entry is needed.
diff --git a/server/services/plugin/base.py b/server/services/plugin/base.py
index 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 the
diff --git a/server/tests/test_node_spec.py b/server/tests/test_node_spec.py
index 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.