Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
docs: sweep md files for Wave 3 backend-schema + AlertDialog patterns
trohitgb6ee1e20e57a
diff --git a/CLAUDE.md b/CLAUDE.mdindex 4b20693c..67c1c2d5 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -9,8 +9,9 @@ This is a React Flow-based workflow automation platform implementing n8n-inspire| Document | Description ||----------|-------------|-| **[Frontend Architecture](./docs-internal/frontend_architecture.md)** | Current frontend stack (React 19 + Vite + Tailwind v4 + shadcn/ui + Radix + RHF/zod + TanStack Query + Zustand). Tokens, primitives, forms, credentials exemplar. |-| **[UI Migration Plan](./docs-internal/ui_migration_plan.md)** | antd → shadcn/ui migration plan + completion log. Phases 0-5, 7 done; phase 6 (ParameterRenderer → JSON Forms) deferred. |+| **[Frontend Architecture](./docs-internal/frontend_architecture.md)** | Current frontend stack (React 19 + Vite + Tailwind v4 + shadcn/ui + Radix + RHF/zod + TanStack Query + Zustand). Tokens, primitives, forms, credentials exemplar, ownership boundary, `uiHints` catalogue. |+| **[UI Migration Plan](./docs-internal/ui_migration_plan.md)** | antd → shadcn/ui migration plan + completion log. Waves 1–3 done; Phase 6 (ParameterRenderer → widget registry) deferred pending backend `get_node_spec`. |+| **[Schema Source of Truth RFC](./docs-internal/schema_source_of_truth_rfc.md)** | Wave 3 decision: node output shapes live on the backend (Pydantic → JSON Schema) and the frontend fetches them lazy, n8n-style. Defines `GET /api/schemas/nodes/{type}.json` + `get_node_output_schema` WS handler. || **[Node Creation Guide](./docs-internal/node_creation.md)** | Complete guide for creating new nodes (frontend definitions, backend handlers, config nodes, triggers) || **[AI Tool Node Guide](./docs-internal/ai_tool_node_creation.md)** | Detailed guide for creating dedicated AI Agent tool nodes (schemas, handlers, toolkits) || **[Specialized Agent Guide](./docs-internal/specialized_agent_node_creation.md)** | Guide for creating specialized AI agents (Android, Coding, Web, Task, Social, Travel, Tool, Productivity, Payments, Consumer) with full AI configuration |@@ -2210,28 +2211,34 @@ def extract_thinking_from_response(response, provider: str) -> Optional[str]:#### Output Schema for Connected NodesThe `thinking` field is available in Input Data & Variables for downstream nodes. This schema applies to all AI nodes including chat models and specialized agents.-```typescript-// In InputSection.tsx-const sampleSchemas = {- ai: {- response: 'string',- thinking: 'string', // Available for drag-and-drop mapping- model: 'string',- provider: 'string',- finish_reason: 'string',- timestamp: 'string'- }-};+**Source of truth (Wave 3, April 2026):** runtime output shapes live on the **backend**, not the frontend. Declared in Pydantic models at `server/services/node_output_schemas.py` and served lazy via `GET /api/schemas/nodes/{node_type}.json` / the `get_node_output_schema` WebSocket handler. The frontend's InputSection prefers real execution data, falls back to the backend schema, then an empty state. See [docs-internal/schema_source_of_truth_rfc.md](./docs-internal/schema_source_of_truth_rfc.md).-// Node types that use the AI output schema-const aiAgentTypes = [- 'aiAgent', 'chatAgent',- 'android_agent', 'coding_agent', 'web_agent', 'task_agent', 'social_agent',- 'travel_agent', 'tool_agent', 'productivity_agent', 'payments_agent', 'consumer_agent'-];-const isAI = nodeTypeLower.includes('chatmodel') || aiAgentTypes.includes(nodeType);+```python+# server/services/node_output_schemas.py+class AIAgentOutput(_OutputBase):+ response: Optional[str] = None+ thinking: Optional[str] = None # Available for drag-and-drop mapping+ model: Optional[str] = None+ provider: Optional[str] = None+ finish_reason: Optional[str] = None+ timestamp: Optional[str] = None++# Shared across every LLM-backed agent + chat model:+_AGENT_TYPES = ['aiAgent', 'chatAgent', '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', 'claude_code_agent', 'deep_agent']+_CHAT_MODEL_TYPES = ['openaiChatModel', 'anthropicChatModel', 'geminiChatModel', ...]+NODE_OUTPUT_SCHEMAS = {+ **{t: AIAgentOutput for t in _AGENT_TYPES},+ **{t: AIAgentOutput for t in _CHAT_MODEL_TYPES},+ # ...+}```+Adding a new node type's output shape: define one Pydantic model, register it in `NODE_OUTPUT_SCHEMAS`. Zero frontend change.+#### UI Display (`client/src/components/ui/NodeOutputPanel.tsx`)- **ThinkingBlock Component**: Collapsible display for thinking content- **Default Expanded**: Thinking block is expanded by default when present@@ -4746,37 +4753,33 @@ whatsappReceive: {}```-#### Output Schema (`client/src/components/parameterPanel/InputSection.tsx`)-Provides draggable variables for downstream nodes:-```typescript-const sampleSchemas = {- whatsapp: {- message_id: 'string',- sender: 'string',- sender_phone: 'string', // Resolved phone number (Go RPC resolves LIDs before sending event)- chat_id: 'string',- message_type: 'string',- text: 'string',- timestamp: 'string',- is_group: 'boolean',- is_from_me: 'boolean',- push_name: 'string',- is_forwarded: 'boolean',- forwarding_score: 'number',- media: 'object',- group_info: {- group_jid: 'string',- sender_jid: 'string',- sender_phone: 'string', // Resolved phone number (Go RPC resolves LIDs)- sender_name: 'string'- },- newsletter_meta: {- edit_ts: 'number',- original_ts: 'number'- }- }-};-```+#### Output Schema (backend, `server/services/node_output_schemas.py`)+Runtime output shapes live on the backend and are fetched lazy by InputSection per the Wave 3 source-of-truth decision. The WhatsApp Receive schema:+```python+class WhatsAppGroupInfo(BaseModel):+ group_jid: Optional[str] = None+ sender_jid: Optional[str] = None+ sender_phone: Optional[str] = None # Resolved phone number (Go RPC resolves LIDs before sending event)+ sender_name: Optional[str] = None++class WhatsAppReceiveOutput(_OutputBase):+ message_id: Optional[str] = None+ sender: Optional[str] = None+ sender_phone: Optional[str] = None+ chat_id: Optional[str] = None+ message_type: Optional[str] = None+ text: Optional[str] = None+ timestamp: Optional[str] = None+ is_group: Optional[bool] = None+ is_from_me: Optional[bool] = None+ push_name: Optional[str] = None+ media: Optional[dict] = None+ group_info: Optional[WhatsAppGroupInfo] = None+ newsletter_meta: Optional[dict] = None++NODE_OUTPUT_SCHEMAS["whatsappReceive"] = WhatsAppReceiveOutput+```+Served via `GET /api/schemas/nodes/whatsappReceive.json` + `get_node_output_schema` WS handler. See [docs-internal/schema_source_of_truth_rfc.md](./docs-internal/schema_source_of_truth_rfc.md).### Task Trigger Nodediff --git a/docs-internal/frontend_architecture.md b/docs-internal/frontend_architecture.mdindex 6f2fc1fe..f59bbc44 100644--- a/docs-internal/frontend_architecture.md+++ b/docs-internal/frontend_architecture.md@@ -365,10 +365,12 @@ This is the rule that keeps the data layer schema-driven instead of imperatively| **`WebSocketContext`** | Raw WS connection, `sendRequest`, push-only broadcast slices (node status, workflow progress, android status). | `nodeStatuses`, `androidStatus`, `consoleLogs`, broadcast streams |**Hard rules:**-- A list of server records (`workflows`, `nodeParameters`, `userSettings`, `credentialCatalogue`) lives in TanStack Query. Never duplicate it in Zustand. Phase-1 follow-up commit `c3a7aa4` removed `savedWorkflows` from `useAppStore` for exactly this reason.-- Imperative WebSocket request/response inside a component (`useEffect` + `sendRequest` + `setState`) is a code smell — wrap it in a `useQuery` hook. Phase-2 commit `b2b6fba` did this for `useParameterPanel` and `useOnboarding`.-- After a mutation, **invalidate the corresponding query key**, don't manually patch a Zustand list. Mutations that need it from non-React code use the `queryClient` singleton at [client/src/lib/queryClient.ts](../client/src/lib/queryClient.ts).+- A list of server records (`workflows`, `nodeParameters`, `userSettings`, `credentialCatalogue`, `userSkills`, node output schemas) lives in TanStack Query. Never duplicate it in Zustand. Phase-1 follow-up commit `c3a7aa4` removed `savedWorkflows` from `useAppStore` for exactly this reason; Wave 3 commit `7706afb` did the same for `userSkills` in MasterSkillEditor.+- Imperative WebSocket request/response inside a component (`useEffect` + `sendRequest` + `setState`) is a code smell — wrap it in a `useQuery` hook. Inline the hook at the top of the consuming file when there's exactly one consumer (Wave 2/3 colocation rule); promote to `client/src/hooks/` when a second consumer appears. Phase-2 commit `b2b6fba` did this for `useParameterPanel` and `useOnboarding`; Wave 3 commits `2c5f227` / `7706afb` / `327f792` followed the same pattern inline inside MiddleSection / MasterSkillEditor / InputSection.+- After a mutation, **invalidate the corresponding query key**, don't manually patch a Zustand list or call a local refetch helper. Mutations that need it from non-React code use the `queryClient` singleton at [client/src/lib/queryClient.ts](../client/src/lib/queryClient.ts).- Schema metadata for parameter behavior (selectors, validators, dynamic options) belongs in the node-definition `typeOptions`, NOT in `parameter.name === '...'` checks inside `ParameterRenderer`. Phase-5 commit `8353c48` introduced `typeOptions.loadOptionsMethod` for the WhatsApp selectors as the canonical pattern.+- **Runtime output shapes for the Input panel's variable list live on the backend** via Pydantic models in `server/services/node_output_schemas.py`. The frontend fetches them lazy via `get_node_output_schema`; real execution data takes precedence. See the "Node output shape" section below and [schema_source_of_truth_rfc.md](./schema_source_of_truth_rfc.md).+- **Never hand-roll a modal backdrop.** Destructive confirmations use `<AlertDialog>`; composite panels use the `Modal.tsx` primitive on top of shadcn `<Dialog>`. A raw `position: fixed; background: rgba(0,0,0,0.5)` in new code should not pass review.## Schema-driven node + panel hints@@ -425,13 +427,14 @@ inspector/The DIY widget registry (RHF + zod + a tester+rank dispatch) is modeled on n8n's monolithic `ParameterInput.vue`. Library-survey research preferred this over @jsonforms / @rjsf — bundle delta ≤ +50 KB gz vs +60–110 KB for any framework option, and shadcn theming would have to be hand-authored against any of them. `@rjsf/core` v6 + `@rjsf/shadcn` is the documented escape hatch if collection recursion bites.-## Reusable component primitives (Wave 2)+## Reusable component primitives| File | When to use ||---|---|| [client/src/components/ui/action-button.tsx](../client/src/components/ui/action-button.tsx) | Colored "soft" toolbar button (Run / Save / Cancel / Reset / Stop). One `tone` prop drives bg/border/text against a fixed dracula palette via static Tailwind classes. Replaces the `actionButtonStyle(color, isDisabled)` style helper that was copy-pasted across 4 files. |+| [client/src/components/ui/alert-dialog.tsx](../client/src/components/ui/alert-dialog.tsx) | Confirmation / destructive-action modals. **Never hand-roll a `position: fixed; background: rgba(0,0,0,0.5)` backdrop** — use `<AlertDialog open onOpenChange>` with `AlertDialogHeader` / `AlertDialogDescription` / `AlertDialogFooter`. Focus trap, escape-to-close, and `role="alertdialog"` come from Radix. MiddleSection Clear Memory + Reset Skill dialogs are the canonical consumers (Wave 3 commit `61bf23c`). || [client/src/components/ui/sonner.tsx](../client/src/components/ui/sonner.tsx) | The `<Toaster />` mount — call `import { toast } from 'sonner'` directly at use sites; do not wrap. |-| [client/src/components/ui/Modal.tsx](../client/src/components/ui/Modal.tsx) | Composition primitive on top of shadcn `<Dialog>`. Owns the recurring "title bar with centered headerActions and a close button + size-constrained content panel" 8 panels share. Not an antd facade. |+| [client/src/components/ui/Modal.tsx](../client/src/components/ui/Modal.tsx) | Composition primitive on top of shadcn `<Dialog>`. Owns the recurring "title bar with centered headerActions and a close button + size-constrained content panel" 8 panels share. Not an antd facade. For destructive confirmations prefer `AlertDialog` above. || `client/src/components/ui/{button,input,select,switch,checkbox,form,…}.tsx` | shadcn-generated primitives. Add new ones via `npx shadcn@latest add <name>`. Don't re-implement what the registry ships. |## Theme + canvas chromediff --git a/docs-internal/new_service_integration.md b/docs-internal/new_service_integration.mdindex c7897c42..8d040215 100644--- a/docs-internal/new_service_integration.md+++ b/docs-internal/new_service_integration.md@@ -669,30 +669,25 @@ async def _execute_{operation1}(args: Dict[str, Any], node_params: Dict[str, Any----## Step 8: Output Schemas+## Step 8: Output Schemas (backend)-Add output schemas in `client/src/components/parameterPanel/InputSection.tsx`:+Output shapes live on the backend — the editor fetches them lazy (see [schema_source_of_truth_rfc.md](./schema_source_of_truth_rfc.md)). Add one Pydantic model per node type to [server/services/node_output_schemas.py](../server/services/node_output_schemas.py) and register it:-```typescript-const sampleSchemas: Record<string, Record<string, string>> = {- // ... existing schemas-- {service}: {- result_id: 'string',- field1: 'string',- field2: 'array',- timestamp: 'string',- },-};+```python+# server/services/node_output_schemas.py-// Add node type detection-const {service}Types = ['{operation1}Node', '{operation2}Node'];-const is{Service} = {service}Types.includes(nodeType);-if (is{Service}) {- schema = sampleSchemas.{service};-}+class YourServiceOutput(_OutputBase):+ result_id: Optional[str] = None+ field1: Optional[str] = None+ field2: Optional[list] = None+ timestamp: Optional[str] = None++# In NODE_OUTPUT_SCHEMAS:+NODE_OUTPUT_SCHEMAS["yourServiceOperationNode"] = YourServiceOutput```+InputSection consumes these automatically via `GET /api/schemas/nodes/{node_type}.json`. No frontend change needed. Shape shared across operations? Assign the same model to multiple keys in `NODE_OUTPUT_SCHEMAS` (see how `_SEARCH_TYPES` aliases `SearchOutput`).+---## Step 9: Credentials Modaldiff --git a/docs-internal/node_creation.md b/docs-internal/node_creation.mdindex 6935c9ea..947e7518 100644--- a/docs-internal/node_creation.md+++ b/docs-internal/node_creation.md@@ -640,32 +640,22 @@ outputs: [{}]```-### Sample Schemas for Common Nodes+### Declaring the runtime output shape (backend)-Add sample schemas in `InputSection.tsx` for better drag-and-drop UX:+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`:-```typescript-const sampleSchemas: Record<string, Record<string, string>> = {- aiAgent: {- response: 'string',- model: 'string',- provider: 'string',- iterations: 'number',- timestamp: 'string'- },- httpRequest: {- status: 'number',- data: 'object',- headers: 'object'- },- yourNewNode: {- field1: 'string',- field2: 'number',- // ... document your output fields- }-};+```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 Handlesdiff --git a/docs-internal/schema_source_of_truth_rfc.md b/docs-internal/schema_source_of_truth_rfc.mdindex 17ab2227..0d84ed07 100644--- a/docs-internal/schema_source_of_truth_rfc.md+++ b/docs-internal/schema_source_of_truth_rfc.md@@ -1,6 +1,15 @@# Schema source of truth — RFC-**Status:** accepted · **Owner:** frontend + backend platform · **Date:** 2026-04-14+**Status:** ✅ **implemented** · **Owner:** frontend + backend platform · **Date:** 2026-04-14 · **Landed across:** commits `cd252c1` → `4a4a439` (8 commits on `feature/credentials-scaling-v2`)++## Landed outcome++- Backend registry seeded with **98 Pydantic models** in [server/services/node_output_schemas.py](../server/services/node_output_schemas.py) covering every node type the deleted `sampleSchemas` map covered, plus all 18 specialized agents and 9 chat models.+- `GET /api/schemas/nodes/{node_type}.json` serves static JSON Schema (Cache-Control `public, max-age=86400`). 404 for unknown types.+- `get_node_output_schema` WebSocket handler for authenticated editor fetches.+- [InputSection.tsx](../client/src/components/parameterPanel/InputSection.tsx) consumes schemas lazy via `queryClient.fetchQuery(['nodeOutputSchema', nodeType])`, in-memory cache only. **1,673 → 972 LOC** (−701). sampleSchemas map, 20 `isXxxNode` detection constants, and 60-line pattern-match chain all gone.+- `outputSchema` field removed from `INodeTypeDescription` — the frontend type no longer has any shape-describing surface for runtime output.+- Adding a new node type's output shape: one Pydantic model in `node_output_schemas.py`. Zero frontend change.## Problemdiff --git a/docs-internal/ui_migration_plan.md b/docs-internal/ui_migration_plan.mdindex 7b4fbbae..9a3ca947 100644--- a/docs-internal/ui_migration_plan.md+++ b/docs-internal/ui_migration_plan.md@@ -86,17 +86,18 @@ Under that finding, the in-flight Wave 3 Phase 1 was reversed: the backend owns| 1a — Revert frontend outputSchema annotations | ✅ done | `cd252c1`, `5866821` | 30-file frontend annotation revert; `outputSchema` field removed from `INodeTypeDescription`; the 7 Wave-2-canary annotations (start/chatTrigger/taskTrigger/simpleMemory/python+js+ts executors) also removed — same principle || 1b — Backend schema registry + endpoint | ✅ done | `0d98c88`, `4a4a439` | `server/services/node_output_schemas.py` — **98 node-type entries** across agents / chat models / triggers / memory / code executors / Google Workspace / WhatsApp / search / location / filesystem / HTTP / Android / documents / proxy / email / telegram / twitter / social / browser / apify / crawlee / cronScheduler. Pydantic models colocated. `GET /api/schemas/nodes/{node_type}.json` (Cache-Control public, max-age=86400) + `get_node_output_schema` WS handler || 1c — Frontend three-tier dispatch + delete sampleSchemas | ✅ done | `327f792`, `4a4a439` | `InputSection.tsx` 1,673 → 972 LOC (−701). `sampleSchemas` map + 20-line `is{Android,Google,…}Node` detection constants + 60-line pattern-match else-if chain all gone. Schema precedence: real run data → backend fetch (cached in TanStack Query, in-memory only, matches n8n's `schemaPreview.store` pattern) → `{ data: 'any' }` empty |-| 2 — MiddleSection decompose | 🟡 partial | `2c5f227` | Two tractable wins landed: `sendRequest('get_user_settings')` → shared `useUserSettingsQuery`; `sendRequest('configure_compaction')` threshold-edit → TanStack `useMutation`. Full 6-sub-panel extraction deferred — 1,248 LOC with deeply-tangled useEffect chains needs in-browser verification |-| 3 — MasterSkillEditor decompose | ⏸ deferred | — | 1,133 LOC + 8 imperative `sendRequest + setState` sites across multiple useEffect chains + native capture-phase keydown escape. Safe decomposition requires UI smoke testing across folder-scan / user-skill CRUD / skill-content fetch |+| 2 — MiddleSection decompose | 🟡 partial | `2c5f227`, `61bf23c` | Three wins landed: (a) `sendRequest('get_user_settings')` → shared `useUserSettingsQuery`; (b) `sendRequest('configure_compaction')` threshold-edit → TanStack `useMutation`; (c) both hand-rolled confirmation modals (Clear Memory, Reset Skill) → shadcn `AlertDialog` primitives — 180 LOC of inline modal JSX + 40 LOC of trigger-button styles gone, accessibility (focus trap / escape / aria) from Radix. Net: 1,248 → 1,120 LOC. Full 6-sub-panel extraction still deferred for the deeply-tangled connected-skills / token-usage / console-output regions |+| 3 — MasterSkillEditor decompose | 🟡 partial | `7706afb` | One read-path migration landed: `get_user_skills` imperative fetch → inline `useQuery(['userSkills'])` + `invalidateUserSkills()` helper. The `useState(userSkills)` + `useCallback(fetchUserSkills)` + bootstrap `useEffect` + two `await fetchUserSkills()` call sites all collapse into one query hook with automatic invalidation on save / delete. Three remaining imperative sites (folder list, folder scan, skill content fetch) still pending || 4 — ConsolePanel Tailwind sweep | ⏸ deferred | — | 58 inline-style blocks, dynamic resize/layout behaviour. Wave 2 Phase 3 already fixed the state architecture (zod prefs + usePanelResize); visual cleanup is the remaining debt || 5 — Docs | ✅ done | this commit | This section + frontend_architecture.md updates |-**Wave 3 numbers:**-- Frontend LOC: `InputSection.tsx` −701; `MiddleSection.tsx` −5 + structural cleanup.-- Frontend `sendRequest + setState` anti-patterns: 2 retired (1 in MiddleSection memory-window-size seed, 1 in compaction threshold save).+**Wave 3 numbers (cumulative across all 10 commits):**+- Frontend LOC: `InputSection.tsx` −701; `MiddleSection.tsx` −133 (128 from AlertDialog + 5 from Query-hook swaps); `MasterSkillEditor.tsx` net +7 with one imperative fetch retired.+- Frontend `sendRequest + setState` anti-patterns retired: **5** — memory-window-size seed, compaction threshold save, `get_user_settings` pre-seed, plus the two modal stacks moved to declarative Radix primitives, plus `get_user_skills` in MasterSkillEditor.+- Hand-rolled dialog stacks replaced: 2 → shadcn `AlertDialog` (focus trap / escape / aria roles from Radix).- Backend: +2 files (`node_output_schemas.py`, `routers/schemas.py`), +1 WS handler, +1 router registration. **98 Pydantic models** seeded.-- `pnpm exec tsc --noEmit` green throughout all 8 commits.-- New frontend files: 0.+- `pnpm exec tsc --noEmit` green throughout all 10 commits.+- New frontend files: **0**.**Architectural delta (permanent):**- Node output shapes now live on the backend **exclusively**. New node types get a Pydantic model in `server/services/node_output_schemas.py` — no frontend change needed.