Self-improving AI Employees for everyone
server/nodes/ — plugin cookbook
One plugin = one folder (server/nodes/<group>/<name>/__init__.py),
or a single .py file inside a domain folder whose icon/meta are shared
folder-wide (stripe/, telegram/, speech/, ...). Both auto-register
at import time; no other code needs to change.
Full reference: docs-internal/plugin_system.md.
Execution contract: Workflow control and Node creation.
Five-minute recipe
# server/nodes/search/acme_search/__init__.py
from pydantic import BaseModel, ConfigDict, Field
from typing import List, Literal, Optional
from services.plugin import (
ActionNode, ApiKeyCredential, NodeContext, Operation, TaskQueue,
)
# 1. Credential — inline here (single-use) or create a
# server/nodes/search/_credentials.py (the search folder does not
# ship one today) if 2+ plugins will share it.
class AcmeCredential(ApiKeyCredential):
id = "acme"
display_name = "Acme Search"
category = "Search"
key_name = "X-Acme-Token"
key_location = "header"
# 2. Params — user-visible config (UI + LLM tool schema).
# snake_case throughout — field names = JSON Schema keys = UI param keys.
class AcmeParams(BaseModel):
query: str = Field(..., min_length=1)
max_results: int = Field(default=10, ge=1, le=100)
model_config = ConfigDict(extra="ignore")
# 3. Output — runtime result shape.
class AcmeOutput(BaseModel):
results: List[dict] = Field(default_factory=list)
count: int = 0
# 4. The node. (Icon + color are NOT declared on the class.
# 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.)
class AcmeSearchNode(ActionNode):
type = "acmeSearch"
display_name = "Acme Search"
group = ("search", "tool")
description = "Search Acme's web index"
component_kind = "square"
handles = (
{"name": "input-main", "kind": "input", "position": "left",
"label": "Input", "role": "main"},
{"name": "output-main", "kind": "output", "position": "right",
"label": "Output", "role": "main"},
)
credentials = (AcmeCredential,)
task_queue = TaskQueue.REST_API
usable_as_tool = True
Params = AcmeParams
Output = AcmeOutput
@Operation("search")
async def search(self, ctx: NodeContext, params: AcmeParams) -> AcmeOutput:
async with ctx.connection("acme") as conn:
resp = await conn.get(
"https://api.acme.com/search",
params={"q": params.query, "limit": params.max_results},
)
resp.raise_for_status()
data = resp.json()
hits = data.get("hits", [])
return AcmeOutput(results=hits, count=len(hits))
On server restart this node is:
- in the Component Palette under
search(the palette files a node under the first entry ofgrouponly; later entries still count for group checks such asisConfigNode) - runnable via the run button (REST API worker pool)
- invokable by any AI Agent wired to its
output-toolhandle, whichusable_as_tool = Trueadds to the NodeSpec automatically (connect it to the agent'sinput-tools) - emitted as NodeSpec at
GET /api/schemas/nodes/acmeSearch/spec.json
No other edits. Zero frontend changes.
Activity policy and cooperative Stop
Use the existing node declarations instead of introducing plugin-specific
pause state or a checkpoint store. task_queue, start_to_close_timeout,
heartbeat_timeout, and retry_policy live on the node class
(services/plugin/scaling.py). The queue is
used when the execution's frozen worker-pool setting is enabled; with pools
disabled the default worker receives the operation. The in-process executor
does not enforce Temporal Activity policies.
Distributed Browser Activities are an exception to the pool switch: their frozen profile binding selects an owner-specific queue even with worker pools disabled. Each backend runs that worker; generic orchestration workers must exclude Browser Activities. Do not route browser effects onto a generic queue. See Browser deployment.
New deployment generations (execution_control_version=1) record resolved
tool bindings and these policies during agent preparation. Ordinary per-type
agent tools use that recorded policy, including attempt limits and
non-retryable error types. Continue-As-New carries the prepared bindings and
policy rather than reloading a pending tool from edited configuration. Old
histories retain their previous dispatch decisions. A tool call outside a
controlled generation (a manual Run) uses the declared timeout, heartbeat
and retry policy as well, never Temporal's unlimited default retries.
Graph node dispatch has a narrower policy contract: plugin retry and queue declarations apply, but its ordinary Activity starts retain generic 24-hour attempt and 2-minute heartbeat defaults. The existing Workspace-task override uses that plugin's timeout/heartbeat declarations. Test the intended execution path instead of assuming a timeout declaration is honored everywhere.
Stop closes workflow admission before new node/tool/model/poll/compaction work or a child start. An admitted Activity finishes, including configured retries; its result and bookkeeping are retained before Stopped is acknowledged. Resume runs the next pending action in the existing execution. Parallel tools already admitted drain concurrently. A stopped generation can therefore remain Stopping while a long operation or unlimited model retry is outstanding. An opaque CLI or managed-agent invocation has a whole-Activity boundary.
Keep external I/O in regular Activities. Heartbeats support liveness and real operation-specific retry recovery; they do not implement Stop-after-completion. Do not add a generic heartbeat cursor to an HTTP call, subprocess, or provider session that cannot actually resume from that cursor. External side effects still require the plugin's retry/idempotency contract when completion was not yet recorded by Temporal. Independent Workspace tasks and separately approved sends retain their own lifecycle. See Long-running Activity and Python Activity failure detection.
Trigger events and stable IDs
Registered deployed triggers send CloudEvents with dispatch.emit.
WorkflowControlWorkflow owns controlled deployments' definitions and queues;
separate listener/poller workflows remain compatibility paths. Interactive
canvas waits use the in-memory event waiter and have a
known producer delivery gap.
Keep provider event IDs stable across redelivery only when the full identity is available. Telegram uses chat plus message ID, Discord uses separate message and interaction namespaces, and WhatsApp uses direction plus conversation plus message ID. Missing identity leaves the envelope's random fallback in place. Do not substitute a shared fallback key. Exact formats and producer references are in Node creation.
The controller borrows queue/deduplication/carry practices from Temporal's Event Accumulator while processing each admitted event immediately. Pending keys are separate from the bounded recent-key window; overflow restoration and Continue-As-New retain queued work, including Signals arriving during spill awaits. Stopped generations queue accepted events without starting their graph runs. Events use Signals, acknowledged control uses completed Updates, and status uses read-only Queries (Workflow messaging).
Signal acceptance is not a node-completion acknowledgement. The producer's Visibility lookup and signal fan-out remain best effort, so the durable queue guarantee starts after Temporal accepts the Signal. Same-label/type trigger Workflow-ID collisions also remain a known limit; stable provider IDs do not resolve them. See Workflow control for version gates, membership, rollover fences, and operating limits.
Folder map
Match the palette group. Current folders (see
groups.py for the canonical list):
agent/ — AI agents (ai_agent, chat_agent + specialized/variant folders incl. 2 team leads,
CLI agents (claude_code, codex, rlm); SSOT: AI_AGENT_TYPES
in server/constants.py + the folder glob)
model/ — LLM chat models (openai, anthropic, gemini, …, and openai_compatible for
a user-named endpoint); also owns the LLM provider dropdown loaders
android/ — Android device services
google/ — Google Workspace (gmail / calendar / drive / sheets / …)
microsoft/ — Microsoft Graph (Outlook mail / calendar / mail receive; OAuth2, Work/School accounts)
twitter/ — Twitter/X (send / search / user / receive)
telegram/ — Telegram bot (send / receive)
discord/ — Discord bot (send / action / receive / interaction).
Multi-account: _accounts.py maps an account id onto the
session_id credential scope; nothing else knows about it.
whatsapp/ — WhatsApp (send / db / receive)
whatsapp_business/ — Official Meta WhatsApp Business Cloud API (send / media / receive / status).
Distinct from whatsapp/ (personal account over the Go bridge): no shared
node type, credential or palette group.
social/ — Unified social (send / receive). Names no platform: each
plugin registers a _social.py adapter and owns the mapping
onto its own parameter shape.
email/ — IMAP/SMTP via Himalaya CLI
search/ — Web search APIs (brave / serper / perplexity / duckduckgo)
scraper/ — Apify / Crawlee / TikHub (SDK-backed, flattened like a
CLI: list_endpoints + call over resource.method ids)
document/ — RAG pipeline (scrape / download / parse / chunk / embed / store)
code/ — Python / Monty (sandboxed Python) / JS / TS executors
filesystem/ — file_read / file_modify / shell / fs_search / gallery
(gallery is the workspace file explorer; deliberately NOT
usable_as_tool — it carries destructive operations, and
fs_search + file_modify already cover what an agent needs)
proxy/ — Residential proxy (request / config / status)
location/ — Google Maps (create / locations / nearby places)
chat/ — chatSend / chatHistory
text/ — textGenerator / fileHandler
scheduler/ — timer / cron_scheduler
trigger/ — Generic triggers (webhook / task / chat)
tool/ — calculatorTool / currentTimeTool / writeTodos / taskManager / simpleMemory
("Memory") / agentBuilder / canvas / dataSource
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 / 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)
dodo_payments/ — Dodo Payments (dodopayments SDK: payments / subscriptions / customers / refunds /
checkout links / any endpoint via call + list_operations; Standard Webhooks trigger;
palette group "payments")
vercel/ — Vercel (CLI deploy / inspect / list / custom passthrough)
github/ — GitHub (gh CLI: clone / PRs / issues / custom; palette group "vcs")
cloudflare/ — Cloudflare (cf CLI: command search / zones / DNS / GraphQL analytics / custom; palette group "deployment")
gcloud/ — Google Cloud (gcloud CLI: projects / Compute Engine / Cloud Run / Cloud Storage / custom; palette group "deployment")
aws/ — AWS (boto3 SDK: identity / EC2 / S3 / any API operation via call + list_operations; IAM key pair
in the encrypted store; palette group "deployment")
speech/ — Provider-abstracted text_to_speech / speech_to_text (palette group "language").
One node per direction with a `provider` dropdown, not one node per vendor. Owns
its own protocol / registries / dispatch / per-vendor modules — see below.
translate/ — Provider-abstracted translate / transliterate / detect_language (palette group
"language"). Same shape as speech/ but THREE registries, one per capability:
DeepL translates only, Sarvam and LLM-backed providers do all three.
(Sarvam's chat model remains a separate plugin at model/sarvam_chat_model/;
nodes/sarvam/ itself was retired — every capability it served is now a provider.)
For Browser plugin runtime, profile and takeover contracts, see Browser. The shared Home/Dev interface is documented in Browser workspace.
Shared helpers (one per domain)
Domains with 2+ plugins share a _base.py (or _<name>.py) in the
folder. If you're adding a new node in one of these domains, reuse
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 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 |
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 |
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 |
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 |
Cross-domain infrastructure lives in services/plugin/ (e.g.
edge_walker.py for agent connection discovery, routing.py for
declarative REST).
Shared credentials
Credentials live in each node folder's _credentials.py — same
"one domain owns its own code" principle as _base.py. Import from
the sibling file via relative path:
# inside server/nodes/google/gmail/__init__.py
from ._credentials import GoogleCredential # shared with 6 siblings
# inside server/nodes/model/openai_chat_model/__init__.py
from ._credentials import OpenAICredential # one of 11 cloud LLM creds
# inside server/nodes/twitter/twitter_send/__init__.py
from ._credentials import TwitterCredential # shared with 3 siblings
| Folder | _credentials.py contents |
Plugins |
|---|---|---|
nodes/google/ |
GoogleCredential (OAuth2, 7 Workspace scopes union) |
gmail, calendar, drive, sheets, tasks, contacts, gmailReceive |
nodes/location/ |
GoogleMapsCredential (API key via ?key=) |
gmaps_create / gmaps_locations / gmaps_nearby_places |
nodes/twitter/ |
TwitterCredential (OAuth2 + PKCE) |
twitter_send / _search / _user / _receive |
nodes/telegram/ |
TelegramCredential (bot token + owner chat id) |
telegram_send / _receive |
nodes/discord/ |
DiscordBotCredential (bot token; overrides inject() because Discord uses Bot <token>, not the inherited Bearer ) + DiscordUserCredential (OAuth2 user context, separate id so connecting a user never overwrites the bot) |
discord_send / _action / _receive / _interaction |
nodes/scraper/ |
ApifyCredential (Bearer, SDK probe) + TikHubCredential (Bearer, declarative httpx probe against tikhub/user/get_user_info — kept SDK-free so the modal validates even if the tikhub import fails) |
apify_actor / tikhub_action |
nodes/model/ |
14 LLM credential classes: 11 cloud (OpenAI / Anthropic / Gemini / OpenRouter / Groq / Cerebras / DeepSeek / Kimi / Mistral / xAI / Sarvam), Ollama / LM Studio, and OpenAICompatibleCredential (any number of named endpoints, RFC-0003) |
13 chat models (xAI has no standalone chat-model node) plus the nodes/speech/ and nodes/translate/ Sarvam providers, which import SarvamCredential from here — one stored key serves Sarvam's OpenAI-compatible chat endpoint and its api-subscription-key REST APIs |
nodes/search/ |
BraveSearch / Serper / Perplexity inlined in each plugin file |
single-use per plugin |
Declare inline only when genuinely single-use (see
nodes/search/brave_search/__init__.py for the inline pattern). Declare in
_credentials.py when the folder has 2+ plugins that share auth.
Auto-discovery is automatic — when the nodes walker imports a plugin
file, the plugin's from ._credentials import X triggers the
credential module import, which registers every Credential subclass
into CREDENTIAL_REGISTRY before the plugin class body runs. No
wiring beyond the import statement.
Contract invariants
server/tests/test_plugin_contract.py enforces the contract
invariants on every plugin (live count via pytest --collect-only).
Common ones you'll trip:
type/display_name/groupmust be non-empty.Params+Outputmust be PydanticBaseModelsubclasses.- Every
@Operationname unique per class. - Every declared credential class must be registered
(happens automatically via
__init_subclass__— just import it). routing=...requirescredentialsdeclared.task_queue∈TaskQueue.ALL(rest-api/ai-heavy/code-exec/triggers-poll/triggers-event/android/browser/messaging/machina-default).- Tool schemas (
usable_as_tool=TrueorToolNode) — no$defs, no$ref(LLM-compat). Outputis enforced at runtime. Dict results from operations are validated against the declaredOutputmodel and dumped withmodel_dump(mode="json", exclude_unset=True)(FastAPIresponse_modelsemantics — seeBaseNode._serialize_result). A type mismatch in a declared field produces anOutputValidationErrorenvelope. Prefer returning theOutputinstance directly; keepextra="allow"+Optionalfields so context keys pass through.
Run: pytest server/tests/test_plugin_contract.py -q.
Self-contained plugin folders (richer plugins)
Most plugins are a single file in the right folder — that's the default. But some own a long-lived service (bot connection, SDK session, subprocess), credentials-modal Connect/Disconnect commands, trigger pre-checks, etc. Those graduate to a self-contained folder shape so nothing telegram-specific (or whatsapp-specific, twitter- specific, …) lives outside that folder.
Reference: server/nodes/telegram/. Read it first before adding a
similar plugin.
server/nodes/telegram/
├── __init__.py # imports + one register_* call per concern (zero logic)
├── _credentials.py # TelegramCredential subclass
├── _service.py # singleton bot lifecycle (connect / send / poll)
├── _handlers.py # WS_HANDLERS dict (telegram_connect, …)
├── _filters.py # build_telegram_filter (event_waiter filter)
├── _refresh.py # WS-connect refresh + trigger precheck
├── _events.py # typed CloudEvents factory + broadcast_telegram_status
├── _send.py # perform_send / resolve_chat_id, shared by the node and the WS send command
├── telegram_send.py # ActionNode, also an AI tool (usable_as_tool; ApprovalSpec: held while Ask first is on)
├── telegram_receive.py # TriggerNode
├── icon.svg # node icon for every node type in the folder
├── telegram.svg # credential brand icon (Credential.get_icon_path)
└── meta.json # palette colour
Variant: one node, many vendors
Telegram owns one vendor's surface. The other shape is a node that must
speak to several vendors interchangeably — one canvas node whose
provider parameter picks the backend. Reference:
server/nodes/speech/.
server/nodes/speech/
├── __init__.py # register_output_schema + register_option_loader (zero logic)
├── _protocol.py # vendor-neutral requests / results / errors + two Protocols
├── _registry.py # ONE REGISTRY PER DIRECTION, over services/provider_registry
├── _config.py # reads server/config/speech_defaults.json
├── _unifier.py # dispatch + typed-error -> NodeUserError, one catch site
├── _providers/ # _http.py + one module per vendor, each self-registering
├── _credentials.py # only the vendors no other plugin already declares
├── _base.py # shared node helpers (credential resolve, input read, billing)
├── _option_loaders.py # provider-aware dropdown loaders
├── text_to_speech.py # the two nodes
└── speech_to_text.py
Four ideas worth stealing wholesale:
- Registry membership is the capability. Two registries, one per
direction, and the node's provider enum is
tts_providers(). A synthesis-only vendor never appears in the transcription dropdown, and there is nosupports_xflag to fall out of sync with reality. - Capabilities are JSON, not Python.
speech_defaults.jsonholds per-provider and per-model values ({"whisper-1": [...], "_default": [...]}), resolved exact → longest-prefix →_default. Boolean flags default permissive, so forgetting to declare one never silently disables a working feature. No shared code branches on a vendor name — the bantest_plugin_shapeimplies is satisfied structurally. - Vendor divergence lives in the vendor module. Auth scheme, whether options ride the query string or the body, and how the response is shaped are all per-vendor facts. Keep them behind the neutral request / result types and central code stays vendor-blind.
- Reuse credentials, don't redeclare them.
_credentials.pyholds only the vendors nothing else owns; the rest are imported (from ..model._credentials import OpenAICredential). Two classes with the sameidcollide inCREDENTIAL_REGISTRYat import time.
See Multi-credential nodes
for the ctx.connection(id) contract and the routing= trap that comes with it.
Generic registries to plug into (19 at time of writing; the hand-curated table lives in plugin_system.md)
Telegram's __init__.py is the canonical wiring example. Adding any
of these concerns to your plugin is one register_* call from your
package's __init__.py — the consumer never imports your folder.
| Concern | Where to register | What it does |
|---|---|---|
| Credentials-modal WebSocket commands | services.ws_handler_registry.register_ws_handlers({"<type>": handler}) |
Adds <type> to the central WS dispatcher (no router edits) |
| FastAPI router (Wave 11.I) | services.ws_handler_registry.register_router(router, name="<name>") |
Plugin's HTTP router mounts via the plugin loop in main.py; sibling concern in the same file as register_ws_handlers |
| Event-trigger filter | services.event_waiter.register_filter_builder(node_type, fn) |
Plugs into FILTER_BUILDERS for event_waiter.build_filter() |
| Trigger pre-execution check | services.event_waiter.register_trigger_precheck(node_type, async_fn) |
Generic triggers.py handler runs run_trigger_precheck before entering the wait loop |
| Service-status refresh on WS connect | services.status_broadcaster.register_service_refresh(async_callback) |
Callback runs once per _refresh_all_services cycle |
| Output schema | services.node_output_schemas.register_output_schema(node_type, ModelClass) |
Avoids declaring a duplicate Output class in the central schema file |
| Agent Context descriptor | services.plugin.edge_walker.register_agent_context_builder(async_fn) |
Turns a node connected on input-context into the descriptor the agent runtime consumes. The framework walks the edge but knows nothing about the descriptor's shape — see nodes/context/_descriptor.py |
All seven are idempotent (same callable / class for the same key is a
no-op; conflicts raise ValueError).
These seven are the core self-contained-folder set; newer concerns have
their own generic register_* entrypoints in the same spirit —
services.events.register_webhook_source,
services.ws_handler_registry.register_option_loader /
register_oauth_callback_path / register_public_ingress_path,
services.deployment.canary_registry.register_canary_trigger_type,
services.deployment.poll_registry.register_poll_coroutine_factory,
services.plugin.edge_walker.register_master_skill_expander, and
services.plugin.social_provider_registry.register_social_send_handler.
Register, don't edit the consumer. Never edit event_waiter.py,
status_broadcaster.py, or routers/websocket.py to add a plugin's
handler / filter / refresh — call the matching register_* from your
plugin's __init__.py instead. Likewise never import a plugin folder
from routers/, services/, or another nodes/ subfolder; the
consumer reaches your code through the registry, never by import path.
Credential validation (Wave 11.I)
The credential-validator dispatch is a sibling concern, handled by the
existing services/plugin/credential.py:Credential base class. Your
Credential subclass overrides _probe(api_key) -> ProbeResult (or,
in rare cases like local-LLM 2-storage, the whole validate(data) -> dict classmethod). Maps, Apify, all 11 cloud LLM providers, and
both local-LLM providers (Ollama / LM Studio) all dispatch through the
same scaffold — no _SPECIAL_PROVIDER_VALIDATORS dict in
routers/websocket.py.
When NOT to use this shape
Don't create _service.py / _handlers.py siblings unless the plugin
genuinely owns:
- A long-lived stateful object (bot / device / session / subprocess).
- Credentials-modal lifecycle commands beyond the standard Save / Load / Delete.
- Trigger pre-checks that depend on plugin-specific service state.
- A status refresh that runs on WebSocket connect.
A single search node, an HTTP-only REST plugin, a code executor — all of those stay one file. Adding the folder ceremony for them is just overhead.
Wire format is stable across moves
Frontend identifies plugin commands by WebSocket message type
strings (telegram_connect, telegram_status, …) — never by Python
module paths. As long as your WS_HANDLERS keys stay the same, you
can rearrange your nodes/<group>/ folder freely with zero frontend
changes. The telegram refactor moved 754 lines without touching
client/.
Full reference: docs-internal/plugin_system.md → "Self-contained plugin folders".
Common pitfalls
- Don't edit
server/nodes/__init__.py— it's a pure auto-discovery walker. Adding a new folder doesn't need edits either;pkgutilfinds subpackages automatically. - Don't instantiate services directly. Use the canonical lazy
helpers in
services.plugin.deps:from services.plugin.deps import get_auth_service, get_database, get_cache, get_ai_service, get_text_service, get_maps_service, get_android_service. These resolve the singleton from the DI container at call time (test monkeypatching depends on call-time lookup — never memoise). - Don't call
auth_service.get_api_key(...)from plugins. Declare aCredentialsubclass; theConnectionfacade / service layer resolves tokens. - Pydantic
extra="ignore"is the default for Params — extra fields silently drop. Useextra="allow"if the node passes unknown fields through to a handler. - snake_case everywhere. Field names, JSON Schema keys,
displayOptions.showkeys, and handler dict access all use snake_case. Noalias="camelName", nopopulate_by_name=True, nomodel_dump(by_alias=True).displayOptions.show["driver_field"]must match a property name in the sameParamsclass — the frontend's visibility evaluator looks up that exact key. - A custom
tool_namebreaks the paired skill's icon unless you add avisuals.jsonalias. The skill icon resolver (SkillLoader._parse_skill_metadata) maps each SKILL.mdallowed-toolstoken — which is the LLM tool name — through snake→camel into avisuals.jsonlookup. Keeptool_name = "<snake_case_of_node_type>"and this just works. If you deliberately pick a short brand name (githubforgithubAction,vercelforvercelAction), you MUST add avisuals.jsonentry keyed by that tool name carrying the same icon plus the plugin'smeta.jsoncolor:"github": {"icon": "lobehub:Github", "color": "#8250df"}. Otherwise the Master Skill row renders a blank icon and no color. Locked bytests/test_skill_icon_resolution.py(every shipped skill must resolve a non-empty icon). - LLM tool schemas must be flat. If your Params uses nested
Pydantic models or
Union, the LLM-schema emission will add$defsand fail the invariant. Keep tool-facing Params flat; move nested types toOutputinstead. - Never name a Params field
modelorapi_keyon a node that also has aproviderfield. An effect inParameterRenderer.tsx:898keys on those two literal names: when a siblingproviderfield is present it overwritesmodelwith the chat-model list and clearsapi_key. It never checks that the provider is an LLM provider, soprovider: "elevenlabs"still triggers it and the field is wiped the moment the user picks a vendor. Prefix instead —tts_model,stt_model. Other reserved sibling names with name-based magic in that file:parameters,message_type,group_id,group_name,channel_jid,sender_number,sender_name,session_id,service_id,action. - The parameter panel stores
""for every cleared field, whatever the declared type. Harmless againststr; a hard validation error againstOptional[float],boolorDict[str, Any]— a freshly-dropped node fails on its own defaults withInvalid parameters: Input should be a valid dictionary. Add a@model_validator(mode="before")that drops blank strings for fields that cannot hold one, and coerce object fields from a JSON string (the panel has no object widget, so a dict parameter arrives as typed text). Reusable form:coerce_blank_paramsinnodes/speech/_base.py; per-node precedents:AndroidServiceParams._coerce_parameters,WriteTodosParams._coerce_todos. Do not blanket-drop blanks forstrfields — that turns amin_lengtherror into a confusing "field required". - Declare the canvas handles a dual-purpose node needs.
usable_as_tool = Trueauto-setshide_input_handle/hide_output_handleunless the class declares them, and adds anoutput-toolhandle. 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 listinput-main/output-maininhandles— declaring the flagsFalsealone does not add them. (Several nodes also set both flagsFalse, 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 letaudio_file="../../credentials.db"read the encrypted credential store and upload it to a third party. Those helpers reject../~/ drive prefixes and re-check containment after resolution, so a symlink or Windows junction cannot redirect the result. - Never return media bytes (or base64) from a node. Write the file into
the workspace with
services.media.write_audioand return theAudioRef. A node result is persisted 3×, broadcast twice, retained in the status cache, copied into every downstream activity input, and — if the node isusable_as_tool— serialized into an LLM message. Seeservices/media/limits.pyfor the measured Temporal thresholds this exists to stay under. - Return plain data, never raw backend or third-party objects. Backend /
SDK result objects (native filesystem
ReadResult, httpx responses, …) must be unwrapped to plain fields before returning — the Output validation rejects them, and everything downstream (node_outputsJSON column, orjson WS broadcast,_serialise_tool_result) expects JSON-compatible data. Likewise return real lists/dicts, not pre-stringified JSON — LLM-facing serialization is the dispatcher's job. - Raise
NodeUserErrorfor user-correctable failures. Missing required field, unknown enum value, bad path, sidecar not running —raise NodeUserError("...")(exported fromservices.plugin) gives the user/LLM a clean one-line WARN + structured envelope with no traceback, and the shared Temporal retry policy skips retries for it (services/plugin/scaling.py). BareExceptionis for genuine server bugs only — it keeps the fulllogger.exceptiontraceback. - Coerce LLM-stringified JSON args at the Params boundary. Gemini
(and others) sometimes pass array/object tool args as JSON-encoded
strings. Fields that can receive them declare a
field_validator(..., mode="before")thatjson.loadses string input — canonical examples:AndroidServiceParams._coerce_parameters,WriteTodosParams._coerce_todos. Malformed JSON should pass through unchanged so Pydantic raises a properValidationErrorthe LLM can correct. - Collapse advanced options with
group="...". Tag rarely-tuned fields withjson_schema_extra={"group": "options"}and they get lifted into a collapsible "Options" collection in the parameter panel (adapter-side). Declare custom display name / placeholder viamodel_config = ConfigDict(json_schema_extra={"groups": {...}}). Main-entry fields stay top-level. Full spec indocs-internal/plugin_system.md. - Never declare
api_keyas a Params field. UseApiKeyCredential/OAuthCredentialsubclasses andAuthService. Local credentials use the encrypted database; approved 1Password bindings resolve privately at the calling Activity, with the trusted principal. Catalogue and form reads use saved source metadata. Plugins that need the injected key readctx.raw["_raw_parameters"]["api_key"]— it's stashed before Pydantic validation strips it. Distributed mode requires an audited static-secret adapter and rejects local keys, inline secrets, OAuth refresh stores and CLI-managed sessions. See 1Password credentials. isConfigNodeis auto-derived — don't declare it. Plugins whosegrouptuple contains"memory"or"tool"automatically exportuiHints.isConfigNode: True(set by_derive_auto_ui_hintsinservices/plugin/base.py). The flag tells the frontend that the node's parameter panel inherits its parent's main inputs instead of showing direct upstream connections. If you genuinely want to opt out, declareui_hints = {"isConfigNode": False}— explicit always wins viadict.update. Adding a new auto-derivation rule goes in_derive_auto_ui_hints, not in individual plugins; new uiHint flags must also be added toINodeUIHintsinclient/src/types/INodeProperties.tsand to theknownset inserver/tests/test_node_spec.py::test_ui_hints_only_carry_known_flags.
Waves-at-a-glance
Added in Wave 11 (Mar 2026):
- 11.A:
BaseNode/ActionNode/TriggerNode/ToolNode@Operation+Routing+Connection+Credential.
- 11.B/C: 111 plugins migrated, folder layout adopted.
- 11.D: Per-domain handler bodies inlined.
- 11.E: 18 declarative credentials, 29 plugins wired.
- 11.E.1: Credentials moved into per-domain
_credentials.py(no centralserver/credentials/dir). - 11.E.2: Dead-code sweep — 2 broken imports fixed, 13 dead
dispatch branches stripped, duplicate proxy handler removed,
routers/whatsapp.py(misnamed) →services/whatsapp_service.py. - 11.E.3: 14 handler files deleted, last per-domain bodies
inlined into plugins;
handle_ai_agent/handle_chat_agentretired in favour ofBaseNode.execute()via the node registry. - 11.E.4: Last
tools.pymovables relocated to their domains (proxyConfig matrix →nodes/proxy/proxy_config, Android tool dispatch →nodes/android/_base). - 11.F: Per-plugin Temporal activities, 9 worker pools with tuned concurrency.
- 11.G (this doc): Cookbook.
End state: services/handlers/ is 4 files / ~1K LOC (down from
16 / 12.8K). Only cross-cutting orchestration remains there:
tools.py (AI-tool dispatch + agent delegation), triggers.py
(generic event-trigger handler), todo.py (writeTodos shim), and the
package docstring (__init__.py). The former google_auth.py shared
OAuth helper was retired into nodes/google/_auth_helper.py.
Plan + full migration history: plugin_system.md.