Skip to content

Self-improving AI Employees for everyone

docs: Wave 11.G.1 — plugin system canonical reference + RFC addendum

trohitg1f119c1b355f
diff --git a/CLAUDE.md b/CLAUDE.md
index dc2c55d3..dbae8628 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -11,8 +11,9 @@ 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, and icons. Plugin pattern via `@register_node`: one file in `server/nodes/<name>.py` = new node. Wire format: `asset:<key>` (filesystem SVG) / `<lib>:<brand>` (NPM icon package) / URL / emoji. Endpoints: `/api/schemas/nodes/{type}/spec.json`, `/nodes/options/{method}`, `/nodes/groups`. 108 pytest invariants lock the contract. |
-| **[Node Creation Guide](./docs-internal/node_creation.md)** | Canonical Wave 10 plugin recipe — one Python file, zero frontend edits. Covers Pydantic params, handler, visual metadata (icon / color / handles / componentKind), uiHints catalogue, dynamic option loaders, output schemas. |
+| **[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). `Credential` subclasses. `TaskQueue` constants route to Temporal worker pools. 111 plugins live across 9 queues. |
+| **[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) |
| **[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 |
| **[Dual-Purpose Tool Guide](./docs-internal/dual_purpose_tool_node_creation.md)** | Guide for nodes that work as both workflow nodes AND AI Agent tools (e.g., whatsappSend) |
diff --git a/docs-internal/node_creation.md b/docs-internal/node_creation.md
index 12529f1b..dcef04a7 100644
--- a/docs-internal/node_creation.md
+++ b/docs-internal/node_creation.md
@@ -1,22 +1,25 @@
# Node Creation Guide
-This guide explains how to create new nodes for MachinaOs, covering frontend definitions, backend handlers, and the complete integration flow.
+> **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.
-> **Related Documentation:**
-> - [Workflow Schema](./workflow-schema.md) - JSON schema, edge handle conventions, config node architecture
-> - [Schema Source of Truth RFC](./schema_source_of_truth_rfc.md) - Wave 3 + Wave 6 backend-as-SSOT design
-> - [CLAUDE.md](../CLAUDE.md) - Project overview, key files, architecture patterns
+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.
+
+> **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.
---
-## Wave 10 — plugin recipe (canonical)
+## Wave 10 — `@register_node` dict form (historical)
-Since Wave 10 the canonical path is **one Python file per node** via the
-`@register_node` plugin pattern. 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.
+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),
diff --git a/docs-internal/plugin_system.md b/docs-internal/plugin_system.md
new file mode 100644
index 00000000..e980b4ef
--- /dev/null
+++ b/docs-internal/plugin_system.md
@@ -0,0 +1,397 @@
+# Plugin System (Wave 11)
+
+The MachinaOs plugin system is a class-based, declarative node
+authoring model inspired by n8n's `INodeType`, Nango's
+`providers.yaml`, Pipedream's app/component split, and Temporal's
+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.
+
+## Quick start — adding a new node
+
+```python
+# server/nodes/search/example_search.py
+from pydantic import BaseModel, Field
+from services.plugin import (
+ ActionNode, ApiKeyCredential, NodeContext, Operation, TaskQueue,
+)
+
+
+class ExampleCredential(ApiKeyCredential):
+ id = "example_api"
+ display_name = "Example Search"
+ category = "Search"
+ key_name = "X-API-Key"
+ key_location = "header"
+
+
+class ExampleParams(BaseModel):
+ query: str = Field(..., min_length=1)
+ max_results: int = Field(default=10, ge=1, le=50)
+
+
+class ExampleOutput(BaseModel):
+ results: list
+ count: int
+
+
+class ExampleSearchNode(ActionNode):
+ type = "exampleSearch"
+ display_name = "Example Search"
+ icon = "asset:example"
+ color = "#abcdef"
+ group = ("search", "tool")
+ description = "Example search via external API"
+ component_kind = "square"
+ handles = (
+ {"name": "input-main", "kind": "input", "position": "left",
+ "label": "Input", "role": "main"},
+ {"name": "output-main", "kind": "output", "position": "right",
+ "label": "Output", "role": "main"},
+ )
+ credentials = (ExampleCredential,)
+ task_queue = TaskQueue.REST_API
+ usable_as_tool = True
+ Params = ExampleParams
+ Output = ExampleOutput
+
+ @Operation("search")
+ async def search(self, ctx: NodeContext, params: ExampleParams) -> ExampleOutput:
+ async with ctx.connection("example_api") as conn:
+ resp = await conn.get(
+ "https://api.example.com/search",
+ params={"q": params.query, "limit": params.max_results},
+ )
+ resp.raise_for_status()
+ data = resp.json()
+ return ExampleOutput(results=data.get("hits", []), count=len(data.get("hits", [])))
+```
+
+**That's it.** On server restart:
+
+- `BaseNode.__init_subclass__` eagerly registers the class into four
+ registries: `NODE_METADATA`, `NODE_INPUT_MODELS`,
+ `NODE_OUTPUT_SCHEMAS`, `_HANDLER_REGISTRY`.
+- `_NODE_CLASS_REGISTRY` indexes the class itself so Temporal workers
+ and tool dispatch can look it up by type.
+- NodeSpec emits automatically via
+ `GET /api/schemas/nodes/exampleSearch/spec.json`.
+- `_PLUGIN_HANDLERS` merge in `NodeExecutor` makes it runnable.
+- The node appears in the Component Palette under its group
+ (search + tool) at the next browser reload.
+
+## Architecture
+
+### Class hierarchy
+
+```
+BaseNode (services/plugin/base.py)
+├── ActionNode fire-once, {success, result} envelope
+├── TriggerNode long-lived, event (event_waiter) or polling modes
+└── ToolNode AI-invoked, flat return (no success wrapper)
+```
+
+Every subclass auto-registers on import. Pure-visual or abstract
+intermediaries pass `abstract=True` in the class definition:
+
+```python
+class SpecializedAgentBase(ActionNode, abstract=True):
+ ...
+```
+
+### Class attributes
+
+| Attribute | Purpose |
+|---|---|
+| `type` | Node type string. Matches workflow JSON + registry key. |
+| `version` | Int, bumped on breaking changes. Activity name includes it. |
+| `display_name` / `subtitle` / `description` | Palette + panel header. |
+| `icon` | `asset:<key>` / `<lib>:<brand>` / URL / emoji. |
+| `color` | Hex or Dracula token. |
+| `group` | Tuple of palette groupings (first is primary). |
+| `component_kind` | Frontend dispatch: `square` / `trigger` / `agent` / `tool` / `model` / `start` / `generic`. |
+| `handles` | React Flow handle topology (`input-main`, `output-main`, …). |
+| `ui_hints` | Dict of panel flags (`hasCodeEditor`, `isMemoryPanel`, …). |
+| `annotations` | Pipedream-style: `destructive` / `readonly` / `open_world`. |
+| `credentials` | Tuple of `Credential` subclasses the node uses. |
+| `Params` | Pydantic `BaseModel` — user-facing parameters. Used for both UI rendering and AI tool schemas. |
+| `Output` | Pydantic `BaseModel` — runtime output shape. |
+| `usable_as_tool` | `ActionNode` flag — mints a ToolNode adapter for AI invocation. |
+| `task_queue` | Temporal worker pool. See `TaskQueue` constants. |
+| `retry_policy` | `RetryPolicy` dataclass (mirrors `temporalio.common.RetryPolicy`). |
+| `start_to_close_timeout` / `heartbeat_timeout` | Per-node Temporal knobs. |
+
+### Operations (`@Operation`)
+
+A multi-op node declares multiple methods, each decorated with
+`@Operation("name")`. `BaseNode._pick_operation` reads
+`parameters.operation` to choose which to run.
+
+```python
+@Operation("send", cost={"service": "gmail", "action": "send", "count": 1})
+async def send(self, ctx: NodeContext, params: GmailParams) -> Any: ...
+
+@Operation("search")
+async def search(self, ctx: NodeContext, params: GmailParams) -> Any: ...
+
+@Operation("read")
+async def read(self, ctx: NodeContext, params: GmailParams) -> Any: ...
+```
+
+Single-op nodes use one method; `parameters.operation` can be omitted.
+
+### Declarative REST via `Routing`
+
+For pure REST integrations, leave the op body empty and attach a
+`Routing` object:
+
+```python
+@Operation("search", routing=Routing(
+ request=RoutingRequest(
+ method="GET",
+ url="https://api.example.com/search",
+ qs={"q": "={{params.query}}"},
+ headers={"X-API-Key": "={{credentials.api_key}}"},
+ ),
+ output=RoutingOutput(
+ post_receive=[PostReceiveAction(type="root_property", property="data.hits")],
+ ),
+))
+async def search(self, ctx, params): pass # body unused — routing handles it
+```
+
+Supported `post_receive` strategies: `root_property`, `limit`,
+`filter`, `set`.
+
+### Connection facade (Nango pattern)
+
+Plugins never see tokens. `ctx.connection(credential_id)` returns an
+authed `httpx`-compatible client:
+
+```python
+async with ctx.connection("brave_search") as conn:
+ resp = await conn.get(url, params={"q": query})
+ # X-Subscription-Token header auto-injected by Credential.inject()
+```
+
+401/403 responses trigger one refresh-and-retry transparently.
+
+### Credentials
+
+Declarative types under `server/credentials/` (or inlined next to
+their plugin for single-use). Three base classes:
+
+- `ApiKeyCredential` — header / query / bearer injection.
+- `OAuth2Credential` — `Authorization: Bearer <access_token>` with
+ auto-refresh via `auth_service.get_oauth_tokens`.
+- `Credential` — fully custom (override `resolve()` + `inject()`).
+
+Auto-discovery: `server/credentials/__init__.py` walks the package at
+import. `CREDENTIAL_REGISTRY` indexes by `cls.id`. Contract invariant
+ensures every declared credential on a plugin resolves to a
+registered class.
+
+### Shared agent helpers
+
+Every agent plugin (ai_agent, chat_agent, 13 specialized agents, team
+leads) calls one helper:
+
+```python
+from ._inline import prepare_agent_call
+
+kwargs = await prepare_agent_call(
+ node_id=ctx.node_id, node_type=self.type,
+ parameters=params.model_dump(by_alias=True),
+ context=ctx.raw, database=database,
+ log_prefix=f"[{self.type}]",
+)
+response = await ai_service.execute_chat_agent(ctx.node_id, **kwargs)
+```
+
+`prepare_agent_call` wraps the shared edge-walker
+(`services/plugin/edge_walker.py`) + task context injection +
+auto-prompt fallback + team-lead teammate injection. Plugin-specific
+logic stays in the `execute_op` method.
+
+### Temporal per-node activities (Wave 11.F)
+
+Every `BaseNode` subclass exposes `cls.as_activity()`, a Temporal
+`@activity.defn`-decorated callable with name
+`node.{type}.v{version}`. Collect them for worker registration:
+
+```python
+from services.temporal.plugin_activities import (
+ collect_plugin_activities,
+ distinct_task_queues,
+)
+
+# Single-queue workers:
+activities = collect_plugin_activities(task_queue="ai-heavy")
+worker = Worker(client, task_queue="ai-heavy", activities=activities, ...)
+
+# Multi-queue pool (one worker per queue):
+from services.temporal.worker import TemporalWorkerPool
+pool = TemporalWorkerPool(client) # defaults to all declared queues
+await pool.start()
+```
+
+Queue distribution (current state):
+
+| Queue | Plugins | Default concurrency |
+|---|---|---|
+| `ai-heavy` | 28 | 4 |
+| `rest-api` | 21 | 50 |
+| `machina-default` | 25 | 20 |
+| `android` | 16 | 10 |
+| `messaging` | 7 | 20 |
+| `triggers-event` | 5 | 100 |
+| `triggers-poll` | 4 | 100 |
+| `code-exec` | 3 | 10 |
+| `browser` | 2 | 4 |
+
+Env overrides: `TEMPORAL_<QUEUE>_CONCURRENCY` (e.g.
+`TEMPORAL_AI_HEAVY_CONCURRENCY=8`).
+
+### Trigger registry auto-populate (Wave 11.D.11)
+
+`services/event_waiter.py:TRIGGER_REGISTRY` + `FILTER_BUILDERS` are
+backfilled from plugin `TriggerNode` subclasses on first access. A
+plugin declaring `event_type` + `build_filter` auto-registers — no
+hand-edit of `event_waiter.py` required.
+
+Hardcoded entries still win when present (authoritative), so plugin
+upgrades never silently replace hand-tuned filter behaviour.
+
+## Folder layout
+
+```
+server/
+├── nodes/ # One file per node
+│ ├── __init__.py # pkgutil.walk_packages discovery
+│ ├── groups.py # Palette group metadata
+│ ├── agent/ # AI agents (aiAgent, chatAgent, 13 specialized)
+│ │ ├── _handles.py # Shared handle topology helpers
+│ │ ├── _inline.py # prepare_agent_call()
+│ │ ├── _specialized.py # SpecializedAgentBase
+│ │ └── <agent>.py
+│ ├── model/ # AI chat models (9 providers)
+│ │ ├── _base.py # ChatModelBase + ChatModelParams/Output
+│ │ └── <provider>_chat_model.py
+│ ├── android/ # 16 Android service nodes
+│ │ ├── _base.py # AndroidServiceBase
+│ │ └── <service>.py
+│ ├── code/ # python/js/ts executors
+│ │ ├── _base.py # CodeExecutorBase
+│ │ ├── _nodejs.py # Shared NodeJSClient singleton
+│ │ └── <lang>_executor.py
+│ ├── filesystem/ # file_read / file_modify / shell / fs_search
+│ │ ├── _backend.py # Shared LocalShellBackend helper
+│ │ └── <op>.py
+│ ├── document/ # http_scraper / parser / chunker / embedding / vector
+│ │ ├── _helpers.py # delegate() wrapper
+│ │ └── <stage>.py
+│ ├── google/ # gmail / calendar / drive / sheets / tasks / contacts
+│ ├── proxy/ # proxy_request / proxy_config / proxy_status
+│ │ └── _usage.py # Shared track_proxy_usage
+│ ├── search/ # brave / serper / perplexity / duckduckgo
+│ ├── scraper/ # apify / crawlee
+│ ├── tool/ # calculator / currentTime / taskManager / writeTodos
+│ ├── trigger/ # webhookTrigger / chatTrigger / taskTrigger
+│ ├── workflow/ # start
+│ ├── scheduler/ # cronScheduler / timer
+│ ├── whatsapp/ # whatsappSend / whatsappDb / whatsappReceive
+│ ├── telegram/ # telegramSend / telegramReceive
+│ ├── twitter/ # twitterSend / search / user / receive
+│ ├── email/ # emailSend / emailRead / emailReceive
+│ ├── chat/ # chatSend / chatHistory
+│ ├── social/ # socialSend / socialReceive
+│ ├── browser/ # browser (agent-browser CLI)
+│ ├── utility/ # httpRequest / webhookResponse / console / team_monitor / process_manager
+│ ├── text/ # textGenerator / fileHandler
+│ ├── location/ # gmaps_create / gmaps_locations / gmaps_nearby_places
+│ └── skill/ # simpleMemory / masterSkill
+├── credentials/ # Declarative Credential subclasses
+│ └── __init__.py # Auto-discovery walker
+└── services/
+ ├── plugin/ # Plugin runtime
+ │ ├── base.py # BaseNode
+ │ ├── action.py / trigger.py / tool.py
+ │ ├── operation.py # @Operation decorator + collector
+ │ ├── routing.py # Declarative REST DSL
+ │ ├── credential.py # Credential base classes
+ │ ├── connection.py # Nango-style authed httpx wrapper
+ │ ├── context.py # NodeContext dataclass
+ │ ├── scaling.py # TaskQueue / RetryPolicy
+ │ ├── edge_walker.py # collect_agent_connections / collect_teammate_connections
+ │ └── interceptor.py # Interceptor ABC + chain
+ ├── node_registry.py # register_node + _NODE_CLASS_REGISTRY + helpers
+ ├── node_spec.py # NodeSpec envelope emission
+ └── temporal/
+ ├── plugin_activities.py # collect_plugin_activities / distinct_task_queues
+ └── worker.py # TemporalWorkerManager + TemporalWorkerPool
+```
+
+## Contract invariants
+
+`server/tests/test_plugin_contract.py` — 16 invariants enforced on
+every CI run. Examples:
+
+- Non-empty `type` / `display_name` / `group` per class.
+- `Params` + `Output` must be Pydantic `BaseModel` subclasses.
+- Every declared `credentials` entry resolves to a registered class.
+- Operation names unique per class.
+- `routing=...` requires `credentials` declared.
+- `task_queue` ∈ `TaskQueue.ALL`.
+- Every `ToolNode` JSON schema has no `$defs` / `$ref` (LLM-compat).
+- Every event-mode `TriggerNode` declares `event_type`.
+- Fast-path covers every AI-tool-usable plugin (no hardcoded schema
+ dependency).
+- Trigger registry auto-populates for every event-mode plugin.
+
+108 Wave 10 invariants in `test_node_spec.py` still run — 124 total.
+
+## Canonical principles
+
+1. **One file = one node.** Adding a new node never edits multiple
+ files. The filesystem location matches the palette group.
+2. **Backend is SSOT.** Node declaration, visual metadata, handlers,
+ schemas, credentials, icons — one authoring location.
+3. **No frontend fallbacks.** Missing data surfaces as a visible gap
+ so the backend bug is obvious, not masked.
+4. **Stateful services stay in `services/`.** AIService, MapsService,
+ NodeJSClient, etc. Plugins call them; never inline them.
+5. **Per-handler helpers move WITH the handler.**
+ `_format_console_output`, `_extract_text`, … inline into the
+ plugin file. Cross-handler helpers (like `edge_walker`) extract
+ to shared modules.
+6. **Container injection.** Plugins do
+ `from core.container import container; svc = container.X()` —
+ never instantiate services directly.
+7. **Pydantic for everything.** Params, Output, Credential config,
+ Routing — all Pydantic. Validation at the boundary, typed at the
+ core.
+
+## Migration history (for future readers)
+
+- Wave 6 — Output schemas on backend.
+- Wave 10 — Input schemas + metadata on backend; `@register_node`
+ decorator (dict form); filesystem-as-catalog.
+- Wave 11.A — `services/plugin/` package with `BaseNode` hierarchy.
+- Wave 11.B — Reference migrations (5 nodes across all kinds).
+- Wave 11.B.1 — Unified tool dispatch via plugin fast-path.
+- Wave 11.C — 111/111 nodes migrated across 5 batches; folder layout
+ mirrors palette groups.
+- Wave 11.D.0 — `edge_walker` extracted to services/plugin/.
+- Wave 11.D.1-6 — Handler bodies inlined into plugins (trivial
+ wrappers, code executors, HTTP/proxy, polling triggers, agents).
+- Wave 11.D.11 — Auto-populate trigger registries.
+- 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 — (next) Declarative credentials consolidation.
+- Wave 11.G — (this file) Docs + packaging.
+
+Deferred handler inlines (11.D.4, 11.D.7–10) are non-blocking polish;
+current delegation is clean.
diff --git a/docs-internal/schema_source_of_truth_rfc.md b/docs-internal/schema_source_of_truth_rfc.md
index f8ffe309..21ccd61c 100644
--- a/docs-internal/schema_source_of_truth_rfc.md
+++ b/docs-internal/schema_source_of_truth_rfc.md
@@ -275,6 +275,68 @@ declaring `{label, icon, color, visibility}`. Retires the frontend's
`client/src/assets/icons/`
- every palette group carries non-empty label + icon
+## Wave 11 — plugin-first class hierarchy
+
+Wave 10 shipped the `@register_node` decorator and per-file plugin
+layout but kept handlers as standalone async functions. Wave 11
+promotes nodes to a class-based plugin model, extracts runtime
+infrastructure into `services/plugin/`, and unifies the node-creation
+API around a single `BaseNode` hierarchy. See
+**[plugin_system.md](./plugin_system.md)** for the canonical reference.
+
+### What changed
+
+- **`BaseNode` class hierarchy.** Three concrete kinds —
+ `ActionNode` / `TriggerNode` / `ToolNode`. Each subclass declares
+ everything on its class object: `type`, metadata, `Params` +
+ `Output` Pydantic models, `credentials`, `handles`, `task_queue`,
+ `retry_policy`, operations. `__init_subclass__` writes to the four
+ legacy registries on import, so existing consumers are unchanged.
+- **`@Operation` decorator** for multi-op dispatch.
+- **Declarative `Routing` DSL** + **`Connection` facade (Nango
+ pattern).** Plugins never see tokens; routing owns templating + HTTP.
+- **Credential classes** (`ApiKeyCredential`, `OAuth2Credential`)
+ with declarative `inject()` methods. Auto-registry via
+ `__init_subclass__`.
+- **Per-plugin Temporal activities** (Wave 11.F). Every subclass
+ exposes `cls.as_activity()` with name `node.{type}.v{version}`.
+ `TemporalWorkerPool` spawns one worker per declared `task_queue`
+ with tuned concurrency (ai-heavy=4, rest-api=50, triggers-poll=100).
+- **Folder layout mirrors palette groups.** `server/nodes/<group>/<name>.py`.
+- **Auto-populate trigger registries** (Wave 11.D.11). Plugins
+ declaring `event_type` + `build_filter` auto-register into
+ `event_waiter.TRIGGER_REGISTRY` + `FILTER_BUILDERS`.
+- **Shared helpers under `services/plugin/`**: `edge_walker.py`
+ (agent connection discovery), `base.py` (BaseNode lifecycle),
+ `context.py` (typed NodeContext), `scaling.py` (TaskQueue +
+ RetryPolicy), `operation.py` (@Operation decorator + collector),
+ `routing.py` (declarative REST DSL), `connection.py` (authed
+ httpx wrapper), `credential.py`, `interceptor.py`.
+
+### Contract invariants
+
+Adds 16 invariants to the 108 Wave 10 suite → **124 total**:
+
+- Every `BaseNode` subclass has `type`, `display_name`, `group`.
+- `Params` + `Output` are Pydantic `BaseModel` subclasses.
+- Every declared credential resolves to `CREDENTIAL_REGISTRY`.
+- `@Operation` names unique per class; `routing=…` requires credentials.
+- `task_queue` ∈ `TaskQueue.ALL`; `retry_policy` is `RetryPolicy`.
+- Every `ToolNode` JSON schema has no `$defs` / `$ref`.
+- Every event-mode `TriggerNode` declares `event_type`.
+- Fast-path covers every AI-tool-usable plugin.
+- Trigger registry auto-populates for every event-mode plugin.
+
+### 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).
+
## References
- [n8n `schemaPreview.api.ts`](https://github.com/n8n-io/n8n/blob/master/packages/frontend/editor-ui/src/features/ndv/runData/schemaPreview.api.ts)