Skip to content

Self-improving AI Employees for everyone

docs: Wave 11 final pass — refresh CLAUDE.md, plugin_system, node_creation, RFC

trohitga0cd1c43b0ad
diff --git a/CLAUDE.md b/CLAUDE.md
index 8a091aa0..9f5f6cef 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -99,6 +99,12 @@ server/services/
├── claude_code_service.py # Claude Code CLI wrapper (--max-budget-usd, session persistence)
├── claude_oauth.py # Isolated Claude CLI auth (~/.claude-machina, no main-session impact)
├── tracked_http.py # HTTPX event hooks for automatic API cost tracking
+├── whatsapp_service.py # WhatsApp RPC proxy helpers (used by nodes/whatsapp/*, not an APIRouter)
+├── handlers/ # Cross-cutting orchestration only (Wave 11: 16 → 4 files, 12.8K → 1.1K LOC)
+│ ├── tools.py # AI-tool dispatch + agent delegation (~821 LOC)
+│ ├── triggers.py # Generic event-trigger handler
+│ ├── google_auth.py # Shared OAuth credential helper
+│ └── __init__.py # Docstring only
├── llm/ # Native LLM provider SDKs (replaces LangChain for chat)
│ ├── __init__.py # Public API exports
│ ├── protocol.py # ThinkingConfig, Message, LLMResponse, LLMProvider Protocol
@@ -329,7 +335,7 @@ class NodeExecutor:
def _build_handler_registry(self) -> Dict[str, Callable]:
return {
'start': handle_start,
- 'aiAgent': partial(handle_ai_agent, ai_service=self.ai_service),
+ 'aiAgent': _dispatch_plugin_node, # Wave 11: routes via BaseNode.execute()
# ... registry-based dispatch instead of if-else chains
}
```
@@ -837,7 +843,7 @@ Search API nodes that work BOTH as standalone workflow nodes AND as AI Agent too
- Serper in **Scrapers** category (Google SERP scraping)
### Specialized AI Agents (15 nodes)
-Specialized agents are AI Agents pre-configured for specific domains. They inherit full AI Agent functionality (provider, model, prompt, system message, thinking/reasoning) while being tailored for specific capabilities. All specialized agents route to `handle_chat_agent` in the backend and support the same input handles. Node colors use centralized dracula theme constants imported from `client/src/styles/theme.ts`.
+Specialized agents are AI Agents pre-configured for specific domains. They inherit full AI Agent functionality (provider, model, prompt, system message, thinking/reasoning) while being tailored for specific capabilities. All specialized agents dispatch through `BaseNode.execute()` via the node registry (Wave 11) and support the same input handles. Node colors use centralized dracula theme constants imported from `client/src/styles/theme.ts`.
**Input Handles:**
- `input-main` - Main data input (auto-prompting fallback)
@@ -864,16 +870,13 @@ Specialized agents are AI Agents pre-configured for specific domains. They inher
- **deep_agent**: Deep Agent - AI agent powered by LangChain DeepAgents with built-in filesystem tools (read, write, edit, glob, grep, execute), sub-agent delegation, auto-summarization, and todo planning. Routes to dedicated `handle_deep_agent` handler and `DeepAgentService` (not `handle_chat_agent`). Supports memory, skills, connected tools, and teammate delegation via `input-teammates`. See `docs-internal/deep_agent.md`.
**Backend Routing:**
-Specialized agents are detected by `SPECIALIZED_AGENT_TYPES` and routed to `handle_chat_agent` (except agents with dedicated execution engines):
+Specialized agents are detected by `SPECIALIZED_AGENT_TYPES` and dispatched through `BaseNode.execute()` via the node registry (Wave 11). Dedicated engines: `rlm_agent` -> `RLMService`, `deep_agent` -> `DeepAgentService` (`services/agents/`).
```python
-# In node_executor.py - most specialized agents route to handle_chat_agent
SPECIALIZED_AGENT_TYPES = {
'android_agent', 'coding_agent', 'web_agent', 'task_agent', 'social_agent',
'travel_agent', 'tool_agent', 'productivity_agent', 'payments_agent', 'consumer_agent',
'autonomous_agent', 'orchestrator_agent', 'ai_employee',
}
-# rlm_agent routes to handle_rlm_agent -> RLMService (dedicated handler + service)
-# deep_agent routes to handle_deep_agent -> DeepAgentService (services/agents/ package)
```
**Team Lead Types (Agent Teams Pattern):**
@@ -1368,7 +1371,7 @@ Residential proxy provider management with geo-targeting, session control, and a
| `server/services/proxy/service.py` | ProxyService singleton with provider selection and URL generation |
| `server/services/proxy/providers.py` | TemplateProxyProvider for JSON url_template formatting |
| `server/services/proxy/models.py` | ProxyProvider, RoutingRule, SessionType dataclasses |
-| `server/services/handlers/proxy.py` | Handler functions for proxy_config, proxy_request, proxy_status |
+| `server/nodes/proxy/proxy_config.py`, `proxy_request.py`, `proxy_status.py` | Plugin nodes (Wave 11); ProxyConfig 10-op matrix lives in `proxy_config.py` |
| `server/skills/web_agent/proxy-config-skill/SKILL.md` | AI agent skill for proxy configuration |
| `server/skills/web_agent/http-request-skill/SKILL.md` | HTTP request skill with proxy usage docs |
@@ -2388,11 +2391,7 @@ The Zeenie will:
- Use LangGraph for tool execution when tools are connected
### Backend Handlers
-Both agents have dedicated handlers in `server/services/handlers/ai.py`:
-- `handle_ai_agent()` - Collects memory, skill, and tool data from connected nodes
-- `handle_chat_agent()` - Collects memory, skill, tool, and input data from connected nodes
-
-Both use the shared `_collect_agent_connections()` base function that:
+Wave 11: `handle_ai_agent` / `handle_chat_agent` were deleted. Agent execution now flows through `BaseNode.execute()` + `NodeContext.from_legacy()` via the node registry (`server/nodes/agent/`). Connection collection is handled by the agent node classes, which internally call `_collect_agent_connections()` to:
- Scans edges for nodes connected to `input-memory`, `input-skill`, `input-tools`, `input-main`/`input-chat` handles
- Returns a 4-tuple: `(memory_data, skill_data, tool_data, input_data)`
- Handles MasterSkill expansion into individual skill entries
@@ -4038,7 +4037,7 @@ android_agent: {
**Backend (4 files):**
6. **constants.py**: Add to `AI_AGENT_TYPES` frozenset
-7. **node_executor.py**: Add handler registry entry mapping to `partial(handle_chat_agent, ...)`
+7. **Plugin file**: Add `server/nodes/agent/<name>.py` subclassing the chat-agent base; registry auto-wires via `BaseNode.__init_subclass__`
8. **handlers/tools.py**: Add to delegation check tuple in `execute_tool()`
9. **ai.py**: Add entries to `DEFAULT_TOOL_NAMES`, `DEFAULT_TOOL_DESCRIPTIONS`, and `DelegateToAgentSchema` condition
@@ -4472,7 +4471,9 @@ Frontend (WhatsAppNode.tsx) → Python Backend (/api/whatsapp/*) → WhatsApp RP
- **No Mock Data**: All endpoints return proper errors instead of mock responses
- **Connection Status**: Real-time status display with device ID, session, and service info
-### Backend Endpoints (`server/routers/whatsapp.py`)
+### Backend Helpers (`server/services/whatsapp_service.py`)
+
+Wave 11: renamed from `routers/whatsapp.py` (was misnamed — never an APIRouter). Provides RPC proxy helpers consumed by `nodes/whatsapp/*` plugins and the WhatsApp WebSocket handlers.
#### `/api/whatsapp/status` - Get Connection Status
- Returns WhatsApp connection status from Flask service
diff --git a/docs-internal/node_creation.md b/docs-internal/node_creation.md
index dcef04a7..7c5e4ce2 100644
--- a/docs-internal/node_creation.md
+++ b/docs-internal/node_creation.md
@@ -1,1884 +1,24 @@
# Node Creation Guide
-> **The canonical recipe moved to [Plugin System (Wave 11)](./plugin_system.md).** That doc has the current class-based `ActionNode` / `TriggerNode` / `ToolNode` quick-start, `@Operation` + declarative `Routing` + `Connection` facade, folder layout, and Temporal worker-pool knobs. New nodes use that pattern.
+> **Canonical recipe:** [Plugin System (Wave 11)](./plugin_system.md) and the inline [Nodes Cookbook](../server/nodes/README.md) next to the plugin files.
-The Wave 10 `@register_node` dict form documented below is still
-supported (it's what `BaseNode.__init_subclass__` calls internally)
-but is kept here for historical context only.
+This file is a redirect. New nodes use the class-based `ActionNode` / `TriggerNode` / `ToolNode` hierarchy under `server/nodes/<group>/<name>.py`. Each subclass declares `type`, metadata, `Params` + `Output` Pydantic models, `credentials`, `handles`, `task_queue`, and operations on the class object; `BaseNode.__init_subclass__` writes to the four legacy registries (`NODE_METADATA`, `_DIRECT_MODELS`, `NODE_OUTPUT_SCHEMAS`, `_HANDLER_REGISTRY`) plus the class registry on import. No frontend edits.
-> **Related documentation:**
-> - **[Plugin System (Wave 11)](./plugin_system.md)** — current canonical recipe, 111 live plugins.
-> - [Workflow Schema](./workflow-schema.md) — JSON schema, edge handle conventions.
-> - [Schema Source of Truth RFC](./schema_source_of_truth_rfc.md) — backend-as-SSOT design.
-> - [CLAUDE.md](../CLAUDE.md) — project overview, key files, architecture patterns.
+## Where to look
----
+| Need | Doc |
+|------|-----|
+| 5-minute recipe, folder map, shared helpers | [server/nodes/README.md](../server/nodes/README.md) |
+| Full plugin pattern, `@Operation`, declarative `Routing`, `Connection` facade, Temporal task queues, credential classes | [plugin_system.md](./plugin_system.md) |
+| Backend-as-SSOT design (NodeSpec, icons, output schemas) | [schema_source_of_truth_rfc.md](./schema_source_of_truth_rfc.md) |
+| JSON workflow format, edge handle conventions | [workflow-schema.md](./workflow-schema.md) |
+| AI-tool nodes (dual-purpose or dedicated) | [ai_tool_node_creation.md](./ai_tool_node_creation.md), [dual_purpose_tool_node_creation.md](./dual_purpose_tool_node_creation.md) |
+| Specialized AI agents | [specialized_agent_node_creation.md](./specialized_agent_node_creation.md) |
-## Wave 10 — `@register_node` dict form (historical)
+## Wave 11 end state
-Drop a file in `server/nodes/`; the auto-discovery walker in
-`server/nodes/__init__.py` picks it up at import time and writes to
-the four registries (`NODE_METADATA`, `_DIRECT_MODELS`,
-`NODE_OUTPUT_SCHEMAS`, `_HANDLER_REGISTRY`) atomically.
-
-**Zero frontend edits.** The backend is SSOT for parameter schemas,
-output schemas, visual metadata (icon / color / handles / componentKind),
-and handlers. See [schema_source_of_truth_rfc.md § Wave 10](./schema_source_of_truth_rfc.md#wave-10--plugin-pattern--visual-contract)
-for the full wire-format reference.
-
-### One-file recipe
-
-```python
-# server/nodes/my_node.py
-from typing import Literal
-from pydantic import Field
-from models.nodes import BaseNodeParams
-from services.node_registry import register_node
-
-
-class MyNodeParams(BaseNodeParams):
- """Parameters for my new node."""
- type: Literal["myNode"]
- operation: Literal["create", "update", "delete"] = "create"
- name: str = Field(
- default="",
- json_schema_extra={"displayOptions": {"show": {"operation": ["create", "update"]}}},
- )
- resource_id: str = Field(
- default="", alias="resourceId",
- json_schema_extra={"displayOptions": {"show": {"operation": ["update", "delete"]}}},
- )
- api_key: str | None = Field(
- default=None, alias="apiKey",
- json_schema_extra={"password": True}, # masks in UI
- )
-
-
-async def handle_my_node(node_id, node_type, params, context):
- # business logic here
- return {"success": True, "result": {...}}
-
-
-register_node(
- type="myNode",
- metadata={
- "displayName": "My Node",
- "subtitle": "Short action hint",
- "icon": "asset:my_icon", # see "Icon wire format" below
- "color": "#8be9fd", # dracula token or hex
- "group": ["tool"], # palette-section grouping
- "componentKind": "square", # React Flow component dispatch
- "handles": [
- {"name": "input-main", "kind": "input", "position": "left", "role": "main", "label": "Input"},
- {"name": "output-main", "kind": "output", "position": "right", "role": "main", "label": "Output"},
- ],
- "description": "What this node does",
- "version": 1,
- "uiHints": {}, # optional: isToolPanel, hideRunButton, hasCodeEditor, …
- },
- input_model=MyNodeParams,
- handler=handle_my_node,
-)
-```
-
-That's the whole file. Restart the backend — the node appears in the
-editor palette and can be dropped on the canvas. No frontend edit anywhere.
-
-### Icon wire format
-
-Backend `icon:` string uses n8n-style prefix dispatch:
-
-| Format | Source | Example |
-|---|---|---|
-| `asset:<key>` | Filesystem SVG under `client/src/assets/icons/**/*.svg`. `<key>` = filename minus `.svg`. Drop a new SVG into any subfolder — Vite's `import.meta.glob` picks it up automatically. | `asset:gmail` |
-| `<lib>:<brand>` | NPM icon package. `lobehub` is registered today (covers 1400+ AI/SaaS brands). Adding a second library = 3-line addition to `ICON_LIBRARIES` in `client/src/assets/icons/index.ts`. | `lobehub:claude` |
-| `data:` / `http(s)://` / `/…` | URL passthrough | `data:image/svg+xml,…` |
-| plain text | emoji / short label | `🔧` |
-
-Pytest invariant `test_every_asset_icon_has_matching_svg` fails CI if you
-reference an `asset:<key>` that doesn't exist.
-
-### componentKind dispatch
-
-Tells the Dashboard which React component renders the node:
-
-| componentKind | Component | When to use |
-|---|---|---|
-| `square` | `SquareNode` | Default for most data / tool / service nodes |
-| `trigger` | `TriggerNode` | Nodes with only an output handle that emit events |
-| `start` | `StartNode` | The workflow Start node (special visual treatment) |
-| `agent` | `AIAgentNode` | LangGraph-style agents (accepts skill/tool/memory/task inputs) |
-| `chat` | `AIAgentNode` | Conversational chat agents |
-| `tool` | `SquareNode` | Passive tool nodes with `uiHints.isToolPanel` for ToolSchemaEditor |
-| `model` | `ModelNode` | AI chat model configuration nodes |
-
-### uiHints catalogue
-
-Every panel-visibility decision reads from `uiHints`:
-
-- `hideInputSection` / `hideOutputSection` / `hideRunButton` — panel chrome toggles
-- `hasCodeEditor` — renders the code-editor layout (Python / JS / TS)
-- `hasSkills` — shows Connected Skills accordion (required for all `componentKind:"agent"`)
-- `isToolPanel` — shows Tool Schema Editor (required for all `componentKind:"tool"`)
-- `isMasterSkillEditor` — shows Master Skill split-panel editor
-- `isMemoryPanel` — shows Memory window-size + token-usage panel
-- `isMonitorPanel` — shows Team Monitor live display
-- `isChatTrigger` / `isConsoleSink` — wires to ConsolePanel tabs
-- `showLocationPanel` — shows Google Maps picker
-- `isAndroidToolkit` — shows ToolSchemaEditor gated on Android service sub-nodes
-- `width` / `height` — explicit canvas node size (overrides defaults)
-
-### Dynamic option loaders
-
-For fields needing fetched-at-edit-time options (Gmail labels, WhatsApp groups, …):
-
-1. Write an async loader in `server/services/node_option_loaders/`.
-2. Register in `LOAD_OPTIONS_REGISTRY` (one line).
-3. On the Pydantic field: `json_schema_extra={"loadOptionsMethod": "myMethodName"}`.
-
-The frontend's generic `load_options` WS dispatcher populates the dropdown.
-
-### Output schemas
-
-For nodes whose runtime output the frontend should show in the Input panel:
-pass `output_model=MyOutput` to `register_node(...)`. Matches the Wave 3
-pattern — see [schema_source_of_truth_rfc.md](./schema_source_of_truth_rfc.md).
-
----
-
-## Legacy backend-only recipe (pre-Wave-10)
-
-Before Wave 10 the recipe spread across 5+ files
-(`models/nodes.py` + `KnownNodeParams` union + `_DIRECT_MODELS` dict +
-`NODE_METADATA` dict + `node_executor` handler registry). The plugin
-pattern above replaces all of that with one file — but the individual
-registries are still live and accept direct entries if you prefer
-the explicit pattern.
-
-### Dynamic option loaders
-
-If your node has a dropdown field that needs to fetch options at edit-time (e.g. Gmail labels, WhatsApp groups, Calendar list):
-
-1. Write an async loader in [server/services/node_option_loaders/](../server/services/node_option_loaders/) following the established `whatsapp_loaders.py` / `google_loaders.py` pattern.
-2. Register it in `LOAD_OPTIONS_REGISTRY` (one line) in `node_option_loaders/__init__.py`.
-3. Add `json_schema_extra={"loadOptionsMethod": "myMethodName"}` to the relevant Pydantic Field.
-
-The dropdown auto-populates via the unified `POST /api/schemas/nodes/options/{method}` dispatcher.
-
-### Frontend (Wave 6 path)
-
-Today: still need a thin entry in `client/src/nodeDefinitions/*.ts` so the editor knows the node type exists (palette + Dashboard routing). Once Phase 3e flips the flag, the entry can drop to just a `*_NODE_TYPES` array membership (or vanish entirely if backend `group` membership is enough).
-
-Visual component routing in [client/src/Dashboard.tsx](../client/src/Dashboard.tsx) is type-id based and still required. Pick a component (`SquareNode`, `AIAgentNode`, `TriggerNode`, `ToolkitNode`, `ModelNode`) by adding to the relevant `NODE_TYPES` list or routing branch.
-
-### What the legacy sections below describe
-
-The remaining content is the pre-Wave-6 frontend-first recipe: authoring `properties: [...]`, `displayOptions`, `defaults` arrays inside `client/src/nodeDefinitions/*.ts`. **All still works** until Phase 3e — but new authoring should use the Wave 6 recipe above so your node ships through the new path automatically when the flag flips.
-
----
-
-## Table of Contents
-
-1. [Node Types Overview](#node-types-overview)
-2. [Frontend: Node Definition](#frontend-node-definition) (legacy)
-3. [Frontend: Visual Component](#frontend-visual-component)
-4. [Backend: Workflow Handler](#backend-workflow-handler)
-5. [Template Resolution](#template-resolution)
-6. [Workflow Context and Status Broadcasting](#workflow-context-and-status-broadcasting)
-7. [Input & Output Panels](#input--output-panels)
-8. [Nodes Without Output Handles](#nodes-without-output-handles)
-9. [Config Nodes (Memory, Tools)](#config-nodes)
-10. [Trigger Nodes](#trigger-nodes)
-11. [AI Provider Nodes](#ai-provider-nodes)
-12. [AI Tool Nodes](#ai-tool-nodes)
-13. [Complete Examples](#complete-examples)
-
----
-
-## Node Types Overview
-
-MachinaOs supports 112 nodes across 19 categories:
-
-| Category | Visual Component | Example Nodes | Count |
-|----------|-----------------|---------------|-------|
-| **Workflow** | StartNode | start, taskTrigger | 2 |
-| **Scheduler** | SquareNode | timer, cronScheduler | 2 |
-| **AI Chat Models** | SquareNode | openaiChatModel, anthropicChatModel, geminiChatModel, openrouterChatModel, groqChatModel, cerebrasChatModel | 6 |
-| **AI Agents** | AIAgentNode | aiAgent, chatAgent | 2 |
-| **Specialized Agents** | AIAgentNode | android_agent, coding_agent, web_agent, task_agent, social_agent, travel_agent, tool_agent, productivity_agent, payments_agent, consumer_agent, autonomous_agent, orchestrator_agent, rlm_agent | 13 |
-| **AI Memory** | SquareNode | simpleMemory | 1 |
-| **AI Skills** | SquareNode | masterSkill, customSkill + 9 individual skills | 11 |
-| **AI Tools** | SquareNode | calculatorTool, currentTimeTool, duckduckgoSearch, androidTool | 4 |
-| **Search** | SquareNode | braveSearch, serperSearch, perplexitySearch | 3 |
-| **Triggers** | TriggerNode | whatsappReceive, webhookTrigger, chatTrigger, twitterReceive | 4 |
-| **Android** | SquareNode | batteryMonitor, wifiAutomation, location, cameraControl (16 services) | 16 |
-| **WhatsApp** | SquareNode | whatsappSend, whatsappReceive, whatsappDb | 3 |
-| **Twitter/X** | SquareNode | twitterSend, twitterSearch, twitterUser, twitterReceive | 4 |
-| **Social** | SquareNode | socialReceive, socialSend | 2 |
-| **Location/Maps** | SquareNode | createMap, addLocations, showNearbyPlaces | 3 |
-| **Utility** | SquareNode | httpRequest, webhookTrigger, webhookResponse, chatTrigger, console | 5 |
-| **Proxy** | SquareNode | proxyRequest, proxyConfig, proxyStatus | 3 |
-| **Code** | SquareNode | pythonExecutor, javascriptExecutor | 2 |
-| **Chat** | SquareNode | chatSend, chatHistory | 2 |
-| **Document** | SquareNode | httpScraper, fileDownloader, documentParser, textChunker, embeddingGenerator, vectorStore | 6 |
-
----
-
-## Frontend: Node Definition
-
-Node definitions are located in `client/src/nodeDefinitions/`. Create your definition in the appropriate file or create a new category file.
-
-### Basic Structure
-
-```typescript
-// client/src/nodeDefinitions/yourNodes.ts
-import { INodeTypeDescription, NodeConnectionType } from '../types/INodeProperties';
-
-export const yourNodes: Record<string, INodeTypeDescription> = {
- yourNodeName: {
- // === Required Fields ===
- displayName: 'Your Node Name', // Shown in UI
- name: 'yourNodeName', // Internal identifier (camelCase)
- icon: '🔧', // Emoji or image URL
- group: ['category'], // For palette grouping
- version: 1,
- description: 'What this node does',
-
- // === Visual Defaults ===
- defaults: {
- name: 'Your Node',
- color: '#FF5722' // Hex color for node accent
- },
-
- // === Connections ===
- inputs: [{
- name: 'main',
- displayName: 'Input',
- type: 'main' as NodeConnectionType,
- description: 'Node input'
- }],
- outputs: [{
- name: 'main',
- displayName: 'Output',
- type: 'main' as NodeConnectionType,
- description: 'result, status, timestamp' // Document output fields
- }],
-
- // === Parameters ===
- properties: [
- // See Parameter Types section below
- ]
- }
-};
-```
-
-### Parameter Types
-
-```typescript
-properties: [
- // String input
- {
- displayName: 'API Key',
- name: 'apiKey',
- type: 'string',
- default: '',
- required: true,
- description: 'Your API key',
- placeholder: 'Enter API key...',
- typeOptions: {
- password: true, // Masked input
- rows: 4 // Multiline textarea
- }
- },
-
- // Number input
- {
- displayName: 'Timeout',
- name: 'timeout',
- type: 'number',
- default: 30,
- typeOptions: {
- minValue: 1,
- maxValue: 300,
- numberStepSize: 1
- }
- },
-
- // Boolean toggle
- {
- displayName: 'Enable Feature',
- name: 'enableFeature',
- type: 'boolean',
- default: false
- },
-
- // Dropdown select
- {
- displayName: 'Method',
- name: 'method',
- type: 'options',
- default: 'GET',
- options: [
- { name: 'GET', value: 'GET' },
- { name: 'POST', value: 'POST' },
- { name: 'PUT', value: 'PUT' },
- { name: 'DELETE', value: 'DELETE' }
- ]
- },
-
- // Conditional display
- {
- displayName: 'Request Body',
- name: 'body',
- type: 'string',
- default: '',
- typeOptions: { rows: 6 },
- displayOptions: {
- show: {
- method: ['POST', 'PUT'] // Only show when method is POST or PUT
- }
- }
- },
-
- // Collection (grouped options)
- {
- displayName: 'Options',
- name: 'options',
- type: 'collection',
- placeholder: 'Add Option',
- default: {},
- options: [
- {
- displayName: 'Headers',
- name: 'headers',
- type: 'string',
- default: ''
- }
- ]
- },
-
- // Dynamic options (loaded from backend)
- {
- displayName: 'Model',
- name: 'model',
- type: 'string',
- default: '',
- typeOptions: {
- dynamicOptions: true,
- dependsOn: ['provider'] // Reload when provider changes
- }
- }
-]
-```
-
-### Register the Node
-
-Add to the main registry in `client/src/nodeDefinitions.ts`:
-
-```typescript
-import { yourNodes } from './nodeDefinitions/yourNodes';
-
-export const nodeDefinitions: Record<string, INodeTypeDescription> = {
- ...existingNodes,
- ...yourNodes,
-};
-```
-
----
-
-## Frontend: Visual Component
-
-### Map to Component Type
-
-In `client/src/Dashboard.tsx`, map your node to a visual component:
-
-```typescript
-const createNodeTypes = () => {
- const types: NodeTypes = {};
-
- Object.entries(nodeDefinitions).forEach(([type, def]) => {
- if (type === 'yourNodeName') {
- types[type] = SquareNode; // Standard square node
- } else if (type === 'yourModelNode') {
- types[type] = ModelNode; // Circular model node
- } else if (type === 'aiAgent') {
- types[type] = AIAgentNode; // Special AI agent layout
- }
- // ... etc
- });
-
- return types;
-};
-```
-
-### Available Visual Components
-
-| Component | Shape | Use Case |
-|-----------|-------|----------|
-| `SquareNode` | 80x80px square | Standard nodes, action nodes |
-| `TriggerNode` | 80x80px square | Trigger nodes (no input handles) |
-| `ModelNode` | 80x80px circle | AI models, config nodes |
-| `AIAgentNode` | Rectangle with handles | AI agents with tool/memory inputs |
-| `ToolkitNode` | Square with vertical handles | Skill nodes, toolkit aggregators |
-
-### Trigger Node Registration
-
-Trigger nodes must be added to `TRIGGER_NODE_TYPES` array in Dashboard.tsx:
-
-```typescript
-// In createNodeTypes()
-const TRIGGER_NODE_TYPES = ['start', 'cronScheduler', 'webhookTrigger', 'whatsappReceive', 'chatTrigger', 'taskTrigger'];
-
-// Trigger nodes map to TriggerNode component
-if (TRIGGER_NODE_TYPES.includes(type)) {
- types[type] = TriggerNode;
-}
-```
-
-Also add to the deploy validation array in `handleDeploy()`:
-
-```typescript
-const triggerTypes = ['start', 'cronScheduler', 'webhookTrigger', 'whatsappReceive', 'workflowTrigger', 'chatTrigger', 'taskTrigger'];
-```
-
----
-
-## Backend: Workflow Handler
-
-### Add to Execution Service (Enables Run Button)
-
-**CRITICAL:** Add your node type to the supported types whitelist in `client/src/services/executionService.ts`. Without this, the "Run" button will NOT appear in the parameter panel for your node.
-
-```typescript
-// client/src/services/executionService.ts
-
-// Option 1: Import and spread node types array (recommended for modules)
-import { YOUR_NODE_TYPES } from '../nodeDefinitions/yourNodes';
-
-static isNodeTypeSupported(nodeType: string): boolean {
- const supportedTypes = [
- // ... existing types
- ...YOUR_NODE_TYPES, // Spread imported array
- ];
- return supportedTypes.includes(nodeType);
-}
-
-// Option 2: Add individual node types directly
-static isNodeTypeSupported(nodeType: string): boolean {
- const supportedTypes = [
- // ... existing types
- 'yourNodeName',
- ];
- return supportedTypes.includes(nodeType);
-}
-```
-
-**Why this is required:**
-- The `isNodeTypeSupported()` method acts as an execution whitelist
-- Only nodes in this list show the "Run" button in the parameter panel
-- This prevents accidental execution of incomplete/untested nodes
-
-### Create Backend Handler
-
-In `server/services/workflow.py`, add a handler in `_execute_single_node()`:
-
-```python
-elif node_type == 'yourNodeName':
- result = await self._execute_your_node(node_id, resolved_parameters)
-```
-
-Then implement the execution method:
-
-```python
-async def _execute_your_node(self, node_id: str, parameters: Dict[str, Any]) -> Dict[str, Any]:
- """Execute your custom node."""
- start_time = time.time()
-
- try:
- # Extract parameters
- api_key = parameters.get('apiKey', '')
- timeout = int(parameters.get('timeout', 30))
- method = parameters.get('method', 'GET')
-
- # Your node logic here
- result_data = {
- "status": "success",
- "data": "your result",
- "timestamp": datetime.now().isoformat()
- }
-
- return {
- "success": True,
- "node_id": node_id,
- "node_type": "yourNodeName",
- "result": result_data,
- "execution_time": time.time() - start_time
- }
-
- except Exception as e:
- logger.error(f"Your node execution failed: {e}")
- return {
- "success": False,
- "node_id": node_id,
- "node_type": "yourNodeName",
- "error": str(e),
- "execution_time": time.time() - start_time
- }
-```
-
----
-
-## Template Resolution
-
-Template resolution allows nodes to reference outputs from other nodes using `{{nodeName.fieldPath}}` syntax.
-
-### How It Works
-
-1. **ParameterResolver** (`server/services/parameter_resolver.py`) gathers outputs from ALL nodes in the workflow
-2. Template patterns `{{nodeName.field}}` are replaced with actual values
-3. Resolution happens BEFORE the node handler executes
-
-### Template Syntax
-
-```
-{{nodeName.field}} # Simple field access
-{{nodeName.nested.field}} # Nested field access
-{{nodeName.array[0]}} # Array indexing
-{{nodeName.data.items[0].name}} # Complex path
-```
-
-### Node Name Resolution
-
-Node names are normalized for template matching:
-- `aiAgent-1234567890` → `aiagent`
-- `WhatsApp Chat History` (custom label) → `whatsappchathistory`
-- Spaces and special characters are removed, converted to lowercase
-
-### Example Usage
-
-```typescript
-// In node definition - parameter that accepts templates
-{
- displayName: 'Message',
- name: 'message',
- type: 'string',
- default: '',
- description: 'Supports templates: {{aiagent.response}}'
-}
-```
-
-### Backend Resolution Flow
-
-```
-NodeExecutor.execute()
- ↓
-ParameterResolver.resolve(params, node_id, nodes, edges, session_id)
- ↓
-_gather_all_outputs() // Collects outputs from ALL nodes
- ↓
-_resolve_value() // Replaces {{templates}} with actual values
- ↓
-Handler receives resolved parameters
-```
-
-### Important Notes
-
-- Templates are resolved by ParameterResolver, not by individual handlers
-- If a template references a node that hasn't executed yet, it resolves to empty string
-- Nodes that need raw template values (not resolved) should use a different parameter name
-
----
-
-## Workflow Context and Status Broadcasting
-
-When a node executes, it receives a context object and can broadcast status updates to the frontend. This is essential for real-time UI updates and per-workflow status scoping.
-
-### Execution Context Structure
-
-The backend passes a `context` dictionary to every node handler:
-
-```python
-context = {
- "nodes": List[Dict], # All nodes in the workflow
- "edges": List[Dict], # All edges in the workflow
- "session_id": str, # Execution session ID
- "execution_id": str, # Unique execution ID
- "workflow_id": str, # Current workflow ID (for status scoping)
- "get_output_fn": Callable, # Function to get node outputs
-}
-```
-
-### Frontend: Passing Workflow ID
-
-When executing a node from the frontend, include `workflow_id` in the request:
-
-```typescript
-// In WebSocketContext.tsx
-const executeNodeAsync = useCallback(async (
- nodeId: string,
- nodeType: string,
- parameters: Record<string, any>,
- nodes?: any[],
- edges?: any[]
- ): Promise<any> => {
- const response = await sendRequest<any>('execute_node', {
- node_id: nodeId,
- node_type: nodeType,
- parameters,
- nodes,
- edges,
- workflow_id: currentWorkflowId // CRITICAL: Include for status scoping
- }, timeoutMs);
- return response;
- }, [sendRequest, currentWorkflowId]);
-```
-
-**Why This Matters:**
-- Without `workflow_id`, status updates are stored under `'unknown'` key
-- Frontend retrieves status from `allNodeStatuses[currentWorkflowId][nodeId]`
-- Mismatched workflow IDs cause status updates to be "lost" (stored but not displayed)
-
-### Backend: Status Broadcasting
-
-Use the `StatusBroadcaster` to send real-time updates to the frontend:
-
-```python
-from services.status_broadcaster import get_status_broadcaster
-
-async def handle_my_node(
- node_id: str,
- node_type: str,
- parameters: Dict[str, Any],
- context: Dict[str, Any]
-) -> Dict[str, Any]:
- workflow_id = context.get('workflow_id') # Extract from context
- broadcaster = get_status_broadcaster()
-
- # Broadcast "executing" status
- await broadcaster.update_node_status(
- node_id,
- "executing",
- {"message": "Starting execution..."},
- workflow_id=workflow_id # CRITICAL: Include workflow_id
- )
-
- # Do your work...
- result = do_something()
-
- # Broadcast "success" status
- await broadcaster.update_node_status(
- node_id,
- "success",
- {"message": "Completed", "result": result},
- workflow_id=workflow_id
- )
-
- return {"success": True, "result": result, ...}
-```
-
-### Status Types
-
-| Status | Description | Visual Effect |
-|--------|-------------|---------------|
-| `idle` | Node is not executing | Default appearance |
-| `executing` | Node is currently running | Cyan glow, pulse animation |
-| `waiting` | Trigger node waiting for event | Cyan glow, pulse animation |
-| `success` | Node completed successfully | Green border (brief) |
-| `error` | Node execution failed | Red border, error message |
-
-### Frontend: Reading Status
-
-Components read status via the `useNodeStatus` hook:
-
-```typescript
-import { useNodeStatus } from '../contexts/WebSocketContext';
-
-const MyNodeComponent: React.FC<NodeProps> = ({ id }) => {
- const nodeStatus = useNodeStatus(id);
- const executionStatus = nodeStatus?.status || 'idle';
- const isExecuting = executionStatus === 'executing';
-
- return (
- <div style={{
- animation: isExecuting ? 'pulse 1.5s ease-in-out infinite' : 'none',
- boxShadow: isExecuting ? '0 0 10px cyan' : 'none'
- }}>
- {/* Node content */}
- </div>
- );
-};
-```
-
-### Status Storage Architecture
-
-```
-Frontend Backend
-──────── ───────
-allNodeStatuses: { StatusBroadcaster.broadcast({
- "workflow-123": { type: "node_status",
- "node-abc": { node_id: "node-abc",
- status: "executing", workflow_id: "workflow-123",
- data: {...} data: {status: "executing", ...}
- } })
- }
-}
- ↑ │
- │ WebSocket │
- └─────────────────────────────────────┘
-```
-
-### Example: Tool Node Status Broadcasting
-
-Tool nodes (executed by AI Agent) need proper status flow:
-
-```python
-# In ai.py - tool_executor callback
-async def tool_executor(tool_name: str, tool_args: Dict) -> Any:
- config = tool_configs.get(tool_name, {})
- tool_node_id = config.get('node_id')
-
- # Broadcast "executing" to tool node
- if tool_node_id and broadcaster:
- await broadcaster.update_node_status(
- tool_node_id,
- "executing",
- {"message": f"Executing {tool_name}"},
- workflow_id=workflow_id # From execute_agent closure
- )
-
- # Execute tool...
- result = await execute_tool(tool_name, tool_args, config)
-
- # Broadcast "success" to tool node
- if tool_node_id and broadcaster:
- await broadcaster.update_node_status(
- tool_node_id,
- "success",
- {"message": f"{tool_name} completed", "result": result},
- workflow_id=workflow_id
- )
-
- return result
-```
-
-### Common Issues
-
-| Issue | Cause | Fix |
-|-------|-------|-----|
-| Status not updating | Missing `workflow_id` in frontend request | Add `workflow_id: currentWorkflowId` to execute request |
-| Status stuck on "executing" | Success broadcast missing | Add success broadcast after execution |
-| Wrong workflow shows status | `workflow_id` mismatch | Ensure frontend sends and backend uses same ID |
-| Multiple nodes show same status | Broadcasting to wrong `node_id` | Verify correct node ID in broadcast call |
-
-### Checklist for Status Broadcasting
-
-- [ ] Frontend: Include `workflow_id` in execution request
-- [ ] Backend: Extract `workflow_id` from context
-- [ ] Backend: Pass `workflow_id` to all `update_node_status()` calls
-- [ ] Backend: Broadcast "executing" at start
-- [ ] Backend: Broadcast "success" or "error" at end
-- [ ] Frontend: Use `useNodeStatus(id)` hook to read status
-
----
-
-## Input & Output Panels
-
-The parameter panel shows inputs from connected upstream nodes and allows drag-and-drop mapping.
-
-### Input Section (`client/src/components/parameterPanel/InputSection.tsx`)
-
-Shows outputs from nodes connected to the current node's input handles:
-- Displays source node label and type
-- Shows available output fields that can be dragged to parameters
-- Config nodes inherit their parent's inputs (labeled "via Parent")
-
-### Output Panel (`client/src/components/OutputPanel.tsx`)
-
-Shows the schema of outputs the node produces:
-- Used for drag-and-drop to downstream node parameters
-- Schema defined in `outputs[].description` of node definition
-
-### Documenting Output Schema
-
-In your node definition, document output fields in the `description`:
-
-```typescript
-outputs: [{
- name: 'main',
- displayName: 'Output',
- type: 'main' as NodeConnectionType,
- description: 'response, model, provider, timestamp' // Comma-separated fields
-}]
-```
-
-### Declaring the runtime output shape (backend)
-
-The node's output shape lives on the **backend** — the frontend fetches it lazy (see [schema_source_of_truth_rfc.md](./schema_source_of_truth_rfc.md)). Add a Pydantic model to [server/services/node_output_schemas.py](../server/services/node_output_schemas.py) and register it in `NODE_OUTPUT_SCHEMAS`:
-
-```python
-# server/services/node_output_schemas.py
-class YourNewNodeOutput(_OutputBase):
- field1: Optional[str] = None
- field2: Optional[int] = None
- # ...
-
-NODE_OUTPUT_SCHEMAS["yourNewNode"] = YourNewNodeOutput
-```
-
-That's it — the editor's Input panel picks it up on next open via `GET /api/schemas/nodes/yourNewNode.json`. No frontend change. If you skip this, InputSection falls back to real run data (once the node executes) and then to an empty `{ data: 'any' }` state.
-
----
-
-## Nodes Without Output Handles
-
-Some nodes are input-only (like Console) and should not have output handles.
-
-### Frontend: Hide Output Handle
-
-In `client/src/components/SquareNode.tsx`, add your node type to `NO_OUTPUT_NODE_TYPES`:
-
-```typescript
-// Nodes that should not have output handles (input-only nodes)
-const NO_OUTPUT_NODE_TYPES = ['console', 'yourInputOnlyNode'];
-```
-
-The output handle is conditionally rendered:
-
-```tsx
-{/* Square Output Handle - hidden for input-only nodes */}
-{!NO_OUTPUT_NODE_TYPES.includes(type || '') && (
- <Handle
- id="output-main"
- type="source"
- position={Position.Right}
- // ...
- />
-)}
-```
-
-### Backend: Special Handler for Connected Outputs
-
-Input-only nodes typically need access to connected upstream outputs. Register them in `NodeExecutor._dispatch()`:
-
-```python
-# server/services/node_executor.py
-
-async def _dispatch(self, node_id: str, node_type: str, params: Dict, context: Dict) -> Dict:
- # Check registry first
- handler = self._handlers.get(node_type)
- if handler:
- return await handler(node_id, node_type, params, context)
-
- # Special handlers needing connected outputs
- if node_type in ('pythonExecutor', 'javascriptExecutor', 'webhookResponse', 'console', 'yourNode'):
- outputs, source_nodes = await self._get_connected_outputs_with_info(context, node_id)
- if node_type == 'yourNode':
- return await handle_your_node(node_id, node_type, params, context, outputs, source_nodes)
- # ... other handlers
-```
-
-### Handler Signature for Connected Outputs
-
-```python
-async def handle_your_node(
- node_id: str,
- node_type: str,
- parameters: Dict[str, Any],
- context: Dict[str, Any],
- connected_outputs: Dict[str, Any] = None, # Keyed by source node type
- source_nodes: list = None # List of {id, type, label}
-) -> Dict[str, Any]:
- """Handle node with access to connected upstream outputs."""
- connected_outputs = connected_outputs or {}
- source_nodes = source_nodes or []
-
- # Merge all connected outputs into single dict
- input_data = {}
- for node_type, output in connected_outputs.items():
- if isinstance(output, dict):
- input_data.update(output)
-
- # Your logic here using input_data
- # ...
-```
-
----
-
-## Config Nodes
-
-Config nodes (memory, tools) connect to parent nodes via special handles and inherit the parent's inputs.
-
-### Define a Config Node
-
-```typescript
-// group must include 'memory' or 'tool'
-myConfigNode: {
- displayName: 'My Config',
- name: 'myConfigNode',
- icon: '🔧',
- group: ['ai', 'memory'], // 'memory' or 'tool' = config node
- version: 1,
- description: 'Configuration node',
- defaults: { name: 'Config', color: '#8b5cf6' },
-
- // Config nodes typically have no main input
- inputs: [],
-
- // Output connects to parent's config handle
- outputs: [{
- name: 'config',
- displayName: 'Config Output',
- type: 'main' as NodeConnectionType,
- description: 'Configuration data'
- }],
-
- properties: [
- // Config-specific parameters
- ]
-}
-```
-
-### Parent Node with Config Handles
-
-Config handles follow the pattern `input-<type>`:
-
-```tsx
-// In your parent node component (e.g., AIAgentNode.tsx)
-<Handle
- id="input-memory" // Config handle naming
- type="target"
- position={Position.Bottom}
- // ... styling
-/>
-
-<Handle
- id="input-tools" // Another config handle
- type="target"
- position={Position.Bottom}
- // ... styling
-/>
-```
-
-### Input Inheritance
-
-When a config node is connected to a parent's config handle:
-1. The parent node does NOT see the config node as an input
-2. The config node DOES see the parent's main inputs (labeled "via Parent")
-
-This is handled automatically by `InputSection.tsx` and `OutputPanel.tsx` using:
-- `isConfigHandle()` - Detects config handles by pattern
-- `isConfigNode()` - Detects config nodes by group
-
----
-
-## Trigger Nodes
-
-Trigger nodes wait for external events before completing execution.
-
-### Define a Trigger Node
-
-```typescript
-myTrigger: {
- displayName: 'My Trigger',
- name: 'myTrigger',
- icon: '⚡',
- group: ['trigger'],
- version: 1,
- description: 'Waits for an event',
- defaults: { name: 'Trigger', color: '#f59e0b' },
-
- // Triggers typically have no input (they start workflows)
- inputs: [],
-
- outputs: [{
- name: 'main',
- displayName: 'Event',
- type: 'main' as NodeConnectionType,
- description: 'event_type, data, timestamp'
- }],
-
- properties: [
- // Filter parameters
- {
- displayName: 'Event Filter',
- name: 'eventFilter',
- type: 'string',
- default: '*',
- description: 'Filter pattern for events'
- }
- ]
-}
-```
-
-### Register Trigger in Backend
-
-In `server/services/event_waiter.py`:
-
-```python
-TRIGGER_REGISTRY: Dict[str, TriggerConfig] = {
- 'myTrigger': TriggerConfig(
- node_type='myTrigger',
- event_type='my_event_received', # Event to listen for
- display_name='My Event'
- ),
-}
-
-# Add filter builder
-def build_my_filter(params: Dict) -> Callable[[Dict], bool]:
- """Build filter for my events."""
- event_filter = params.get('eventFilter', '*')
-
- def filter_fn(event_data: Dict) -> bool:
- if event_filter == '*':
- return True
- return event_data.get('type') == event_filter
-
- return filter_fn
-
-FILTER_BUILDERS['myTrigger'] = build_my_filter
-```
-
-### Temporal/Deployment Safety
-
-Trigger nodes connecting via config handles (e.g., `input-task`) are excluded from downstream inclusion in `_get_downstream_nodes()` (`server/services/deployment/manager.py`). Non-firing trigger nodes in a deployment run are automatically marked `_pre_executed` with `{not_triggered: True}` to prevent them from blocking as event waiters.
-
-The Temporal workflow (`server/services/temporal/workflow.py`) has a safety net: any trigger node reaching the scheduling loop without `_pre_executed` is auto-completed instead of being scheduled as a blocking activity. The trigger type set `TRIGGER_NODE_TYPES` in `workflow.py` must be kept in sync with `WORKFLOW_TRIGGER_TYPES` in `constants.py`.
-
-### Dispatch Events
-
-From your event source (webhook, WebSocket, etc.):
-
-```python
-from services import event_waiter
-
-# When event occurs
-event_waiter.dispatch('my_event_received', {
- 'type': 'some_type',
- 'data': {...},
- 'timestamp': datetime.now().isoformat()
-})
-```
-
-### Example: Task Trigger (Agent Delegation)
-
-The `taskTrigger` node demonstrates a complete trigger implementation that fires when delegated child agents complete:
-
-**Frontend Definition** (`client/src/nodeDefinitions/workflowNodes.ts`):
-```typescript
-taskTrigger: {
- displayName: 'Task Completed',
- name: 'taskTrigger',
- icon: '📨',
- group: ['trigger', 'workflow'],
- version: 1,
- subtitle: 'Child Agent Completed',
- description: 'Triggers when a delegated child agent completes its task',
- defaults: { name: 'Task Completed', color: '#bd93f9' },
- inputs: [],
- outputs: [{
- name: 'main',
- displayName: 'Output',
- type: 'main' as NodeConnectionType,
- description: 'task_id, status, agent_name, result/error, parent_node_id'
- }],
- properties: [
- { displayName: 'Task ID Filter', name: 'task_id', type: 'string', default: '' },
- { displayName: 'Agent Name Filter', name: 'agent_name', type: 'string', default: '' },
- { displayName: 'Status Filter', name: 'status_filter', type: 'options', default: 'all',
- options: [{ name: 'All', value: 'all' }, { name: 'Completed Only', value: 'completed' }, { name: 'Errors Only', value: 'error' }] },
- { displayName: 'Parent Node ID', name: 'parent_node_id', type: 'string', default: '' }
- ]
-}
-```
-
-**Backend Registry** (`server/services/event_waiter.py`):
-```python
-'taskTrigger': TriggerConfig(
- node_type='taskTrigger',
- event_type='task_completed',
- display_name='Task Completed'
-),
-
-def build_task_completed_filter(params: Dict) -> Callable[[Dict], bool]:
- """Build filter for task completed events."""
- task_id_filter = params.get('task_id', '')
- agent_name_filter = params.get('agent_name', '')
- status_filter = params.get('status_filter', 'all')
- parent_node_id = params.get('parent_node_id', '')
-
- def matches(data: Dict) -> bool:
- if task_id_filter and data.get('task_id') != task_id_filter:
- return False
- if agent_name_filter:
- if agent_name_filter.lower() not in data.get('agent_name', '').lower():
- return False
- if status_filter == 'completed' and data.get('status') != 'completed':
- return False
- if status_filter == 'error' and data.get('status') != 'error':
- return False
- if parent_node_id and data.get('parent_node_id') != parent_node_id:
- return False
- return True
- return matches
-
-FILTER_BUILDERS['taskTrigger'] = build_task_completed_filter
-```
-
-**Event Dispatch** (`server/services/handlers/tools.py`):
-```python
-# In _execute_delegated_agent(), after child completes:
-await broadcaster.send_custom_event('task_completed', {
- 'task_id': task_id,
- 'status': 'completed', # or 'error'
- 'agent_name': agent_label,
- 'agent_node_id': node_id,
- 'parent_node_id': config.get('parent_node_id', ''),
- 'result': result.get('result', {}).get('response', ...),
- 'workflow_id': workflow_id,
-})
-```
-
-**Output Schema** (`client/src/components/parameterPanel/InputSection.tsx`):
-```typescript
-taskTrigger: {
- task_id: 'string',
- status: 'string',
- agent_name: 'string',
- agent_node_id: 'string',
- parent_node_id: 'string',
- result: 'string',
- error: 'string',
- workflow_id: 'string',
-}
-```
-
----
-
-## AI Provider Nodes
-
-AI provider nodes use a factory pattern for consistent structure. They connect to the AI service backend and dynamically fetch available models.
-
-### Factory Pattern
-
-AI chat models use `createBaseChatModel()` from `src/factories/baseChatModelFactory.ts`:
-
-```typescript
-import { createBaseChatModel, ChatModelConfig, STANDARD_PARAMETERS } from '../factories/baseChatModelFactory';
-
-const myProviderConfig: ChatModelConfig = {
- providerId: 'myprovider', // Internal identifier
- displayName: 'My Provider', // Shown in UI
- icon: '🤖', // Emoji icon
- color: '#6366F1', // Accent color
- description: 'Provider description',
- models: [], // Empty - fetched dynamically
- parameters: [
- STANDARD_PARAMETERS.temperature,
- STANDARD_PARAMETERS.maxTokens,
- STANDARD_PARAMETERS.topP,
- // Provider-specific parameters...
- ]
-};
-
-export const aiModelNodes = {
- myProviderChatModel: createBaseChatModel(myProviderConfig)
-};
-```
-
-### Standard Parameters
-
-Available in `STANDARD_PARAMETERS`:
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `temperature` | number | 0.7 | Randomness (0-2) |
-| `maxTokens` | number | 1000 | Response length limit |
-| `topP` | number | 1 | Nucleus sampling |
-| `topK` | number | 40 | Top-K sampling |
-| `frequencyPenalty` | number | 0 | Token frequency penalty |
-| `presencePenalty` | number | 0 | Token presence penalty |
-
-### Backend Provider Configuration
-
-Add to `server/services/ai.py`:
-
-```python
-from dataclasses import dataclass
-from langchain_openai import ChatOpenAI
-
-@dataclass
-class ProviderConfig:
- name: str
- model_class: type
- api_key_param: str
- max_tokens_param: str
- detection_patterns: tuple
- default_model: str
- models_endpoint: str
- models_header_fn: Callable
-
-# Header function for API authentication
-def _myprovider_headers(api_key: str) -> dict:
- return {'Authorization': f'Bearer {api_key}'}
-
-PROVIDER_CONFIGS = {
- 'myprovider': ProviderConfig(
- name='myprovider',
- model_class=ChatOpenAI,
- api_key_param='api_key',
- max_tokens_param='max_tokens',
- detection_patterns=('myprovider',),
- default_model='default-model-id',
- models_endpoint='https://api.provider.com/models',
- models_header_fn=_myprovider_headers
- ),
-}
-```
-
-### Model Fetching
-
-Add model fetching logic in `AIService.fetch_models()`:
-
-```python
-elif provider == 'myprovider':
- response = await client.get(
- 'https://api.provider.com/models',
- headers=_myprovider_headers(api_key)
- )
- response.raise_for_status()
- data = response.json()
-
- models = []
- for model in data.get('data', []):
- model_id = model.get('id', '')
- if model_id:
- models.append(model_id)
-
- return sorted(models)
-```
-
-### Provider Detection
-
-Add to `server/constants.py`:
-
-```python
-def detect_ai_provider(node_type: str, parameters: dict = None) -> str:
- if 'myprovider' in node_type.lower():
- return 'myprovider'
- # ... other providers
- return 'openai' # Default fallback
-```
-
-### Frontend Integration
-
-1. **Dashboard.tsx** - Map to visual component:
- ```typescript
- } else if (type === 'myProviderChatModel') {
- types[type] = SquareNode;
- }
- ```
-
-2. **ModelNode.tsx** - Credential mapping:
- ```typescript
- const CREDENTIAL_TO_PROVIDER = {
- 'myProviderApi': 'myprovider'
- };
- ```
-
-3. **CredentialsModal.tsx** - API key entry:
- ```typescript
- {
- id: 'myprovider',
- name: 'My Provider',
- icon: '🤖',
- fields: [{ name: 'apiKey', label: 'API Key', type: 'password', required: true }]
- }
- ```
-
-### Complete Example: Adding Groq Provider
-
-Groq provides ultra-fast LLM inference. Here's the complete implementation:
-
-#### 1. Frontend Node Definition (`client/src/nodeDefinitions/aiModelNodes.ts`)
-
-```typescript
-import { createBaseChatModel, ChatModelConfig, STANDARD_PARAMETERS } from '../factories/baseChatModelFactory';
-
-const groqConfig: ChatModelConfig = {
- providerId: 'groq',
- displayName: 'Groq',
- icon: '⚡',
- color: '#F55036',
- description: 'Groq - Ultra-fast LLM inference with Llama, Mixtral, and Gemma models',
- models: [], // Fetched dynamically via API
- parameters: [
- STANDARD_PARAMETERS.temperature,
- STANDARD_PARAMETERS.maxTokens,
- STANDARD_PARAMETERS.topP,
- {
- displayName: 'Timeout',
- name: 'timeout',
- type: 'number',
- default: 60000,
- typeOptions: { minValue: 1000, maxValue: 180000 },
- description: 'Timeout for the request in milliseconds'
- },
- {
- displayName: 'Max Retries',
- name: 'maxRetries',
- type: 'number',
- default: 2,
- typeOptions: { minValue: 0, maxValue: 5 },
- description: 'Maximum number of retries'
- }
- ]
-};
-
-export const aiModelNodes = {
- // ... other providers
- groqChatModel: createBaseChatModel(groqConfig)
-};
-
-export { groqConfig };
-```
-
-#### 2. Backend Provider Config (`server/services/ai.py`)
-
-```python
-from langchain_groq import ChatGroq
-
-def _groq_headers(api_key: str) -> dict:
- return {'Authorization': f'Bearer {api_key}'}
-
-PROVIDER_CONFIGS = {
- # ... other providers
- 'groq': ProviderConfig(
- name='groq',
- model_class=ChatGroq,
- api_key_param='api_key',
- max_tokens_param='max_tokens',
- detection_patterns=('groq', 'llama', 'mixtral', 'gemma'),
- default_model='llama-3.3-70b-versatile',
- models_endpoint='https://api.groq.com/openai/v1/models',
- models_header_fn=_groq_headers
- ),
-}
-```
-
-#### 3. Model Fetching (`server/services/ai.py` - in `fetch_models` method)
-
-```python
-elif provider == 'groq':
- response = await client.get(
- 'https://api.groq.com/openai/v1/models',
- headers={'Authorization': f'Bearer {api_key}'}
- )
- response.raise_for_status()
- data = response.json()
-
- models = []
- for model in data.get('data', []):
- model_id = model.get('id', '')
- if model_id:
- models.append(model_id)
-
- return sorted(models)
-```
-
-#### 4. Chat Execution (`server/services/ai.py` - in `execute_chat` method)
-
-```python
-# Determine provider from node_type
-if node_type == 'groqChatModel':
- provider = 'groq'
-else:
- provider = self.detect_provider(model)
-```
-
-#### 5. Backend Constants (`server/constants.py`)
-
-```python
-AI_CHAT_MODEL_TYPES: FrozenSet[str] = frozenset([
- 'openaiChatModel',
- 'anthropicChatModel',
- 'geminiChatModel',
- 'openrouterChatModel',
- 'groqChatModel', # Add here
-])
-
-def detect_ai_provider(node_type: str, parameters: dict = None) -> str:
- # ... existing checks
- elif 'groq' in node_type.lower():
- return 'groq'
- # ... rest of function
-```
-
-#### 6. Frontend Provider Mapping (`client/src/components/ParameterRenderer.tsx`)
-
-```typescript
-const NODE_TYPE_TO_PROVIDER: Record<string, string> = {
- 'openaiChatModel': 'openai',
- 'anthropicChatModel': 'anthropic',
- // ... other providers
- 'groqChatModel': 'groq' // Add here
-};
-```
-
-#### 7. Execution Service (`client/src/services/executionService.ts`)
-
-```typescript
-static isNodeTypeSupported(nodeType: string): boolean {
- const supportedTypes = [
- // AI Nodes
- 'aiAgent',
- 'openaiChatModel',
- 'anthropicChatModel',
- 'geminiChatModel',
- 'openrouterChatModel',
- 'groqChatModel', // Add here
- // ... other nodes
- ];
- return supportedTypes.includes(nodeType);
-}
-```
-
-#### 8. Credentials Modal (`client/src/components/CredentialsModal.tsx`)
-
-```typescript
-const PROVIDERS = [
- // ... other providers
- {
- id: 'groq',
- name: 'Groq',
- placeholder: 'gsk_...',
- color: '#F55036',
- desc: 'Ultra-fast LLM inference - Llama, Mixtral, Gemma'
- },
-];
-```
-
-#### 9. Model Node Credential Mapping (`client/src/components/ModelNode.tsx`)
-
-```typescript
-const CREDENTIAL_TO_PROVIDER: Record<string, string> = {
- // ... other mappings
- 'groqApi': 'groq'
-};
-
-// In provider detection fallback:
-if (type?.includes('groq')) return 'groq';
-```
-
-#### 10. AI Provider Icons (`client/src/components/icons/AIProviderIcons.tsx`)
-
-```typescript
-import { Groq } from '@lobehub/icons';
-
-// Groq uses Avatar variant (no Color variant available)
-export const GroqIcon: React.FC<{ size?: number }> = ({ size = ICON_SIZE }) => (
- <Groq.Avatar size={size} />
-);
-
-export const AI_PROVIDER_ICONS: Record<string, React.FC<{ size?: number }>> = {
- // ... other icons
- groq: GroqIcon,
-};
-```
-
-#### 11. Python Dependency (`server/requirements.txt`)
-
-```
-langchain-groq>=0.1.0
-```
-
-### OpenRouter Example
-
-OpenRouter demonstrates advanced patterns including:
-- OpenAI-compatible API with custom base_url
-- Free/paid model grouping with `[FREE]` prefix
-- Multi-provider model IDs (e.g., `openai/gpt-4o`)
-
-See the [AI Chat Model Development Guide](../CLAUDE.md#ai-chat-model-development-guide) in CLAUDE.md for the complete OpenRouter implementation.
-
----
-
-## AI Tool Nodes
-
-AI Tool nodes provide capabilities that AI Agents can invoke during reasoning. They connect to the AI Agent's `input-tools` handle and define schemas that tell the LLM how to call them.
-
-### Architecture
-
-```
-Tool Node (calculatorTool) → (tool output) → AI Agent (input-tools handle)
- ↓
- LangGraph builds tools from schemas
- ↓
- LLM decides when to call tools
- ↓
- Tool executor runs handler
- ↓
- Result returned to LLM
-```
-
-### Existing Tool Nodes
-
-| Tool | Icon | Description |
-|------|------|-------------|
-| `calculatorTool` | `🔢` | Mathematical operations (add, subtract, multiply, divide, power, sqrt, mod, abs) |
-| `currentTimeTool` | `🕐` | Get current date/time with timezone support |
-| `duckduckgoSearch` | SVG | DuckDuckGo web search - free, no API key required |
-| `androidTool` | `📱` | Android device control toolkit - aggregates connected Android service nodes |
-| `braveSearch` | SVG | Brave Search API - web results with titles, snippets, URLs (dual-purpose) |
-| `serperSearch` | SVG | Google SERP via Serper API - web, news, images, places (dual-purpose) |
-| `perplexitySearch` | SVG | Perplexity Sonar AI - markdown answer with citations (dual-purpose) |
-
-### Define a Tool Node
-
-Tool nodes are defined in `client/src/nodeDefinitions/toolNodes.ts`:
-
-```typescript
-import { INodeTypeDescription, NodeConnectionType } from '../types/INodeProperties';
-
-export const toolNodes: Record<string, INodeTypeDescription> = {
- myCustomTool: {
- displayName: 'My Custom Tool',
- name: 'myCustomTool',
- icon: '🔧',
- group: ['ai', 'tool'], // 'tool' = AI tool node
- version: 1,
- subtitle: 'Custom Operations',
- description: 'Allow AI Agent to perform custom operations',
- defaults: { name: 'My Tool', color: '#50fa7b' },
-
- // Tool nodes typically have no main input (they're passive)
- inputs: [],
-
- // Output connects to AI Agent's input-tools handle
- outputs: [{
- name: 'tool',
- displayName: 'Tool',
- type: 'main' as NodeConnectionType,
- description: 'Connect to AI Agent tool handle'
- }],
-
- properties: [
- {
- displayName: 'Tool Name',
- name: 'toolName',
- type: 'string',
- default: 'my_custom_tool',
- required: true,
- description: 'Name the AI will use to call this tool'
- },
- {
- displayName: 'Description',
- name: 'toolDescription',
- type: 'string',
- default: 'Describe what this tool does for the AI',
- typeOptions: { rows: 2 },
- description: 'Describe the tool capabilities for the AI'
- },
- // Tool-specific parameters...
- ]
- }
-};
-
-// Add to TOOL_NODE_TYPES for identification
-export const TOOL_NODE_TYPES = ['calculatorTool', 'currentTimeTool', 'duckduckgoSearch', 'androidTool', 'myCustomTool'];
-// Search nodes are in a separate file: searchNodes.ts
-export const SEARCH_NODE_TYPES = ['braveSearch', 'serperSearch', 'perplexitySearch'];
-```
-
-### Backend: Tool Schema
-
-Add a Pydantic schema for your tool in `server/services/ai.py`:
-
-```python
-from pydantic import BaseModel, Field
-
-class MyCustomToolSchema(BaseModel):
- """Schema for my custom tool."""
- operation: str = Field(description="The operation to perform")
- value: str = Field(description="The value to operate on")
-
-def _get_tool_schema(tool_type: str) -> type:
- """Get Pydantic schema for tool type."""
- schemas = {
- 'calculatorTool': CalculatorSchema,
- 'currentTimeTool': CurrentTimeSchema,
- 'duckduckgoSearch': DuckDuckGoSearchSchema,
- 'myCustomTool': MyCustomToolSchema, # Add here
- }
- return schemas.get(tool_type)
-```
-
-### Backend: Tool Handler
-
-Add a handler in `server/services/handlers/tools.py`:
-
-```python
-async def _execute_my_custom_tool(params: Dict[str, Any]) -> str:
- """Execute my custom tool."""
- operation = params.get('operation', '')
- value = params.get('value', '')
-
- # Your tool logic here
- result = f"Performed {operation} on {value}"
-
- return result
-
-async def execute_tool(tool_type: str, tool_params: Dict, llm_params: Dict) -> str:
- """Dispatch tool execution to appropriate handler."""
- if tool_type == 'calculatorTool':
- return await _execute_calculator(llm_params)
- elif tool_type == 'currentTimeTool':
- return await _execute_current_time(llm_params)
- elif tool_type == 'duckduckgoSearch':
- return await _execute_duckduckgo_search(llm_params, tool_params)
- elif tool_type == 'myCustomTool':
- return await _execute_my_custom_tool(llm_params) # Add here
- else:
- return f"Unknown tool type: {tool_type}"
-```
-
-### Android Toolkit Pattern
-
-The `androidTool` demonstrates a special pattern for aggregating multiple nodes:
-
-```
-[Battery Monitor] --+
- +--> [Android Toolkit] --> [AI Agent]
-[WiFi Automation] --+
-```
-
-Key features:
-- **Gateway Pattern**: Single tool node aggregates multiple service nodes
-- **Dynamic Schema**: Schema built at runtime from connected services only
-- **Service Routing**: Tool execution routes to appropriate connected node
-
-The AI sees a single `android_device` tool with schema showing only connected services:
-- `service_id`: Which service to use (e.g., "battery", "wifi_automation")
-- `action`: Action to perform (e.g., "status", "enable", "disable")
-- `parameters`: Action-specific parameters
-
-### Tool Execution Flow
-
-1. **Tool Discovery**: AI Agent scans edges for nodes connected to `input-tools` handle
-2. **Schema Building**: `_get_tool_schema()` creates Pydantic schema for each tool type
-3. **Tool Binding**: LangGraph binds tools to the LLM model
-4. **LLM Decision**: LLM decides when to call tools based on user query
-5. **Status Broadcast**: `executing_tool` status broadcast with tool_name for UI animation
-6. **Tool Execution**: `execute_tool()` dispatches to appropriate handler
-7. **Result Return**: Tool result returned to LLM for continued reasoning
-
-### Checklist for New Tool Nodes
-
-**Frontend:**
-- [ ] Add tool definition in `client/src/nodeDefinitions/toolNodes.ts`
-- [ ] Add to `TOOL_NODE_TYPES` array in same file
-- [ ] Register in `client/src/nodeDefinitions.ts` (if not already importing toolNodes)
-
-**Backend:**
-- [ ] Add Pydantic schema in `server/services/ai.py` `_get_tool_schema()`
-- [ ] Add handler function in `server/services/handlers/tools.py`
-- [ ] Add dispatcher case in `execute_tool()` function
-- [ ] Add to `AI_TOOL_TYPES` in `server/constants.py`
-
----
-
-## Complete Examples
-
-### Example 1: HTTP Request Node
-
-**Frontend Definition:**
-```typescript
-httpRequest: {
- displayName: 'HTTP Request',
- name: 'httpRequest',
- icon: '🌐',
- group: ['utility'],
- version: 1,
- description: 'Make HTTP requests to external APIs',
- defaults: { name: 'HTTP', color: '#3b82f6' },
- inputs: [{ name: 'main', displayName: 'Input', type: 'main' }],
- outputs: [{
- name: 'main',
- displayName: 'Response',
- type: 'main',
- description: 'status, data, headers'
- }],
- properties: [
- { displayName: 'URL', name: 'url', type: 'string', required: true },
- { displayName: 'Method', name: 'method', type: 'options', default: 'GET',
- options: [{ name: 'GET', value: 'GET' }, { name: 'POST', value: 'POST' }] },
- { displayName: 'Body', name: 'body', type: 'string', typeOptions: { rows: 4 },
- displayOptions: { show: { method: ['POST'] } } }
- ]
-}
-```
-
-**Backend Handler:**
-```python
-async def _execute_http_request(self, node_id: str, parameters: Dict) -> Dict:
- import httpx
-
- url = parameters.get('url', '')
- method = parameters.get('method', 'GET')
- body = parameters.get('body', '')
-
- async with httpx.AsyncClient(timeout=30) as client:
- if method == 'GET':
- response = await client.get(url)
- else:
- response = await client.post(url, content=body)
-
- return {
- "success": True,
- "node_id": node_id,
- "node_type": "httpRequest",
- "result": {
- "status": response.status_code,
- "data": response.text,
- "headers": dict(response.headers)
- }
- }
-```
-
-### Example 2: Memory Config Node
-
-The Simple Memory node uses markdown-based storage with optional vector DB archival.
-
-**Frontend Definition:**
-```typescript
-simpleMemory: {
- displayName: 'Simple Memory',
- name: 'simpleMemory',
- icon: '🧠',
- group: ['skill', 'memory'], // 'skill' = appears in AI Skills category
- version: 1,
- description: 'Markdown-based conversation memory with optional vector DB for long-term retrieval',
- defaults: { name: 'Memory', color: '#8b5cf6' },
- inputs: [], // No input - passive config node
- outputs: [{
- name: 'memory',
- displayName: 'Memory',
- type: 'main',
- description: 'session_id, messages, message_count'
- }],
- properties: [
- { displayName: 'Session ID', name: 'sessionId', type: 'string', default: 'default' },
- { displayName: 'Window Size', name: 'windowSize', type: 'number', default: 10,
- typeOptions: { minValue: 1, maxValue: 100 },
- description: 'Number of message pairs to keep in short-term memory' },
- { displayName: 'Conversation History', name: 'memoryContent', type: 'string',
- default: '# Conversation History\n\n*No messages yet.*\n',
- typeOptions: { rows: 15, editor: 'code', editorLanguage: 'markdown' },
- description: 'Recent conversation history (editable)' },
- { displayName: 'Enable Long-Term Memory', name: 'longTermEnabled', type: 'boolean',
- default: false, description: 'Archive old messages to vector DB for semantic retrieval' },
- { displayName: 'Retrieval Count', name: 'retrievalCount', type: 'number', default: 3,
- typeOptions: { minValue: 1, maxValue: 10 },
- displayOptions: { show: { longTermEnabled: [true] } },
- description: 'Number of relevant memories to retrieve from long-term storage' }
- ]
-}
-```
-
-**Markdown Format:**
-```markdown
-# Conversation History
-
-### **Human** (2025-01-30 14:23:45)
-What is the weather like today?
-
-### **Assistant** (2025-01-30 14:23:48)
-I don't have access to real-time weather data...
-```
-
-**Backend Flow (in AI Agent handler):**
-The AI Agent collects memory_data from connected Simple Memory node:
-```python
-# In handlers/ai.py - handle_ai_agent()
-if target_handle == 'input-memory' and source_node.get('type') == 'simpleMemory':
- memory_params = await database.get_node_parameters(source_node_id) or {}
- memory_data = {
- 'node_id': source_node_id,
- 'session_id': memory_params.get('sessionId', 'default'),
- 'window_size': int(memory_params.get('windowSize', 10)),
- 'memory_content': memory_params.get('memoryContent', '# Conversation History\n\n*No messages yet.*\n'),
- 'long_term_enabled': memory_params.get('longTermEnabled', False),
- 'retrieval_count': int(memory_params.get('retrievalCount', 3))
- }
-```
-
-**Memory Processing (in ai.py):**
-```python
-# Parse markdown to LangChain messages
-history_messages = _parse_memory_markdown(memory_content)
-
-# After AI response, append and trim
-updated_content = _append_to_memory_markdown(updated_content, 'human', prompt)
-updated_content = _append_to_memory_markdown(updated_content, 'ai', response_content)
-updated_content, removed_texts = _trim_markdown_window(updated_content, window_size)
-
-# Archive to vector DB if enabled
-if removed_texts and memory_data.get('long_term_enabled'):
- store = _get_memory_vector_store(session_id) # InMemoryVectorStore + HuggingFaceEmbeddings
- store.add_texts(removed_texts)
-
-# Save updated markdown to node parameters
-await database.save_node_parameters(memory_node_id, {'memoryContent': updated_content})
-```
-
----
-
-## Checklist for New Nodes
-
-### Frontend
-- [ ] Create node definition in `client/src/nodeDefinitions/`
-- [ ] Register in `client/src/nodeDefinitions.ts`
-- [ ] Map to visual component in `Dashboard.tsx`
-- [ ] **Add to supported types in `executionService.ts`** (CRITICAL - enables Run button)
-- [ ] Add output schema in `InputSection.tsx` (for drag-and-drop UX)
-- [ ] For input-only nodes: Add to `NO_OUTPUT_NODE_TYPES` in `SquareNode.tsx`
-
-### Backend
-- [ ] Add handler in `server/services/handlers/` (appropriate file)
-- [ ] Export handler in `server/services/handlers/__init__.py`
-- [ ] Register in `NodeExecutor._build_handler_registry()` OR add to special handlers in `_dispatch()`
-- [ ] For nodes needing connected outputs: Use `_get_connected_outputs_with_info()` pattern
-- [ ] For triggers: Register in `event_waiter.py` TRIGGER_REGISTRY
-- [ ] For triggers: Add filter builder function
-
-### Template Resolution
-- [ ] If node uses template parameters: Templates are auto-resolved by ParameterResolver
-- [ ] If node needs raw template values: Use different parameter name to avoid resolution
-- [ ] Document template-compatible parameters in node description
-
-### AI Provider Nodes (additional steps)
-
-**Frontend:**
-- [ ] Add ChatModelConfig in `client/src/nodeDefinitions/aiModelNodes.ts`
-- [ ] Export via `createBaseChatModel()` factory
-- [ ] Add to `NODE_TYPE_TO_PROVIDER` in `client/src/components/ParameterRenderer.tsx`
-- [ ] Add to supported types in `client/src/services/executionService.ts`
-- [ ] Add credential mapping in `client/src/components/ModelNode.tsx` (CREDENTIAL_TO_PROVIDER)
-- [ ] Add provider fallback detection in `ModelNode.tsx` (type?.includes check)
-- [ ] Add credentials entry in `client/src/components/CredentialsModal.tsx`
-- [ ] Add provider icon in `client/src/components/icons/AIProviderIcons.tsx` (if using @lobehub/icons)
-
-**Backend:**
-- [ ] Add LangChain dependency in `server/requirements.txt` (e.g., `langchain-groq>=0.1.0`)
-- [ ] Import model class in `server/services/ai.py` (e.g., `from langchain_groq import ChatGroq`)
-- [ ] Add header function in `server/services/ai.py` (e.g., `_groq_headers()`)
-- [ ] Add ProviderConfig in `PROVIDER_CONFIGS` dict
-- [ ] Add model fetching case in `AIService.fetch_models()`
-- [ ] Add node type check in `AIService.execute_chat()` for provider detection
-- [ ] Add to `AI_CHAT_MODEL_TYPES` in `server/constants.py`
-- [ ] Add provider detection in `detect_ai_provider()` in `server/constants.py`
-
-### Documentation
-- [ ] Add to node count in `CLAUDE.md`
-- [ ] Document in appropriate section of `CLAUDE.md`
-- [ ] For AI providers: Update AI Chat Models section
-- [ ] Add to workflow-schema.md supported node types
+- 111 plugins across 9 Temporal worker pools (`rest-api`, `ai-heavy`, `code-exec`, `triggers-poll`, `triggers-event`, `android`, `browser`, `messaging`, `machina-default`).
+- Per-domain `_credentials.py` in each node folder (18 `Credential` subclasses; central `server/credentials/` was deleted in Wave 11.E.1).
+- `services/handlers/` shrank to 4 files / 1.1K LOC — only cross-cutting orchestration remains (`tools.py` AI-tool dispatch + agent delegation, `google_auth.py`, `triggers.py`).
+- Agent delegation invokes child agents through `BaseNode.execute()` via the node registry.
+- 124 pytest invariants in `tests/test_node_spec.py` lock the contract.
diff --git a/docs-internal/plugin_system.md b/docs-internal/plugin_system.md
index b55bac2f..f274247c 100644
--- a/docs-internal/plugin_system.md
+++ b/docs-internal/plugin_system.md
@@ -7,7 +7,12 @@ activity pattern. One Python file under `server/nodes/<group>/<name>.py`
= one node. No cross-cutting edits.
**Status: shipped.** 111 plugin classes cover every node type in the
-product; 124 pytest contract invariants lock the architecture.
+product across 9 Temporal worker queues; 124 pytest contract
+invariants lock the architecture. `services/handlers/` shrank from
+12.8K → 1.1K LOC across 16 → 4 files. See
+[`server/nodes/README.md`](../server/nodes/README.md) for the
+authoring cookbook (5-minute recipe + shared helpers + common
+pitfalls).
## Quick start — adding a new node
@@ -341,8 +346,9 @@ server/
│ ├── text/ # textGenerator / fileHandler
│ ├── location/ # gmaps_create / gmaps_locations / gmaps_nearby_places
│ └── skill/ # simpleMemory / masterSkill
-├── credentials/ # Declarative Credential subclasses
-│ └── __init__.py # Auto-discovery walker
+│ # Each group folder owns its own
+│ # _credentials.py (Wave 11.E.1) —
+│ # no central credentials package.
└── services/
├── plugin/ # Plugin runtime
│ ├── base.py # BaseNode
@@ -424,8 +430,9 @@ every CI run. Examples:
- Wave 11.D.8 — Twitter / Crawlee / Apify inlined. Twitter shares
`nodes/twitter/_base.py` for client + XDK helpers.
- Wave 11.D.9 — WhatsApp + Social inlined into `nodes/whatsapp/_base.py`
- and `nodes/social/_base.py` (full bodies, RPC dispatch still via
- `routers.whatsapp`).
+ and `nodes/social/_base.py` (full bodies, RPC dispatch via
+ `services.whatsapp_service`; renamed from `routers/whatsapp.py` in
+ Wave 11.E.2 since it was never an APIRouter).
- Wave 11.D.10 — `utility.py` split across 12 plugin files (maps,
text, workflow start, timer, cron, console, team monitor, chat).
- Wave 11.D.11 — Auto-populate trigger registries.
@@ -451,16 +458,23 @@ every CI run. Examples:
deep_agent) by inlining into their plugins. Split `handlers/ai.py`
4 ways: `handle_ai_chat_model` → `ChatModelBase.chat`,
`handle_simple_memory` → `SimpleMemoryNode.read`,
- `handle_ai_agent` / `handle_chat_agent` → deleted entirely
- (`tools.py:_execute_delegated_agent` now uses
- `BaseNode.execute()` + `NodeContext.from_legacy()` directly via the
- node registry).
+ `handle_ai_agent` / `handle_chat_agent` → deleted entirely.
+ `tools.py:_execute_delegated_agent` now looks up the child agent's
+ plugin class via `services.node_registry.get_node_class(node_type)`,
+ builds `NodeContext.from_legacy(...)`, and calls
+ `instance.execute(node_id, params, ctx)` directly — no handler shell
+ in the path.
- Wave 11.E.4 — Relocated `tools.py` movables: proxyConfig 10-op
- matrix → `nodes/proxy/proxy_config.execute_proxy_config`, Android
- AI-tool dispatch (toolkit + direct service) →
+ matrix → `nodes/proxy/proxy_config.execute_proxy_config` (shared by
+ the plugin's `dispatch` op and the AI-tool branch in `tools.py`);
+ Android AI-tool dispatch (toolkit + direct service) →
`nodes/android/_base.{execute_android_toolkit,
- execute_android_service_tool}`. `tools.py` from 1,255 → 821 LOC.
-- Wave 11.G — (this file) Docs + packaging.
+ execute_android_service_tool}` with a single canonical
+ `SERVICE_ID_MAP` and a shared `_execute_with_broadcast` helper
+ (previously duplicated in `tools.py`). `tools.py` from 1,255 → 821
+ LOC.
+- Wave 11.G — Nodes cookbook (`server/nodes/README.md`) + CLAUDE.md
+ plugin section + this file refreshed to match shipped state.
`services/handlers/` is now **4 files / 1,112 LOC** (down from 16
files / 12,800 LOC):
diff --git a/docs-internal/schema_source_of_truth_rfc.md b/docs-internal/schema_source_of_truth_rfc.md
index 21ccd61c..dfdd85d4 100644
--- a/docs-internal/schema_source_of_truth_rfc.md
+++ b/docs-internal/schema_source_of_truth_rfc.md
@@ -329,13 +329,38 @@ Adds 16 invariants to the 108 Wave 10 suite → **124 total**:
### Status
-111 plugins live across 9 Temporal task queues. Handlers in
-`services/handlers/*.py` stay as implementations that plugins call
-(Wave 11.D.1–6 inlined the trivial ones into the plugin files; complex
-handlers like WhatsApp RPC + Google Workspace + document pipeline
-stay delegated — those migrations are deferred polish). Sunset of the
-empty `nodes/{agents,services,triggers,tools,utilities}.py` bulk files
-+ dead dispatcher fallbacks is complete (Wave 11.D.13).
+111 plugins live across 9 Temporal task queues (`rest-api`,
+`ai-heavy`, `code-exec`, `triggers-poll`, `triggers-event`, `android`,
+`browser`, `messaging`, `machina-default`). Handler bodies are fully
+inlined into plugin files — `services/handlers/` shrank from
+**12.8K LOC / 16 files → 1.1K LOC / 4 files**. Only cross-cutting
+orchestration remains: `tools.py` (AI-tool dispatch + agent
+delegation through `BaseNode.execute()` via the node registry),
+`google_auth.py`, `triggers.py`. Sunset of the empty
+`nodes/{agents,services,triggers,tools,utilities}.py` bulk files +
+dead dispatcher fallbacks is complete (Wave 11.D.13).
+
+### Sub-waves shipped
+
+- **11.A / B / B.1** — `BaseNode` hierarchy, `ActionNode` /
+ `TriggerNode` / `ToolNode`, `__init_subclass__` registry writes.
+- **11.C** — `@Operation` decorator + multi-op dispatch.
+- **11.D.0–13** — handler inlining, bulk-file sunset, trigger
+ registry auto-population, dispatcher cleanup.
+- **11.E** — declarative `Credential` subclasses
+ (`ApiKeyCredential`, `OAuth2Credential`) with `inject()` methods
+ and auto-registry via `Credential.__init_subclass__`.
+- **11.E.1** — credentials modularised into per-domain
+ `server/nodes/<group>/_credentials.py` files (or inline for
+ single-use). **Central `server/credentials/` directory deleted.**
+ 18 `Credential` subclasses total.
+- **11.E.2 / E.3 / E.4** — credential polish + doc sync.
+- **11.F** — per-plugin Temporal activities
+ (`cls.as_activity()` named `node.{type}.v{version}`),
+ `TemporalWorkerPool` per task queue with tuned concurrency
+ (ai-heavy=4, rest-api=50, triggers-poll=100, etc.).
+- **11.G** — nodes cookbook (`server/nodes/README.md`) + CLAUDE.md
+ sync.
## References