Skip to content

Self-improving AI Employees for everyone

docs: Wave 11.E.1-E.4 — plan, plugin_system, CLAUDE.md, nodes/README

trohitg03e14bfe1a17
diff --git a/CLAUDE.md b/CLAUDE.md
index 515b6579..8a091aa0 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -12,7 +12,7 @@ This is a React Flow-based workflow automation platform implementing n8n-inspire
| **[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–10 done. Full frontend is schema-driven (backend SSOT); remaining DIY widget registry (ex-Phase 6) is the one deferred item. |
| **[Schema Source of Truth RFC](./docs-internal/schema_source_of_truth_rfc.md)** | Backend is SSOT for node schemas, visual metadata, handlers, palette metadata, icons. Plugin pattern: one `BaseNode` subclass in `server/nodes/<group>/<name>.py`. Wire format: `asset:<key>` / `<lib>:<brand>` / URL / emoji. Endpoint: `/api/schemas/nodes/{type}/spec.json`. 124 pytest invariants lock the contract. |
-| **[Plugin System (Wave 11)](./docs-internal/plugin_system.md)** | Class-based plugin-first architecture. `BaseNode` / `ActionNode` / `TriggerNode` / `ToolNode` + `@Operation` decorator. Pydantic `Params`/`Output`. Declarative `Routing` DSL + `Connection` facade (Nango pattern). 18 `Credential` subclasses live in each node folder's `_credentials.py` (or inline for single-use). `TaskQueue` constants route to Temporal worker pools. 111 plugins live across 9 queues; handler bodies fully inlined (handlers/ shrank 12.8K → 4.9K LOC). |
+| **[Plugin System (Wave 11)](./docs-internal/plugin_system.md)** | Class-based plugin-first architecture. `BaseNode` / `ActionNode` / `TriggerNode` / `ToolNode` + `@Operation` decorator. Pydantic `Params`/`Output`. Declarative `Routing` DSL + `Connection` facade (Nango pattern). 18 `Credential` subclasses live in each node folder's `_credentials.py` (or inline for single-use). `TaskQueue` constants route to Temporal worker pools. 111 plugins live across 9 queues; handler bodies fully inlined (`services/handlers/` shrank 12.8K → 1.1K LOC across 16 → 4 files; only cross-cutting orchestration remains: `tools.py` AI-tool dispatch + agent delegation, `google_auth.py`, `triggers.py`). |
| **[Nodes Cookbook](./server/nodes/README.md)** | 5-minute recipe + folder map + shared helpers (`_base.py` / `_inline.py` per domain) + shared credentials + contract invariants + common pitfalls. Lives next to the plugin files. |
| **[Node Creation Guide](./docs-internal/node_creation.md)** | Canonical plugin recipe — one Python file, zero frontend edits. Subclass `ActionNode`/`TriggerNode`/`ToolNode`, declare metadata + `Params` + `Output`, decorate op methods with `@Operation`. Auto-registers via `BaseNode.__init_subclass__`. |
| **[AI Tool Node Guide](./docs-internal/ai_tool_node_creation.md)** | Detailed guide for creating dedicated AI Agent tool nodes (schemas, handlers, toolkits) |
diff --git a/docs-internal/plugin_system.md b/docs-internal/plugin_system.md
index f1f675d9..b55bac2f 100644
--- a/docs-internal/plugin_system.md
+++ b/docs-internal/plugin_system.md
@@ -432,14 +432,46 @@ every CI run. Examples:
- Wave 11.D.12 — Fast-path contract invariants.
- Wave 11.D.13 — Sunset empty bulk files + dead dispatch.
- Wave 11.F — Per-plugin Temporal activities + worker pools.
-- Wave 11.E — Declarative credentials: 18 `Credential` subclasses under
- `server/credentials/` (GoogleCredential + GoogleMapsCredential +
- TwitterCredential + TelegramCredential + ApifyCredential + 10 LLM
- providers + 3 inline search credentials). 29 plugins now declare
- `credentials = (...)`. Agents stay poly-provider (empty tuple).
+- Wave 11.E — Declarative credentials: 18 `Credential` subclasses
+ (GoogleCredential + GoogleMapsCredential + TwitterCredential +
+ TelegramCredential + ApifyCredential + 10 LLM providers + 3 inline
+ search credentials). 29 plugins now declare `credentials = (...)`.
+ Agents stay poly-provider (empty tuple).
+- Wave 11.E.1 — Modularised credentials into per-domain
+ `nodes/<group>/_credentials.py` files. `server/credentials/`
+ directory deleted; auto-discovery rides on node-package import.
+- Wave 11.E.2 — Dead-code sweep: fixed 2 broken agent imports,
+ stripped 13 dead dispatch branches in `tools.py`, deleted duplicate
+ `handlers/proxy.py`, moved misnamed `routers/whatsapp.py` →
+ `services/whatsapp_service.py`, dedup'd `TRIGGER_NODE_TYPES`.
+- Wave 11.E.3 — Inlined the last per-domain handler bodies into
+ plugins. Deleted 8 fully-orphan handler files (search, code,
+ telegram, http, filesystem, email, process, todo) and 5
+ still-referenced ones (browser, android, claude_code, rlm,
+ 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).
+- 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) →
+ `nodes/android/_base.{execute_android_toolkit,
+ execute_android_service_tool}`. `tools.py` from 1,255 → 821 LOC.
- Wave 11.G — (this file) Docs + packaging.
-Every handler body now lives on its plugin. `services/handlers/` keeps
-only small shared helpers (`google_auth.py`, `triggers.py`) and the
-`tools.py` AI-tool dispatcher — everything else is gone (~8K LOC moved
-or deleted across 11.D.4–10).
+`services/handlers/` is now **4 files / 1,112 LOC** (down from 16
+files / 12,800 LOC):
+
+| File | LOC | Purpose |
+|---|---|---|
+| `tools.py` | 821 | AI-tool dispatcher, plugin fast-path, agent delegation infrastructure (shared `_delegated_tasks` / `_delegation_results` state). |
+| `google_auth.py` | 142 | Shared OAuth helper for the 7 Google plugins. |
+| `triggers.py` | 126 | Generic event-trigger handler for `twitterReceive` and other polling triggers. |
+| `__init__.py` | 23 | Package docstring; nothing imports from `services.handlers` at package level. |
+
+Every domain owns its own code under `nodes/<group>/` — plugin file +
+optional `_base.py` / `_inline.py` / `_credentials.py` siblings. No
+handler shells, no central credential registry, no cross-domain reach.
diff --git a/server/nodes/README.md b/server/nodes/README.md
index 09cc6ed1..69c92888 100644
--- a/server/nodes/README.md
+++ b/server/nodes/README.md
@@ -131,14 +131,16 @@ these first before writing new code:
|---|---|---|
| `agent/` | `_inline.prepare_agent_call` | One-shot pre-dispatch for every agent (memory + skill + tool + teammate collection) |
| `agent/` | `_specialized.SpecializedAgentBase` | Base for 13 specialized agents |
-| `model/` | `_base.ChatModelBase` | 9 chat models inherit → same `@Operation("chat")` body |
-| `android/` | `_base.AndroidServiceBase` | 16 Android services inherit |
+| `model/` | `_base.ChatModelBase` | 9 chat models inherit → same `@Operation("chat")` body that calls `ai_service.execute_chat` |
+| `android/` | `_base.AndroidServiceBase` | 16 Android services inherit; payload translation + `SERVICE_ID_MAP` lives on this base |
+| `android/` | `_base.execute_android_toolkit` / `execute_android_service_tool` | AI-tool dispatchers — called from `services/handlers/tools.py` for the toolkit aggregator + direct service tool branches |
| `code/` | `_base.CodeExecutorBase` + `_nodejs.NodeJSClient` | Python/JS/TS executors |
| `google/` | `_base.build_google_service` / `track_google_usage` | 7 Google plugins (OAuth + API) |
| `google/` | `_gmail.fetch_email_details` / `mark_email_as_read` | gmail + gmail_receive |
| `twitter/` | `_base.call_with_retry` / `format_tweet` / `sync_search_recent` | 4 twitter plugins (XDK + refresh) |
-| `whatsapp/` | `_base.*` | whatsappSend / whatsappDb |
+| `whatsapp/` | `_base.*` | whatsappSend / whatsappDb (RPC dispatch via `services/whatsapp_service.py`) |
| `social/` | `_base.*` | socialReceive / socialSend |
+| `proxy/` | `proxy_config.execute_proxy_config` | 10-operation matrix; called by both `ProxyConfigNode.dispatch` and `tools.py`'s AI-tool branch |
Cross-domain infrastructure lives in `services/plugin/` (e.g.
`edge_walker.py` for agent connection discovery, `routing.py` for
@@ -235,11 +237,28 @@ Added in Wave 11 (Mar 2026):
- **11.A**: `BaseNode` / `ActionNode` / `TriggerNode` / `ToolNode`
+ `@Operation` + `Routing` + `Connection` + `Credential`.
- **11.B/C**: 111 plugins migrated, folder layout adopted.
-- **11.D**: Handler bodies inlined into plugins (handlers/ shrank
- ~12.8K → ~4.9K LOC).
+- **11.D**: Per-domain handler bodies inlined.
- **11.E**: 18 declarative credentials, 29 plugins wired.
+- **11.E.1**: Credentials moved into per-domain `_credentials.py`
+ (no central `server/credentials/` dir).
+- **11.E.2**: Dead-code sweep — 2 broken imports fixed, 13 dead
+ dispatch branches stripped, duplicate proxy handler removed,
+ `routers/whatsapp.py` (misnamed) → `services/whatsapp_service.py`.
+- **11.E.3**: 14 handler files deleted, last per-domain bodies
+ inlined into plugins; `handle_ai_agent` / `handle_chat_agent`
+ retired in favour of `BaseNode.execute()` via the node registry.
+- **11.E.4**: Last `tools.py` movables relocated to their domains
+ (proxyConfig matrix → `nodes/proxy/proxy_config`, Android tool
+ dispatch → `nodes/android/_base`).
- **11.F**: Per-plugin Temporal activities, 9 worker pools with tuned
concurrency.
- **11.G** (this doc): Cookbook.
-Plan + migration history: [plugin_system.md](../../docs-internal/plugin_system.md).
+End state: `services/handlers/` is **4 files / 1.1K LOC** (down from
+16 / 12.8K). Only cross-cutting orchestration remains there:
+`tools.py` (AI-tool dispatch + agent delegation), `triggers.py`
+(generic event-trigger handler), `google_auth.py` (shared OAuth
+helper), and a 23-line package docstring.
+
+Plan + full migration history:
+[plugin_system.md](../../docs-internal/plugin_system.md).