Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
docs: Wave 11 final pass — refresh CLAUDE.md, plugin_system, node_creation, RFC
trohitga0cd1c43b0ad
diff --git a/CLAUDE.md b/CLAUDE.mdindex 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_agentSPECIALIZED_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 servicediff --git a/docs-internal/node_creation.md b/docs-internal/node_creation.mdindex 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.mdindex 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 16files / 12,800 LOC):diff --git a/docs-internal/schema_source_of_truth_rfc.md b/docs-internal/schema_source_of_truth_rfc.mdindex 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