Skip to content

Self-improving AI Employees for everyone

docs+refactor: prune stale CLAUDE.md instructions; clean up onboarding wizard

trohitgd87420d77d66
diff --git a/CLAUDE.md b/CLAUDE.md
index 12eb55bf..c9f92f57 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -527,20 +527,10 @@ class CacheEntry(SQLModel, table=True):
- `cleanup_expired_cache()` - Remove expired entries
## Codebase Summary
-- **Hybrid architecture**: Node.js + Python + React TypeScript
-- **107 implemented workflow nodes** with clean service separation (9 AI models + 3 AI agents/memory + 16 specialized agents + 1 skill + 5 dedicated tools + 3 search + 16 Android + 3 WhatsApp + 4 Twitter + 2 Telegram + 2 Social + 3 Location + 3 Code + 6 Utility + 6 Document + 2 Chat + 2 Scheduler + 2 Workflow + 7 Google Workspace + 1 Apify + 1 Crawlee + 1 Browser + 3 Email + 3 Proxy + 4 Filesystem/Shell + 1 Process Manager)
-- **WebSocket-First Architecture**: WebSocket as primary frontend-backend communication (89 message handlers)
-- **Recent optimizations**: REST APIs replaced with WebSocket, AI endpoints migrated to Python, Android automation integrated
-
-## Architecture Refactoring
-The project was completely refactored from schema-based node definitions to explicit INodeProperties interface system inspired by n8n architecture. Key changes:
-- **Pure INodeProperties System**: Removed all backward compatibility layers
-- **93 Implemented Node Components**: AI models, agents, skills, location services, Android automation, WhatsApp, Twitter/X, Telegram, social, code execution, HTTP/Webhook utilities, document processing, chat, schedulers, search, and proxy
-- **WebSocket-First Communication**: 125 WebSocket message handlers replace most REST API calls
-- **Resource-Operation Pattern**: Organized by functional categories (AI, Location, Android, WhatsApp)
-- **TypeScript-First**: Full type safety with proper interface alignment
-- **Code Cleanup**: Removed dead code, unused files, and legacy methods
-- **Android Integration**: 16 Android service nodes with ADB-based device automation
+- **Hybrid architecture**: Python (FastAPI + Pydantic plugins) + React/TypeScript frontend + Node.js subprocess for JS/TS code execution.
+- **Backend NodeSpec is the single source of truth.** Plugins live in [`server/nodes/<group>/<name>.py`](./server/nodes/) and auto-register via `BaseNode.__init_subclass__`. Authoritative node count is whatever globs out of `server/nodes/**/*.py` (excluding `_*.py` helpers and `__init__.py`); folders cover agent / model / android / google / whatsapp / twitter / telegram / social / email / search / scraper / document / code / filesystem / proxy / location / chat / text / scheduler / trigger / tool / utility / workflow / skill / browser / stripe.
+- **WebSocket-first frontend-backend communication.** Authoritative handler count is the size of the `MESSAGE_HANDLERS` dict in [`server/routers/websocket.py`](./server/routers/websocket.py) plus plugin-registered handlers via `services.ws_handler_registry`. Don't hand-maintain the count in this doc — it drifts on every plugin add.
+- **Plugin-first architecture (Wave 11).** One file = one node. `services/handlers/` shrank from 12.8K → 1.1K LOC across 16 → 4 files. 124 pytest invariants lock the contract.
## Frontend Performance Architecture
@@ -617,7 +607,7 @@ authoring model.
- `src/components/parameterPanel/MiddleSection.tsx` - Parameter panel middle section with conditional display logic
- `src/components/OutputPanel.tsx` - Connected node output display with drag mapping
- `src/components/LocationParameterPanel.tsx` - Location-specific parameter handling
-- `src/components/AIAgentNode.tsx` - Config-driven AI agent component supporting both aiAgent and chatAgent via AGENT_CONFIGS
+- `src/components/AIAgentNode.tsx` - Spec-driven agent canvas component. Reads `useNodeSpec(type)` for handles / icon / colour / displayName / uiHints; renders any plugin whose backend `component_kind` is `"agent"` or `"chat"`. No `AGENT_CONFIGS` map.
- `src/ParameterPanel.tsx` - Main parameter configuration modal
### AI Chat Model Components
@@ -669,13 +659,14 @@ Single source of truth: [client/src/index.css](./client/src/index.css). All toke
### WebSocket-First Architecture
The project uses WebSocket as the primary communication method between frontend and backend, replacing most REST API calls:
- `src/contexts/WebSocketContext.tsx` - Central WebSocket context with request/response pattern
-- `server/routers/websocket.py` - WebSocket endpoint with 89 message handlers
+- `server/routers/websocket.py` - WebSocket endpoint; the live handler set is the `MESSAGE_HANDLERS` dict plus plugin-registered handlers via `services.ws_handler_registry`. Don't hand-maintain a count here.
- `server/services/status_broadcaster.py` - Connection management and broadcasting
**Canvas mutations from the backend** -- any handler that needs to add / move / delete nodes or edges (e.g., auto-add-skill on tool connect, future workflow-template features, AI-suggested edits) returns a workflow-ops batch (`{operations: [...]}`) and the frontend applies it through `applyOperations` in [client/src/lib/workflowOps.ts](./client/src/lib/workflowOps.ts). Backend builders live in [server/services/workflow_ops.py](./server/services/workflow_ops.py). Full spec: [docs-internal/workflow_ops_protocol.md](./docs-internal/workflow_ops_protocol.md). Do not invent a parallel "modify the canvas" RPC for new features -- target this protocol.
## Implemented Node Types
-The following 92 nodes are currently implemented and functional:
+
+> **Authoritative source: backend plugin registry.** Glob [`server/nodes/**/*.py`](./server/nodes/) (excluding `_*.py` helpers and `__init__.py`) for the live count. The per-node descriptions below are reference material — they drift on every plugin add and should be cross-checked against [`server/nodes/README.md`](./server/nodes/README.md), the per-domain docs in `docs-internal/`, and the actual plugin classes before relying on any specific detail.
### AI Chat Models (9 nodes)
- **openaiChatModel**: OpenAI GPT models with response format options. O-series models (o1, o3, o4) support reasoning effort parameter.
@@ -835,12 +826,7 @@ The Master Skill node uses a custom split-panel editor (`MasterSkillEditor.tsx`)
- Default folder: `assistant`
**Icon Resolution Priority:**
-Skill icons are resolved in this order (node definition first for SVG support):
-1. `skillNodes.ts` node definition icon (supports SVG data URIs, e.g., WhatsApp logo)
-2. SKILL.md metadata `icon` field (emoji strings)
-3. Default fallback
-
-Implemented via `getNodeDefaults()` helper that looks up icon/color from `skillNodes.ts` by matching `skillName` property.
+Skill icons resolve via the central `visuals.json` registry — see "Icon + color — central `visuals.json` registry" below. The pre-Wave-10 `skillNodes.ts` + `getNodeDefaults()` helper that did per-skill icon overrides on the frontend was retired; icons + colours now live exclusively in [`server/nodes/visuals.json`](./server/nodes/visuals.json) and SKILL.md frontmatter for orphan skills (no node target).
**Keyboard Handling:**
The editor uses a native DOM `addEventListener('keydown')` on a wrapper div (via `useRef`) to `stopPropagation()` for Ctrl/Meta key events. This prevents React Flow's document-level `useKeyPress` hook from intercepting Ctrl+A (select all) and other Ctrl shortcuts inside the textarea. React synthetic `stopPropagation()` is insufficient because React Flow uses native `document.addEventListener`.
@@ -1746,8 +1732,8 @@ All scripts in `scripts/` are cross-platform Node.js (Windows, macOS, Linux, WSL
See **[Scripts Reference](./docs-internal/SCRIPTS.md)** for full documentation.
## Current Status
-✅ **INodeProperties System**: Fully implemented with 93 functional node components
-✅ **WebSocket-First Architecture**: 89 message handlers replacing REST APIs
+✅ **Plugin-first architecture (Wave 11)**: every node is one Python file under `server/nodes/<group>/<name>.py`; backend NodeSpec is the SSOT for icon, colour, handles, params, output schema, uiHints. Frontend renders via `useNodeSpec` + `componentKind` dispatch.
+✅ **WebSocket-First Architecture**: most frontend-backend RPC goes through WebSocket; live handler set lives in `MESSAGE_HANDLERS` in `server/routers/websocket.py`
✅ **Code Editor**: Python, JavaScript, and TypeScript executors with syntax-highlighted editor (react-simple-code-editor + prismjs) and console output
✅ **Node.js Executor**: Persistent Node.js server (Express + tsx) for fast JS/TS execution, replacing subprocess spawning
✅ **Component Palette**: Emoji icons with distinct dracula-themed category colors, localStorage persistence for collapsed sections
@@ -2312,68 +2298,43 @@ The token-based compaction threshold (`agent.compaction.ratio` × context_length
If the recursion cap is ever hit anyway, the `GraphRecursionError` handler appends a terminal `AIMessage` carrying a truncation note so `_extract_text_content` returns a usable partial response and the workflow continues — `_track_token_usage` and any post-loop persistence still run.
-### Config-Driven Component Design
-The `AIAgentNode.tsx` component uses a configuration-driven pattern to support multiple agent types from a single component.
+### Spec-driven component design (Wave 10.D)
+
+`AIAgentNode.tsx` knows nothing about specific agent types. It calls `useNodeSpec(type)` once and reads `handles`, `color`, `displayName`, `subtitle`, and `uiHints` from the cached `NodeSpec` ([`AIAgentNode.tsx:55-68`](./client/src/components/AIAgentNode.tsx#L55-L68)). The earlier 60-line `AGENT_CONFIGS` map (one entry per agent type, each with hardcoded `themeColorKey` + handle topology) was retired in Wave 10.D.
+
+Component dispatch lives in [`Dashboard.tsx:74-105`](./client/src/Dashboard.tsx#L74-L105):
-#### AGENT_CONFIGS Object
```typescript
-type ThemeColorKey = 'purple' | 'cyan' | 'green' | 'pink' | 'orange' | 'yellow' | 'red';
-
-interface AgentConfig {
- icon: React.ReactNode;
- title: string;
- subtitle: string;
- themeColorKey: ThemeColorKey; // References dracula theme constant
- bottomHandles: Array<{ id: string; label: string; position: string }>;
- leftHandles?: Array<{ id: string; label: string; position: string }>;
- topOutputHandle?: { id: string; label: string };
- width?: number;
- height?: number;
-}
+const COMPONENT_BY_KIND: Record<string, React.ComponentType<any>> = {
+ start: StartNode,
+ trigger: TriggerNode,
+ agent: AIAgentNode, // every plugin with component_kind="agent" routes here
+ chat: AIAgentNode,
+ model: SquareNode,
+ square: SquareNode,
+ tool: SquareNode,
+ generic: SquareNode,
+};
-// Color resolved at runtime: dracula[config.themeColorKey]
-const AGENT_CONFIGS: Record<string, AgentConfig> = {
- aiAgent: {
- icon: <RobotIcon />,
- title: 'AI Agent',
- subtitle: 'LangGraph Agent',
- themeColorKey: 'purple',
- bottomHandles: [
- { id: 'input-skill', label: 'Skill', position: '25%' },
- { id: 'input-tools', label: 'Tool', position: '75%' },
- ],
- leftHandles: [
- { id: 'input-memory', label: 'Memory', position: '55%' },
- { id: 'input-task', label: 'Task', position: '85%' },
- ],
- },
- chatAgent: {
- icon: <ZeenieIcon />,
- title: 'Zeenie',
- subtitle: 'Conversational Agent',
- themeColorKey: 'cyan',
- bottomHandles: [
- { id: 'input-skill', label: 'Skill', position: '25%' },
- { id: 'input-tools', label: 'Tool', position: '75%' },
- ],
- leftHandles: [
- { id: 'input-memory', label: 'Memory', position: '55%' },
- { id: 'input-task', label: 'Task', position: '85%' },
- ],
- },
- // ... 11 specialized agents (android_agent, coding_agent, web_agent, task_agent,
- // social_agent, travel_agent, tool_agent, productivity_agent, payments_agent, consumer_agent, autonomous_agent)
- // each with themeColorKey, standard Skill/Tool bottom handles, Memory/Task left handles
+const createNodeTypes = () => {
+ const types: Record<string, React.ComponentType<any>> = {};
+ listCachedNodeSpecs().forEach(spec => {
+ const kind = spec.componentKind;
+ if (kind && COMPONENT_BY_KIND[kind]) {
+ types[spec.type] = COMPONENT_BY_KIND[kind];
+ } else if (spec.type === 'teamMonitor') {
+ types[spec.type] = TeamMonitorNode;
+ } else if ((spec.uiHints as any)?.isMasterSkillEditor === true) {
+ types[spec.type] = ToolkitNode;
+ } else {
+ types[spec.type] = SquareNode;
+ }
+ });
+ return types;
};
```
-#### Component Selection
-In `Dashboard.tsx`, both agent types map to the same component:
-```typescript
-} else if (type === 'aiAgent' || type === 'chatAgent') {
- types[type] = AIAgentNode;
-}
-```
+The dispatch keys off `spec.componentKind` (a backend-declared string), never `spec.type`. Specialized agent visuals (icon, color, handles, subtitle, width, height) all come from the spec. Icons + colours live in [`server/nodes/visuals.json`](./server/nodes/visuals.json) — not in the frontend component.
### AI Agent vs Zeenie
@@ -2497,45 +2458,23 @@ Child broadcasts its own status updates (executing, success, error)
### Specialized AI Agents
-The system supports specialized agent variants that inherit from the base AI Agent architecture:
-
-| Agent Type | Node Type | Icon | Theme Color (dracula) |
-|------------|-----------|------|-----------------------|
-| AI Agent | `aiAgent` | Robot SVG | purple |
-| Zeenie | `chatAgent` | Chat SVG | cyan |
-| Android Control | `android_agent` | robot | green |
-| Coding Agent | `coding_agent` | laptop | cyan |
-| Web Control | `web_agent` | globe | pink |
-| Task Management | `task_agent` | clipboard | purple |
-| Social Media | `social_agent` | phone | green |
-| Travel Agent | `travel_agent` | plane | orange |
-| Tool Agent | `tool_agent` | wrench | yellow |
-| Productivity | `productivity_agent` | clock | cyan |
-| Payments | `payments_agent` | credit card | green |
-| Consumer | `consumer_agent` | cart | purple |
-| Autonomous | `autonomous_agent` | target | purple |
-| Orchestrator | `orchestrator_agent` | conductor | cyan |
-| AI Employee | `ai_employee` | briefcase | purple |
-| RLM Agent | `rlm_agent` | brain | orange |
-| Deep Agent | `deep_agent` | brain (U+1F9E0) | green |
-
-All specialized agents share the same handle configuration:
+The system ships specialized agent variants — each is one Python file under [`server/nodes/agent/`](./server/nodes/agent/) inheriting `SpecializedAgentBase`. Authoritative list: glob that folder. Per-type display name / subtitle / description live on the plugin class; icon + colour live in [`server/nodes/visuals.json`](./server/nodes/visuals.json). Do not maintain a hand-list of agent types in this doc — it drifts on every plugin add.
+
+Standard handle topology (declared on `SpecializedAgentBase` via `std_agent_handles()`):
- **Left**: `input-main` (Input, 30%), `input-memory` (Memory, 55%), `input-task` (Task, 85%)
- **Bottom**: `input-skill` (Skill, 25%), `input-tools` (Tool, 75%)
- **Top**: `output-top` (Output)
-**Team Lead Agents** (`orchestrator_agent`, `ai_employee`) have an additional handle:
-- **Bottom**: `input-teammates` (Teammates, 50%) - Connect specialized agents here for delegation
+**Team Lead Agents** (`orchestrator_agent`, `ai_employee`) declare an extra `input-teammates` handle on the bottom (50%) for delegation. They are listed in `TEAM_LEAD_TYPES` in [`client/src/components/TeamMonitorNode.tsx`](./client/src/components/TeamMonitorNode.tsx) (frontend tribal array — flagged as tech debt; see "remaining tribal arrays" note).
-The `AIAgentNode.tsx` component uses `AGENT_CONFIGS` to render all agent types with their specific icons, titles, and theme colors.
+`AIAgentNode.tsx` is type-agnostic: it calls `useNodeSpec(type)` and renders whatever handles/icon/color the spec returns — no `AGENT_CONFIGS` map.
## Architecture Patterns
-- **Resource-Operation Pattern**: Nodes organized by functional resources
-- **TypeScript-First**: 90.4% TypeScript coverage with strict typing
-- **Component-Driven**: Modular UI components with clear responsibilities
-- **State Management**: Zustand for reactive application state
-- **Interface Compatibility**: Dual interface support for smooth transitions
-- **Execution Pipeline**: Async component execution with result handling
+- **Plugin-first (Wave 11).** One file per node under [`server/nodes/<group>/<name>.py`](./server/nodes/) subclassing `BaseNode` / `ActionNode` / `TriggerNode` / `ToolNode`. Auto-registers via `__init_subclass__`. See [`docs-internal/plugin_system.md`](./docs-internal/plugin_system.md).
+- **Backend NodeSpec is the SSOT** for icon, colour, handles, params, output schema, uiHints, palette group. Frontend consumes via `useNodeSpec(type)` and adapts the JSON Schema → `INodeTypeDescription` shape through [`adapters/nodeSpecToDescription.ts`](./client/src/adapters/nodeSpecToDescription.ts) (legacy interface kept as a render contract; not a parallel schema system).
+- **Component-driven frontend.** shadcn/ui primitives + Tailwind tokens; canvas nodes are spec-driven (see "Spec-driven component design" above).
+- **State management.** TanStack Query owns server-backed data; Zustand (`useAppStore`, `nodeStatusStore`) owns UI state and slice-subscribed high-frequency push state. Slice-selector reads only — never whole-store destructure (see "Frontend Performance Architecture").
+- **Execution pipeline.** Temporal-distributed activities for plugin execution; `WorkflowExecutor` for parallel orchestration; per-node retry / timeout / heartbeat declared on the plugin class.
## File Structure Cleanup
**Removed Files:**
@@ -3872,66 +3811,33 @@ Tool Node (calculatorTool) → (tool output) → AI Agent (input-tools handle)
| `server/services/ai.py` | `_get_tool_schema()` - Pydantic schemas for tools |
| `server/services/handlers/ai.py` | Tool discovery from edges |
-### Tool Node Definition Pattern
-```typescript
-// In toolNodes.ts
-calculatorTool: {
- displayName: 'Calculator Tool',
- name: 'calculatorTool',
- icon: '...',
- group: ['tool', 'ai'], // 'tool' marks as tool node
- outputs: [{
- name: 'tool',
- type: 'main' as NodeConnectionType,
- description: 'Connect to AI Agent tool handle'
- }],
- properties: [
- { name: 'toolName', type: 'string', default: 'calculator' },
- { name: 'toolDescription', type: 'string', default: '...' }
- ]
-}
-```
+### Adding a new tool or specialized agent (Wave 11)
-### Specialized Agent Node Definition Pattern
-```typescript
-// In specializedAgentNodes.ts - uses shared AI_AGENT_PROPERTIES for full AI configuration
-android_agent: {
- displayName: 'Android Control Agent',
- name: 'android_agent',
- icon: '📱',
- group: ['agent', 'ai'], // 'agent' for category placement
- inputs: [
- { name: 'main', displayName: 'Input', type: 'main' as NodeConnectionType },
- { name: 'skill', displayName: 'Skill', type: 'main' as NodeConnectionType },
- { name: 'memory', displayName: 'Memory', type: 'main' as NodeConnectionType },
- { name: 'tools', displayName: 'Tool', type: 'main' as NodeConnectionType }
- ],
- outputs: [{ name: 'main', displayName: 'Output', type: 'main' as NodeConnectionType }],
- properties: AI_AGENT_PROPERTIES // Full AI configuration (provider, model, prompt, etc.)
-}
-```
+**Single source of truth: [`server/nodes/README.md`](./server/nodes/README.md)** (5-minute recipe) and [`docs-internal/plugin_system.md`](./docs-internal/plugin_system.md) (full reference). The pre-Wave-11 `toolNodes.ts` / `specializedAgentNodes.ts` / `AGENT_CONFIGS` files do not exist — the canonical authoring shape is one Python file.
-### Adding New Tools
-1. **Frontend**: Add node definition in `toolNodes.ts` with `group: ['tool', 'ai']`
-2. **Schema**: Add Pydantic schema in `ai.py` `_get_tool_schema()`
-3. **Handler**: Add execution handler in `tools.py` and dispatcher case in `execute_tool()`
-4. **TOOL_NODE_TYPES**: Add to array in `toolNodes.ts`
+The whole workflow:
+
+```python
+# server/nodes/tool/<name>.py ← for a tool
+# server/nodes/agent/<name>.py ← for a specialized agent
+class MyTool(ToolNode): # or SpecializedAgentBase for an agent
+ type = "myTool"
+ display_name = "My Tool"
+ group = ("tool", "ai")
+ component_kind = "tool" # or "agent"
+ Params = MyParams # Pydantic — feeds UI + AI tool schema
+ Output = MyOutput
+ @Operation("run")
+ async def run(self, ctx, params): ...
+```
-### Adding New Specialized Agents
-**Frontend (5 files):**
-1. **Node Definition**: Add to `specializedAgentNodes.ts` with `group: ['agent', 'ai']`, `properties: AI_AGENT_PROPERTIES`, and `defaults.color: dracula.<color>`
-2. **SPECIALIZED_AGENT_TYPES**: Add to array in `specializedAgentNodes.ts`
-3. **AIAgentNode Config**: Add to `AGENT_CONFIGS` in `AIAgentNode.tsx` with icon, title, subtitle, `themeColorKey`, standard handles (Skill 25%, Tool 75%, Memory 70%), 260x160px
-4. **MiddleSection.tsx**: Add to `AGENT_WITH_SKILLS_TYPES` array
-5. **InputSection.tsx**: Add to both `AGENT_WITH_SKILLS_TYPES` and `aiAgentTypes` arrays
+`BaseNode.__init_subclass__` registers the class into `NODE_METADATA`, `NODE_INPUT_MODELS`, `NODE_OUTPUT_SCHEMAS`, `_HANDLER_REGISTRY`, and `_NODE_CLASS_REGISTRY` on import. NodeSpec emits at `GET /api/schemas/nodes/<type>/spec.json`. The frontend auto-discovers via `useNodeSpec` + `componentKind` dispatch (see "Spec-driven component design" above). Icon + colour go in [`server/nodes/visuals.json`](./server/nodes/visuals.json).
-**Backend (4 files):**
-6. **constants.py**: Add to `AI_AGENT_TYPES` frozenset
-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
+**Cross-cutting edits that are still required (small):**
+- New specialized agent: add the agent's `type` string to the delegation-check tuple in [`server/services/handlers/tools.py:execute_tool()`](./server/services/handlers/tools.py) (~line 224) so the parent agent's `delegate_to_*` tool finds it. Also update `AI_AGENT_TYPES` frozenset in [`server/constants.py`](./server/constants.py) — used for legacy delegation checks. Both are flagged as tech debt; see "remaining tribal arrays" note.
+- Brand-new uiHint flag: add to `INodeUIHints` in [`client/src/types/INodeProperties.ts`](./client/src/types/INodeProperties.ts) AND to the `known` set in `test_ui_hints_only_carry_known_flags` (`server/tests/test_node_spec.py`).
-**No changes needed:** `Dashboard.tsx` auto-maps via `SPECIALIZED_AGENT_TYPES.forEach()`
+**No edits needed:** any TypeScript node definition file, `_get_tool_schema()`, `AGENT_CONFIGS`, `AGENT_WITH_SKILLS_TYPES`, `aiAgentTypes`, `Dashboard.tsx`, `MiddleSection.tsx`, `InputSection.tsx`, or any of the other arrays the pre-Wave-11 docs listed.
### Tool Execution Animation
Tool nodes display execution status via the standard node status system:
@@ -5139,7 +5045,7 @@ This function:
- **Performance**: Fast HMR updates and clean TypeScript compilation
- **AI Architecture**: 5-layer system with factory pattern and secure credential management
- **Android Architecture**: Factory-based node creation with ADB integration for device automation
-- **WebSocket-First Architecture**: 89 message handlers replace REST APIs for parameters, execution, API keys, Android, WhatsApp, and skill operations
+- **WebSocket-First Architecture**: most frontend-backend RPC (parameters, execution, API keys, Android, WhatsApp, skill operations) goes through WebSocket. Live handler set lives in the `MESSAGE_HANDLERS` dict in `server/routers/websocket.py` plus plugin-registered handlers via `services.ws_handler_registry`.
- **WebSocket Hooks**: Dedicated React hooks (useWhatsApp, useExecution, useApiKeys, useAndroidOperations, useParameterPanel) for clean component integration
- **WebSocket Support**: Persistent remote Android device connections via WebSocket proxy with background tasks
- Connection stays alive across multiple API requests until switched to local ADB
diff --git a/client/src/components/onboarding/OnboardingWizard.tsx b/client/src/components/onboarding/OnboardingWizard.tsx
index 9b013ea8..b3759e43 100644
--- a/client/src/components/onboarding/OnboardingWizard.tsx
+++ b/client/src/components/onboarding/OnboardingWizard.tsx
@@ -2,10 +2,10 @@ import React from 'react';
import { ArrowLeft, ArrowRight, Check } from 'lucide-react';
import { Button } from '@/components/ui/button';
+import { ActionButton } from '@/components/ui/action-button';
import { cn } from '@/lib/utils';
import Modal from '../ui/Modal';
import { useOnboarding } from '../../hooks/useOnboarding';
-import { useAppTheme } from '../../hooks/useAppTheme';
import WelcomeStep from './steps/WelcomeStep';
import ConceptsStep from './steps/ConceptsStep';
import ApiKeyStep from './steps/ApiKeyStep';
@@ -17,42 +17,33 @@ interface OnboardingWizardProps {
reopenTrigger?: number;
}
-const stepItems = [
- { title: 'Welcome' },
- { title: 'Concepts' },
- { title: 'API Keys' },
- { title: 'Canvas' },
- { title: 'Get Started' },
+// Single source of truth for the wizard's step list. Length feeds the
+// hook's totalSteps and the progress indicator; renderer is dispatched
+// by index. Adding a step is a one-line edit here.
+const STEPS: { title: string; render: (props: { onOpenCredentials: () => void }) => React.ReactNode }[] = [
+ { title: 'Welcome', render: () => <WelcomeStep /> },
+ { title: 'Concepts', render: () => <ConceptsStep /> },
+ { title: 'API Keys', render: ({ onOpenCredentials }) => <ApiKeyStep onOpenCredentials={onOpenCredentials} /> },
+ { title: 'Canvas', render: () => <CanvasStep /> },
+ { title: 'Get Started', render: () => <GetStartedStep /> },
];
const OnboardingWizard: React.FC<OnboardingWizardProps> = ({ onOpenCredentials, reopenTrigger }) => {
- const theme = useAppTheme();
const {
isVisible,
currentStep,
isLoading,
hasChecked,
- totalSteps,
nextStep,
prevStep,
skip,
complete,
- } = useOnboarding(reopenTrigger);
+ } = useOnboarding(reopenTrigger, STEPS.length);
if (!isVisible || !hasChecked || isLoading) return null;
- const isLastStep = currentStep >= totalSteps - 1;
-
- const renderStep = () => {
- switch (currentStep) {
- case 0: return <WelcomeStep />;
- case 1: return <ConceptsStep />;
- case 2: return <ApiKeyStep onOpenCredentials={onOpenCredentials} />;
- case 3: return <CanvasStep />;
- case 4: return <GetStartedStep />;
- default: return <WelcomeStep />;
- }
- };
+ const isLastStep = currentStep >= STEPS.length - 1;
+ const safeIndex = Math.min(Math.max(currentStep, 0), STEPS.length - 1);
return (
<Modal
@@ -63,17 +54,13 @@ const OnboardingWizard: React.FC<OnboardingWizardProps> = ({ onOpenCredentials,
maxHeight="95vh"
autoHeight
>
- <div style={{
- display: 'flex',
- flexDirection: 'column',
- padding: '16px 20px 12px',
- }}>
+ <div className="flex flex-col px-5 pt-4 pb-3">
{/* Progress steps */}
<ol className="mb-4 flex w-full items-center">
- {stepItems.map((item, idx) => {
+ {STEPS.map((item, idx) => {
const status: 'completed' | 'active' | 'upcoming' =
idx < currentStep ? 'completed' : idx === currentStep ? 'active' : 'upcoming';
- const isLast = idx === stepItems.length - 1;
+ const isLast = idx === STEPS.length - 1;
return (
<li key={item.title} className="flex flex-1 items-center gap-2">
<div
@@ -108,30 +95,16 @@ const OnboardingWizard: React.FC<OnboardingWizardProps> = ({ onOpenCredentials,
</ol>
{/* Step content */}
- <div style={{
- overflowY: 'auto',
- minHeight: 500,
- maxHeight: 'calc(95vh - 200px)',
- paddingRight: 4,
- }}>
- {renderStep()}
+ <div className="overflow-y-auto pr-1 max-h-[calc(95vh-200px)]">
+ {STEPS[safeIndex].render({ onOpenCredentials })}
</div>
{/* Footer navigation */}
- <div style={{
- display: 'flex',
- justifyContent: 'space-between',
- alignItems: 'center',
- paddingTop: 12,
- marginTop: 12,
- borderTop: `1px solid ${theme.colors.border}`,
- }}>
- {/* Left: Skip */}
+ <div className="flex items-center justify-between border-t border-border pt-3 mt-3">
<Button variant="ghost" size="sm" onClick={skip} className="text-muted-foreground">
Skip for now
</Button>
- {/* Right: Back + Next/Finish */}
<div className="flex items-center gap-2">
{currentStep > 0 && (
<Button variant="outline" onClick={prevStep}>
@@ -140,27 +113,15 @@ const OnboardingWizard: React.FC<OnboardingWizardProps> = ({ onOpenCredentials,
</Button>
)}
{isLastStep ? (
- <Button
- onClick={complete}
- style={{
- backgroundColor: theme.dracula.green,
- borderColor: theme.dracula.green,
- }}
- >
+ <ActionButton intent="run" onClick={complete}>
<Check className="h-4 w-4" />
Start Building
- </Button>
+ </ActionButton>
) : (
- <Button
- onClick={nextStep}
- style={{
- backgroundColor: theme.dracula.purple,
- borderColor: theme.dracula.purple,
- }}
- >
+ <ActionButton intent="tools" onClick={nextStep}>
Next
<ArrowRight className="h-4 w-4" />
- </Button>
+ </ActionButton>
)}
</div>
</div>
diff --git a/client/src/components/onboarding/nodeRoleClasses.ts b/client/src/components/onboarding/nodeRoleClasses.ts
new file mode 100644
index 00000000..199c9785
--- /dev/null
+++ b/client/src/components/onboarding/nodeRoleClasses.ts
@@ -0,0 +1,23 @@
+/**
+ * Shared role-to-Tailwind-classes map for the onboarding step cards.
+ * Each role keys into the existing `--node-X` triplet (soft bg + border
+ * + accent text). Co-located with the onboarding folder because both
+ * consumers (ConceptsStep, GetStartedStep) live here.
+ */
+
+export type NodeRole = 'model' | 'skill' | 'agent' | 'workflow' | 'trigger';
+
+export interface NodeRoleClasses {
+ /** Tinted background + border for the card surface. */
+ card: string;
+ /** Accent text colour matching the card's role. */
+ text: string;
+}
+
+export const NODE_ROLE_CLASSES: Record<NodeRole, NodeRoleClasses> = {
+ model: { card: 'bg-node-model-soft border-node-model-border', text: 'text-node-model' },
+ skill: { card: 'bg-node-skill-soft border-node-skill-border', text: 'text-node-skill' },
+ agent: { card: 'bg-node-agent-soft border-node-agent-border', text: 'text-node-agent' },
+ workflow: { card: 'bg-node-workflow-soft border-node-workflow-border', text: 'text-node-workflow' },
+ trigger: { card: 'bg-node-trigger-soft border-node-trigger-border', text: 'text-node-trigger' },
+};
diff --git a/client/src/components/onboarding/steps/CanvasStep.tsx b/client/src/components/onboarding/steps/CanvasStep.tsx
index 523a330f..05f153c0 100644
--- a/client/src/components/onboarding/steps/CanvasStep.tsx
+++ b/client/src/components/onboarding/steps/CanvasStep.tsx
@@ -19,13 +19,19 @@ const CanvasStep: React.FC = () => {
</p>
</div>
- {/* Visual layout diagram */}
+ {/*
+ * Visual layout diagram. Region tints mirror the live UI's
+ * accent colours via the predefined --node-X-soft tokens — no
+ * opacity arithmetic at the call site. Each region maps to a
+ * node-group colour: toolbar→workflow (orange), sidebar→model
+ * (cyan), canvas→agent (purple), palette→skill (green),
+ * console→trigger (pink). Decorative use of the dracula text
+ * colours is permitted (tutorial diagram intentionally mirrors
+ * the live UI palette).
+ */}
<div className="mb-4 overflow-hidden rounded-lg border border-border">
{/* Toolbar */}
- <div
- className="flex items-center gap-1.5 border-b border-border px-2.5 py-1.5"
- style={{ backgroundColor: 'hsl(var(--dracula-orange) / 0.12)' }}
- >
+ <div className="flex items-center gap-1.5 border-b border-border bg-node-workflow-soft px-2.5 py-1.5">
<Wrench className="h-3 w-3 text-dracula-orange" />
<span className="text-xs font-semibold text-dracula-orange">Toolbar</span>
<div className="flex-1" />
@@ -37,10 +43,7 @@ const CanvasStep: React.FC = () => {
{/* Main area */}
<div className="flex h-[120px]">
{/* Sidebar */}
- <div
- className="flex w-20 flex-col gap-1 border-r border-border p-1.5"
- style={{ backgroundColor: 'hsl(var(--dracula-cyan) / 0.08)' }}
- >
+ <div className="flex w-20 flex-col gap-1 border-r border-border bg-node-model-soft p-1.5">
<span className="text-[9px] font-semibold text-dracula-cyan">Sidebar</span>
{['Workflow 1', 'Workflow 2'].map((w) => (
<div key={w} className="rounded-sm bg-muted px-1 py-0.5 text-[8px] text-muted-foreground">
@@ -50,10 +53,7 @@ const CanvasStep: React.FC = () => {
</div>
{/* Canvas */}
- <div
- className="relative flex flex-1 items-center justify-center"
- style={{ backgroundColor: 'hsl(var(--dracula-purple) / 0.06)' }}
- >
+ <div className="relative flex flex-1 items-center justify-center bg-node-agent-soft">
<div className="text-center">
<Layout className="mx-auto h-5 w-5 text-dracula-purple opacity-50" />
<div className="mt-0.5 text-[9px] text-dracula-purple">Canvas</div>
@@ -61,10 +61,7 @@ const CanvasStep: React.FC = () => {
</div>
{/* Palette */}
- <div
- className="flex w-20 flex-col gap-1 border-l border-border p-1.5"
- style={{ backgroundColor: 'hsl(var(--dracula-green) / 0.08)' }}
- >
+ <div className="flex w-20 flex-col gap-1 border-l border-border bg-node-skill-soft p-1.5">
<span className="text-[9px] font-semibold text-dracula-green">Palette</span>
{['AI Agents', 'AI Models', 'Skills'].map((c) => (
<div key={c} className="rounded-sm bg-muted px-1 py-0.5 text-[8px] text-muted-foreground">
@@ -75,10 +72,7 @@ const CanvasStep: React.FC = () => {
</div>
{/* Console */}
- <div
- className="flex items-center gap-1.5 border-t border-border px-2.5 py-1.5"
- style={{ backgroundColor: 'hsl(var(--dracula-pink) / 0.08)' }}
- >
+ <div className="flex items-center gap-1.5 border-t border-border bg-node-trigger-soft px-2.5 py-1.5">
<Terminal className="h-3 w-3 text-dracula-pink" />
<span className="text-xs font-semibold text-dracula-pink">Console</span>
<div className="flex-1" />
diff --git a/client/src/components/onboarding/steps/ConceptsStep.tsx b/client/src/components/onboarding/steps/ConceptsStep.tsx
index b84adc18..d2fe87b5 100644
--- a/client/src/components/onboarding/steps/ConceptsStep.tsx
+++ b/client/src/components/onboarding/steps/ConceptsStep.tsx
@@ -1,15 +1,6 @@
import React from 'react';
import { LayoutGrid, GitBranch, Bot, Wrench, ArrowLeftRight } from 'lucide-react';
-
-type NodeRole = 'model' | 'skill' | 'agent' | 'workflow' | 'trigger';
-
-const ROLE_CLASSES: Record<NodeRole, { card: string; text: string }> = {
- model: { card: 'bg-node-model-soft border-node-model-border', text: 'text-node-model' },
- skill: { card: 'bg-node-skill-soft border-node-skill-border', text: 'text-node-skill' },
- agent: { card: 'bg-node-agent-soft border-node-agent-border', text: 'text-node-agent' },
- workflow: { card: 'bg-node-workflow-soft border-node-workflow-border', text: 'text-node-workflow' },
- trigger: { card: 'bg-node-trigger-soft border-node-trigger-border', text: 'text-node-trigger' },
-};
+import { NODE_ROLE_CLASSES, type NodeRole } from '../nodeRoleClasses';
const concepts: { Icon: typeof LayoutGrid; title: string; desc: string; role: NodeRole }[] = [
{
@@ -56,7 +47,7 @@ const ConceptsStep: React.FC = () => {
<div className="flex w-full flex-col gap-2.5">
{concepts.map((c) => {
- const classes = ROLE_CLASSES[c.role];
+ const classes = NODE_ROLE_CLASSES[c.role];
return (
<div
key={c.title}
diff --git a/client/src/components/onboarding/steps/GetStartedStep.tsx b/client/src/components/onboarding/steps/GetStartedStep.tsx
index f341f2ac..b83dd4b8 100644
--- a/client/src/components/onboarding/steps/GetStartedStep.tsx
+++ b/client/src/components/onboarding/steps/GetStartedStep.tsx
@@ -2,15 +2,7 @@ import React from 'react';
import { Play, FlaskConical, BookOpen, Settings } from 'lucide-react';
import { Card, CardContent } from '@/components/ui/card';
import { Badge } from '@/components/ui/badge';
-
-type NodeRole = 'skill' | 'agent' | 'model' | 'workflow';
-
-const ROLE_CLASSES: Record<NodeRole, { card: string; text: string }> = {
- skill: { card: 'bg-node-skill-soft border-node-skill-border', text: 'text-node-skill' },
- agent: { card: 'bg-node-agent-soft border-node-agent-border', text: 'text-node-agent' },
- model: { card: 'bg-node-model-soft border-node-model-border', text: 'text-node-model' },
- workflow: { card: 'bg-node-workflow-soft border-node-workflow-border', text: 'text-node-workflow' },
-};
+import { NODE_ROLE_CLASSES, type NodeRole } from '../nodeRoleClasses';
type Tip = {
Icon: typeof Play;
@@ -69,7 +61,7 @@ const GetStartedStep: React.FC = () => {
<div className="flex w-full flex-col gap-2.5">
{tips.map(({ Icon, title, desc, role }, i) => {
- const classes = ROLE_CLASSES[role];
+ const classes = NODE_ROLE_CLASSES[role];
return (
<Card key={i} className={classes.card}>
<CardContent className="flex items-start gap-2.5 p-3">
diff --git a/client/src/hooks/useOnboarding.ts b/client/src/hooks/useOnboarding.ts
index fa73f2b8..1bb9111f 100644
--- a/client/src/hooks/useOnboarding.ts
+++ b/client/src/hooks/useOnboarding.ts
@@ -12,9 +12,21 @@ export interface OnboardingState {
hasChecked: boolean;
}
-const TOTAL_STEPS = 5;
+const DEFAULT_TOTAL_STEPS = 5;
-export const useOnboarding = (reopenTrigger?: number) => {
+/**
+ * Onboarding wizard state hook.
+ *
+ * @param reopenTrigger - bump from SettingsPanel to replay the wizard.
+ * @param totalSteps - number of steps the wizard will render. Caller
+ * owns the step list (`STEPS.length` in OnboardingWizard); the hook
+ * uses this only to detect last-step completion. Defaults to 5 for
+ * backwards compatibility.
+ */
+export const useOnboarding = (
+ reopenTrigger?: number,
+ totalSteps: number = DEFAULT_TOTAL_STEPS,
+) => {
const settingsQuery = useUserSettingsQuery();
const saveSettings = useSaveUserSettingsMutation();
const [state, setState] = useState<OnboardingState>({
@@ -77,14 +89,14 @@ export const useOnboarding = (reopenTrigger?: number) => {
const nextStep = useCallback(() => {
setState((prev) => {
const next = prev.currentStep + 1;
- if (next >= TOTAL_STEPS) {
- saveProgress(TOTAL_STEPS, true);
+ if (next >= totalSteps) {
+ saveProgress(totalSteps, true);
return { ...prev, currentStep: next, isCompleted: true, isVisible: false };
}
saveProgress(next, false);
return { ...prev, currentStep: next };
});
- }, [saveProgress]);
+ }, [saveProgress, totalSteps]);
const prevStep = useCallback(() => {
setState((prev) => {
@@ -100,13 +112,13 @@ export const useOnboarding = (reopenTrigger?: number) => {
}, [saveProgress, state.currentStep]);
const complete = useCallback(() => {
- saveProgress(TOTAL_STEPS, true);
+ saveProgress(totalSteps, true);
setState((prev) => ({ ...prev, isVisible: false, isCompleted: true }));
- }, [saveProgress]);
+ }, [saveProgress, totalSteps]);
return {
...state,
- totalSteps: TOTAL_STEPS,
+ totalSteps,
nextStep,
prevStep,
skip,