Skip to content

Self-improving AI Employees for everyone

docs: add plugin authoring RFC (folder-default + Temporal + CloudEvents)

trohitgfad940af49c0
diff --git a/docs-internal/plugin_authoring_rfc.md b/docs-internal/plugin_authoring_rfc.md
new file mode 100644
index 00000000..4b0cf169
--- /dev/null
+++ b/docs-internal/plugin_authoring_rfc.md
@@ -0,0 +1,375 @@
+# RFC: Plugin Authoring Standard — Folder-Default + Temporal Activities + CloudEvents Broadcasts
+
+| Field | Value |
+|---|---|
+| Status | Draft — awaiting approval |
+| Scope | `server/nodes/**`, `server/services/plugin/**`, `server/services/events/**`, `server/services/temporal/**`, `docs-internal/*plugin*.md`, `docs-internal/node_creation.md`, `CLAUDE.md`, `server/nodes/README.md` |
+| Authors | Plan generated by Claude Code |
+| Date | 2026-05-13 |
+
+---
+
+## 1. Summary
+
+Codify the canonical plugin authoring shape for MachinaOs: every plugin is a self-contained folder under `server/nodes/<group>/<plugin>/`, its code and media co-located, inheriting shared base classes; the backend auto-registers a per-plugin Temporal activity; every server→FE event flows through a CloudEvents v1.0 `WorkflowEvent` envelope. Update the docs to match the code, fix three real CloudEvents spec violations, and migrate the 117 legacy single-file plugins.
+
+## 2. Motivation
+
+Three problems compound today:
+
+- **Docs claim ~95% match the code; the 5% gap traps new contributors.** Examples: `NODE_INPUT_MODELS` doesn't exist (real name `_DIRECT_MODELS`); "five registries" should be "up to six"; the icon override path is dead but documented as live; six hand-maintained counts drift on every change.
+- **Authoring shape is ambiguous.** Today 117 plugins are bare `.py` at the group root; 4 use the folder pattern. New contributors see two shapes and pick the wrong one or invent a third.
+- **Two production-grade contracts are under-documented.** Plugins inherit a Temporal activity automatically (`as_activity()` → `node.<type>.v<version>`) and emit CloudEvents through a typed envelope (`WorkflowEvent`), but the docs don't say "this is how to use them" — new authors reinvent.
+
+## 3. Goals
+
+1. One canonical authoring shape: folder-per-plugin, mandatory.
+2. Backend is the sole authority on all plugin business logic, metadata, and assets. Frontend is a rendering layer that consumes backend APIs.
+3. Document the Temporal worker contract as a first-class plugin author concern.
+4. Document the CloudEvents broadcast contract and fix three real spec violations.
+5. Eliminate dual-source-of-truth patterns (one genuine, two false-positive).
+6. Replace hand-maintained counts with derivation methods.
+
+## 4. Non-goals
+
+- No new pytest invariants beyond what already exists.
+- No wiring of per-node Temporal activity dispatch in `temporal/workflow.py` (Wave 11.F gap — separate sprint).
+- No capability-mixin implementation (mention as future direction only).
+- No entry-point-based third-party plugin loading.
+- No edits to `themedGlyphs.ts` (UI chrome, not plugin media).
+
+## 5. Design principles
+
+- **Backend owns all business logic and plugin metadata.** Plugin discovery, NodeSpec emission, output schema, credentials, icon, color, docs — all backend-resident. The frontend consults `GET /api/schemas/nodes/...` and renders.
+- **Frontend is a thin UI layer.** No business decisions, no per-plugin TypeScript code, no static fallback tables. Frontend reads the spec, renders the canvas, sends WS messages, displays broadcasts.
+- **Folder per plugin** keeps a plugin's surface area contained — code, credentials, helpers, icon, README all in one directory. The runtime sees one Python package per plugin.
+- **Auto-discovery over manifest.** `__init_subclass__` registers plugins on import; `pkgutil.walk_packages` walks the filesystem. No `package.json`-style manifest; no YAML registry.
+- **Typed envelopes over raw dicts.** `WorkflowEvent` Pydantic envelope locked by pytest invariants for every server→FE broadcast. Telemetry-high-frequency is the only documented carve-out.
+
+## 6. Design
+
+### 6.1 Canonical plugin folder
+
+```
+server/nodes/<group>/<plugin>/
+├── __init__.py # Required. Wiring hub (zero business logic).
+├── icon.svg # Required. Co-located plugin icon.
+├── icon.dark.svg # Optional. Dark-mode variant.
+├── README.md # Recommended. Per-plugin docs.
+├── _credentials.py # Optional. Credential subclasses.
+├── _service.py # Optional. Long-lived singleton (bot/daemon/SDK).
+├── _install.py # Optional. Binary auto-installer.
+├── _source.py # Optional. EventSource subclass.
+├── _handlers.py # Optional. WS_HANDLERS dict.
+├── _filters.py # Optional. Event filter builder (incoming events).
+├── _refresh.py # Optional. Status refresh + trigger precheck.
+├── _events.py # Optional. Plugin-specific WorkflowEvent factories + broadcaster wrappers.
+├── _router.py # Optional. FastAPI APIRouter.
+├── _option_loaders.py # Optional. Dynamic dropdown loaders.
+├── _runtime.py # Optional. Process supervisor.
+├── <plugin>.py # Single-class plugin. (Or class lives in __init__.py.)
+│
+├── <plugin>_send.py # Multi-class split: one file per node class.
+└── <plugin>_receive.py
+```
+
+`__init__.py` is purely declarative wiring. Underscore-prefixed files are package-private (skipped by `pkgutil.walk_packages` discovery — they exist only to be imported from `__init__.py`).
+
+### 6.2 Shared class hierarchy
+
+| Tier | Location | Members |
+|---|---|---|
+| Framework bases | `server/services/plugin/` | `BaseNode`, `ActionNode`, `TriggerNode`, `ToolNode`, `WebhookTriggerNode` |
+| Domain bases | `server/nodes/<group>/_base.py` | `AndroidServiceBase`, `ChatModelBase`, `SpecializedAgentBase`, `CodeExecutorBase`, `GoogleAPIBase`, `TwitterAPIBase`, `WhatsAppBase`, `SocialBase`, `EmailBase` |
+
+A new plugin in group `X` checks `nodes/X/_base.py` for a domain base first; inherits from it if present, otherwise inherits from the appropriate framework base. Never inherits from another plugin's class.
+
+### 6.3 Temporal worker contract
+
+**Auto-registration.** Every `BaseNode` subclass gets a Temporal activity via `as_activity()` (`server/services/plugin/base.py:428-454`). The classmethod returns `@activity.defn(name=f"node.{cls.type}.v{cls.version}")`. `TemporalWorkerPool.collect_plugin_activities(task_queue=...)` filters plugins by `cls.task_queue` and registers their activities into the matching worker.
+
+**Plugin author declares** (class attributes on `BaseNode` subclass):
+- `type: str` — activity name becomes `node.<type>.v<version>`.
+- `version: int` — bump on backward-incompatible signature changes (Temporal versioning is name-driven).
+- `task_queue: str` — one of `TaskQueue.*` enum (`scaling.py:17-37`): `DEFAULT`, `REST_API`, `AI_HEAVY`, `CODE_EXEC`, `TRIGGERS_POLL`, `TRIGGERS_EVENT`, `ANDROID`, `BROWSER`, `MESSAGING`.
+- `start_to_close_timeout: timedelta` — **mandatory**. Plugin author owns the per-attempt budget. Framework removes its default; `__init_subclass__` raises at registration if missing.
+- `retry_policy: RetryPolicy` — optional override of `DEFAULT_RETRY`.
+- `heartbeat_timeout: timedelta` — optional override of `DEFAULT_HEARTBEAT` (2 min).
+
+**Framework guarantees:**
+- `NodeUserError` is auto-injected into `retry_policy.non_retryable_error_types`. User-correctable failures never burn retries (matches Temporal's documented "bad input data" non-retryable case).
+- The activity's WebSocket read loop calls `activity.heartbeat()` every 30s (`activities.py:220-242`). Long-running plugins (DeepAgent, browser automation) survive past the 2-min `heartbeat_timeout`.
+- `Worker.graceful_shutdown_timeout = timedelta(seconds=30)` — explicit shutdown window honoring SIGTERM (`worker.py`).
+
+**Documented gap:** per-node activity dispatch (Wave 11.F intent) is partially wired. `as_activity()` registers per-type activities but `temporal/workflow.py:177-183` still schedules the legacy `"execute_node_activity"` name. Functionally equivalent today (one activity dispatches by `node_type`); migration tracked separately.
+
+### 6.4 CloudEvents broadcast contract
+
+**Envelope.** Every server→FE broadcast wraps `WorkflowEvent` (CloudEvents v1.0; `server/services/events/envelope.py`). Pydantic model stronger than `cloudevents/sdk-python` (which is dict-based). Locked by pytest invariants in `tests/credentials/test_credential_broadcasts.py:120-152` and `tests/test_status_broadcasts.py:87-473`.
+
+**Wire shape** on the WebSocket: `{"type": "<legacy_routing_key>", "data": <WorkflowEvent JSON>}`. Outer wrapper is a MachinaOs transport envelope (not strict CloudEvents WS binding) — defensible because the WS channel multiplexes non-CloudEvent traffic. Inner `data` is the typed envelope and consumers route on `data.type`.
+
+**Three real spec-compliance fixes** (this RFC):
+
+1. **Extension attribute naming.** CloudEvents v1.0 mandates lowercase-alphanumeric extension keys (no underscores, dashes, dots). Today's `workflow_id`, `trigger_node_id`, `correlation_id` are non-conformant. Rename to `workflowid`, `triggernodeid`, `correlationid`. Update all 9 typed factories, frontend `cloudEvents.ts` interface, WebSocketContext readers, pytest assertions.
+2. **`type` reverse-DNS prefix.** CloudEvents Primer SHOULDs the reverse-DNS convention. Today's `credential.api_key.connected`, `agent.progress` become `com.machinaos.credential.api_key.connected`, `com.machinaos.agent.progress`. Affects all 9 typed factories and frontend glob patterns.
+3. **`dataschema` URI per event type.** Add `dataschema = f"machinaos://schemas/events/{type_segment}.json"` to each factory; pair with `GET /api/schemas/events/<type>.json` endpoint returning the Pydantic-derived JSON Schema for the event's `data` field.
+
+**Two factory tiers — plugin-specific factories live in the plugin folder.**
+
+- **Cross-cutting factories** stay in `server/services/events/envelope.py`. These are parametrized by plugin name and serve any plugin: `credential`, `oauth_completed`, `connection_status`, `agent_progress`, `task_completed`, `workflow_lifecycle`, `deployment_snapshot`, `team_event`.
+- **Plugin-specific factories** live in the plugin folder's `_events.py`. The plugin alone owns its event types, data payloads, and broadcaster wrappers. Examples: `telegram_message_received`, `stripe_payment_succeeded`, `whatsapp_group_invite`. Today these are mixed into central `envelope.py` (`WorkflowEvent.message(plugin, direction, data)` is parametrized but lives centrally); a migration step (Phase 5b) moves the plugin-specific ones out.
+
+**Plugin event author rule** (canonical four-step pattern for a new plugin-owned event type):
+
+1. **Add a typed factory in the plugin's `_events.py`** (NOT central `envelope.py`):
+ ```python
+ # server/nodes/telegram/_events.py
+ from services.events.envelope import WorkflowEvent
+
+ def telegram_message_received(*, chat_id: str, text: str, workflowid: str | None = None) -> WorkflowEvent:
+ return WorkflowEvent(
+ source="machinaos://nodes/telegram",
+ type="com.machinaos.telegram.message.received",
+ subject=chat_id,
+ dataschema="machinaos://schemas/events/telegram.message.received.json",
+ data={"chat_id": chat_id, "text": text},
+ workflowid=workflowid,
+ )
+
+ async def broadcast_telegram_message_received(broadcaster, **kwargs):
+ event = telegram_message_received(**kwargs)
+ await broadcaster.broadcast({
+ "type": "telegram_message_received",
+ "data": event.model_dump(mode="json"),
+ })
+ ```
+2. **Import + register from the plugin's `__init__.py`** so the broadcaster wrapper is reachable:
+ ```python
+ from ._events import broadcast_telegram_message_received # noqa: F401 — re-export
+ ```
+ Plugin code (e.g. `_service.py`) imports the wrapper from the plugin module and calls it with the singleton `StatusBroadcaster` instance.
+3. **Add a frontend handler in `client/src/contexts/WebSocketContext.tsx`** routing on the wire key (`telegram_message_received`). The frontend is plugin-aware only at the wire-key level — no plugin-specific TypeScript code beyond the case branch + the typed cast on `msg.data`.
+4. **Add a pytest parity test in `tests/test_status_broadcasts.py`** using `inspect.getsource` introspection (mirrors existing pattern). The test asserts the broadcaster wrapper constructs the typed envelope and emits with the expected wire key.
+
+**What lives where (definitive table):**
+
+| Concern | Location | Why |
+|---|---|---|
+| Cross-cutting event factories (`credential`, `agent_progress`, etc.) | `server/services/events/envelope.py` | Parameterized by plugin name; serve every plugin uniformly. |
+| Cross-cutting broadcaster helpers (`broadcast_credential_event`, `broadcast_agent_progress`) | `server/services/status_broadcaster.py` | Same reasoning — cross-cutting. |
+| Plugin-specific event factories | `server/nodes/<group>/<plugin>/_events.py` | Plugin alone owns its events; no central catalog touched on plugin add. |
+| Plugin-specific broadcaster wrappers | `server/nodes/<group>/<plugin>/_events.py` | Co-located with factories. |
+| Wire-key routing on frontend | `client/src/contexts/WebSocketContext.tsx` | The frontend is a thin renderer — one switch case per wire key; no plugin-specific logic. |
+| Pytest invariants | `server/tests/test_status_broadcasts.py` + `tests/credentials/test_credential_broadcasts.py` | Centralized for contract-locking. |
+
+**Forbidden.** Emitting raw-dict payloads via `update_node_status` for new event types. `_LEGACY_RAW_DICT_CALLSITES` allowlist (`test_status_broadcasts.py:87-109`) is closed; only telemetry-high-frequency carve-outs (node_status, variable updates, logs) are permanently exempt. Plugin-specific factories MUST NOT be added to central `envelope.py` — they belong in the plugin folder.
+
+**Definition — plugin-specific vs cross-cutting:**
+
+A factory is **plugin-specific** if its `type` string names a single plugin (`com.machinaos.telegram.message.received`, `com.machinaos.stripe.payment.succeeded`, `com.machinaos.whatsapp.group.joined`). These move to `_events.py` in the plugin folder.
+
+A factory is **cross-cutting** if its `type` follows a shape parameterized by plugin name and uses identical payload structure across plugins: `credential.<action>` (every plugin with credentials), `oauth.completed` (every OAuth plugin), `agent.progress` (every agent), `task.completed` (every delegated task), `workflow.<stage>` (workflow lifecycle), `deployment.snapshot` (deployment state). These stay in central `envelope.py`.
+
+The current `WorkflowEvent.message(plugin, direction, data)` and `WorkflowEvent.connection_status(plugin, ...)` factories are borderline — they're parameterized but each plugin emits its own type-string variant (`telegram.message.received`, `whatsapp.message.received`). Phase 5b moves these into per-plugin `_events.py` files because each plugin's message payload differs (Telegram messages have chat_id; WhatsApp messages have phone_number + group_jid) — the central parametrized factory was lossy.
+
+### 6.5 Icon and media handling — backend owns, frontend consumes
+
+**Storage**: per-plugin `icon.svg` co-located in `server/nodes/<group>/<plugin>/`.
+
+**Serving**: new backend endpoint `GET /api/schemas/nodes/{type}/icon` reads the SVG from disk and returns it with `Content-Type: image/svg+xml` and a cache header. Optional `?variant=dark` for `icon.dark.svg`. NodeSpec metadata exposes the URL: `{"icon": "/api/schemas/nodes/aiAgent/icon"}` instead of the legacy `asset:aiAgent` wire format. Adds one route to `server/routers/schemas.py` (or wherever the existing `/api/schemas/nodes/<type>/spec.json` route lives).
+
+**Frontend resolver** (`client/src/assets/icons/index.ts` + `NodeIcon.tsx`):
+- Existing `import.meta.glob('./**/*.svg', {eager: true, query: '?raw'})` stays — covers themed glyphs (`themedGlyphs.ts`) and library icons.
+- Dispatch becomes: `lobehub:<brand>` → React component; emoji/text → inline; URL (starts with `/api/schemas/nodes/…/icon` or `https://`) → `<img src={url}>`; legacy `asset:<key>` → bundled `ICON_REGISTRY` (kept for transition; removed when migration completes).
+
+**Why API-served, not build-step copy**: the frontend is a thin UI layer. Build-time coupling between `server/nodes/**/*.svg` and `client/public/node-icons/...` makes the frontend a stakeholder in backend file layout. API-served icons mean the backend is the sole authority on plugin assets; the frontend just renders URLs. Hot-reload works without rebuilding the frontend; new plugins drop in without a build step. Browser HTTP cache handles performance.
+
+**`visuals.json` shrinks** to entries that don't have a folder `icon.svg`:
+- Emoji-only plugins.
+- `lobehub:<brand>` library icons.
+- Color overrides (icon defaults to the folder `icon.svg`; color stays declared until colors also move to per-folder `meta.json` — deferred).
+
+**Stays put** (NOT plugin media): `client/src/assets/icons/themedGlyphs.ts` (UI chrome — 290 glyphs across 29 keys × 10 themes), `@lobehub/icons` library imports.
+
+### 6.6 Eliminate the icon/color class-attr dead path
+
+`server/services/plugin/base.py`:
+- Delete `icon: ClassVar[str] = ""` and `color: ClassVar[str] = ""` (lines 123-124).
+- Simplify `_metadata_dict` lines 206-207: `icon = get_icon(cls.type)`, `color = get_color(cls.type)`.
+- Remove docstring sentence about the optional override (lines 199-203).
+
+Audit confirmed: 0 of 122 plugins set these attributes; `visuals.json` covers 100% of types. Branch is dead. `_metadata_dict` then computes icon as the API URL `f"/api/schemas/nodes/{cls.type}/icon"` when an `icon.svg` exists in the plugin folder, falling back to `get_icon(cls.type)` from `visuals.json` for emoji/library entries.
+
+### 6.7 Doc rewrites — what changes where
+
+| File | Sections rewritten |
+|---|---|
+| `CLAUDE.md` | "Adding a new node — the canonical recipe", "Icon + color", "WebSocket-first architecture" handler count |
+| `docs-internal/plugin_system.md` | "Adding a new node", "Registries" (5→up-to-6 plus `register_router`), new "Temporal worker contract" + "CloudEvents broadcast contract" sections, icon section |
+| `docs-internal/node_creation.md` | "Choose your shape" → one shape; full walkthrough rewritten around folder template |
+| `docs-internal/schema_source_of_truth_rfc.md` | `NODE_INPUT_MODELS` → `_DIRECT_MODELS`; path claim updated; icon section |
+| `server/nodes/README.md` | Quick-start + 5-minute recipe rewritten around folder template + Temporal + CloudEvents contracts |
+| `docs-internal/ai_tool_node_creation.md`, `specialized_agent_node_creation.md`, `dual_purpose_tool_node_creation.md` | Banner verification only (prepend pre-Wave-11 historical-reference banner if missing) |
+
+### 6.8 Factual corrections + count strip
+
+**Discrepancies:**
+- `NODE_INPUT_MODELS` → `_DIRECT_MODELS` in `plugin_system.md:79-81`, `node_creation.md:210`, `schema_source_of_truth_rfc.md:39`.
+- "Five cross-cutting registries" → "Up to six" in `plugin_system.md:482`. Add `register_router` (`services/ws_handler_registry.py:85-94`).
+- Telegram "6 register_* calls" → 5 in `plugin_system.md:468`, `server/nodes/README.md:227`.
+
+**Counts replaced with derivation methods:**
+
+| File:line | Stale | Replace with |
+|---|---|---|
+| `CLAUDE.md:49` | "89 handlers" | "live count via `len(MESSAGE_HANDLERS) + len(get_ws_handlers())`" |
+| `plugin_system.md:9` | "111 plugin classes … 124 pytest invariants" | "live count via `glob server/nodes/**/__init__.py`" |
+| `plugin_system.md:674` | "108 … 124 total" | "live total via `pytest --collect-only`" |
+| `schema_source_of_truth_rfc.md:7` | "98 Pydantic models" | "live size via `len(NODE_OUTPUT_SCHEMAS)`" |
+| `schema_source_of_truth_rfc.md:20` | "105 input models" | "live count via `len(_DIRECT_MODELS)`" |
+| `schema_source_of_truth_rfc.md:25` | "25 groups with 110 entries … 34 hand-rolled" | "live count via `len(NODE_GROUPS)`" |
+
+Snapshot counts marking historical milestones (`12.8K → 1.1K LOC`) stay.
+
+## 7. Implementation phases
+
+| # | Phase | Scope | Risk |
+|---|---|---|---|
+| 1 | Dead-path removal | `server/services/plugin/base.py` icon/color class attrs | Low |
+| 2 | Factual corrections + count strip | 5 doc files | Low |
+| 3 | Folder-template doc rewrite | 5 doc files | Low |
+| 4 | Temporal contract tightening | `base.py` mandatory `start_to_close_timeout`, `scaling.py` NodeUserError mapping, `Worker` graceful_shutdown_timeout | Medium (touches every plugin — need migration) |
+| 5a | CloudEvents spec fixes | `envelope.py` extension rename + type prefix + dataschema; `cloudEvents.ts` interface; `WebSocketContext.tsx` readers; pytest assertions | Medium (wire-format change — coordinate FE+BE in one commit) |
+| 5b | Migrate plugin-specific factories to plugin folders | Move `WorkflowEvent.message(plugin, ...)` and any plugin-named factories from `services/events/envelope.py` into `server/nodes/<plugin>/_events.py`. Audit existing broadcaster calls in `_service.py` files (whatsapp, telegram, stripe) — they currently hand-construct envelopes; refactor to import the per-plugin wrapper from `_events.py`. Update pytest invariants to assert plugin-specific factories are NOT in central `envelope.py`. | Medium (touches plugin services that emit events today) |
+| 6 | Icon endpoint | `server/routers/schemas.py` new `GET /api/schemas/nodes/{type}/icon`; `_metadata_dict` URL emission | Low |
+| 7 | Frontend icon resolver | `index.ts` + `NodeIcon.tsx` URL dispatch | Low |
+| 8 | Plugin migration to folders | 117 plugins, group-by-group; pytest-gated per batch | High volume, low per-unit risk |
+| 9 | SVG migration to per-folder | 30 SVGs move from `client/src/assets/icons/<group>/<name>.svg` to `server/nodes/<group>/<plugin>/icon.svg` | Low |
+| 10 | Banner verification | 3 pre-Wave-11 historical guides | Low |
+
+**Phase 8 batch order** (lowest-risk first):
+
+| Batch | Groups | Plugin count |
+|---|---|---|
+| B1 | chat, scheduler, text, workflow | 7 |
+| B2 | tool, search, trigger, utility | 17 |
+| B3 | location, proxy, scraper, skill | 10 |
+| B4 | document, filesystem, browser | 11 |
+| B5 | code, email | 6 |
+| B6 | model (`ChatModelBase`) | 11 |
+| B7 | agent (`SpecializedAgentBase`) | 19 |
+| B8 | google, twitter, social | 13 |
+| B9 | android (`AndroidServiceBase`) | 16 |
+| B10 | telegram, stripe, whatsapp | 7 (verify only — already folder-shape) |
+
+Per-batch verification: `pytest tests/test_node_spec.py -x && pytest tests/test_plugin_self_containment.py -x && pytest tests/ -x` plus frontend smoke (drag 3 migrated nodes onto canvas).
+
+## 8. Migration / rollout
+
+**Phase 1-3** ship independently (doc fixes + dead-code removal). No runtime effect.
+
+**Phase 4 (mandatory `start_to_close_timeout`)** is breaking — every plugin must declare it. Migration: walk all 122 plugins, add `start_to_close_timeout = timedelta(minutes=…)` matching the kind-specific default the framework had (ACTION 10m, AI 30m, TRIGGER 24h, CODE 5m). Single commit, gated by pytest registration check.
+
+**Phase 5 (CloudEvents spec fixes)** is a wire-format change — extension keys rename + type prefix change. FE + BE coordinated in one commit. Existing connected sessions hit one disconnect/reconnect cycle; no persistent data affected. Pytest invariants in `test_credential_broadcasts.py` and `test_status_broadcasts.py` update in the same commit.
+
+**Phases 6-7 (icon endpoint + frontend resolver)** ship together. The frontend keeps the legacy `asset:<key>` → bundled `ICON_REGISTRY` fallback during transition. Remove the fallback after Phase 9 completes.
+
+**Phase 8 (plugin migration)** runs in 10 batches over multiple commits. Each batch is mechanical and reversible. Pytest invariants gate progress.
+
+**Phase 9 (SVG migration)** runs after Phase 8 (per-plugin folders exist) and after Phase 6 (endpoint serves the new location).
+
+## 9. Backward compatibility
+
+- **Legacy `asset:<key>` wire format** stays during transition. Frontend resolver: URL paths (start with `/`) → `<img>`; `asset:<key>` → bundled `ICON_REGISTRY`; emoji/text → inline; `lobehub:<brand>` → React component. Bundled registry removed after Phase 9.
+- **CloudEvents wire keys** (the outer `type` value) stay unchanged for existing event types — only the inner `WorkflowEvent.type` gains the `com.machinaos.` prefix. Frontend handlers route on the outer wire key (e.g., `case 'credential_catalogue_updated'`) so they continue to work without coordination.
+- **Plugin imports.** Migrating `server/nodes/tool/calculator_tool.py` to `server/nodes/tool/calculator_tool/__init__.py` preserves the import path `from nodes.tool.calculator_tool import CalculatorToolNode`. Sub-module imports like `from nodes.tool.calculator_tool.calculator_tool import X` work for multi-class plugins. Audit `server/tests/` before each batch for deeper imports.
+
+## 10. Open questions
+
+None blocking. Three follow-ups deferred:
+
+1. Migrate node colors from `visuals.json` to per-plugin `meta.json` (matches icon co-location for color).
+2. Capability mixins (`RequiresOAuth`, `SupportsStreaming`) per Prefect's pattern.
+3. Per-node Temporal activity dispatch in `temporal/workflow.py` (Wave 11.F gap).
+
+## 11. Verification
+
+**Code edits:**
+- `git grep -E "cls\.icon|cls\.color"` in `server/services/plugin/base.py` → 0 hits.
+- `git grep -E "(icon|color): ClassVar"` in `server/` → 0 hits.
+- `git grep -E "\bworkflow_id\b|\btrigger_node_id\b|\bcorrelation_id\b" server/services/events/envelope.py` → 0 hits.
+- `git grep -E '"type":\s*"(credential|agent|workflow|team|connection)\.[^c]'` in `envelope.py` → 0 hits (every event type starts with `com.machinaos.`).
+- Boot backend; `GET /api/schemas/nodes/aiAgent/spec.json` returns populated `metadata.icon` pointing at `/api/schemas/nodes/aiAgent/icon`.
+- `GET /api/schemas/nodes/aiAgent/icon` returns SVG with `Content-Type: image/svg+xml`.
+- `pytest server/tests/ -x` passes, including the three load-bearing suites: `test_node_spec.py`, `test_plugin_self_containment.py`, `test_credential_broadcasts.py`, `test_status_broadcasts.py`.
+- `find server/nodes/<group>/ -maxdepth 1 -type f -name '*.py' -not -name '_*' -not -name '__init__.py'` → 0 hits in every group post-Phase-8.
+
+**Doc edits:**
+- `git grep -n "NODE_INPUT_MODELS"` in docs → 0 hits.
+- `git grep -n "Five cross-cutting registries"` → 0 hits.
+- `git grep -nE "\b(89|111|98|105|110|124) (handlers|plugins|invariants|models|entries)"` → 0 hits.
+- Five canonical doc files contain "Canonical folder template", "Temporal worker contract", "CloudEvents broadcast contract" sections.
+- Hypothetical "add a `weatherForecast` ToolNode" walkthrough: one path through the docs, no ambiguity.
+
+**Frontend behavior:**
+- Canvas renders every plugin icon (no broken-image fallbacks).
+- Browser network tab shows GETs to `/api/schemas/nodes/<type>/icon` returning 200 with SVG bodies.
+- No build-step references `server/nodes/**/*.svg` (frontend is decoupled).
+
+## 12. References
+
+**MachinaOs (internal):**
+- `server/services/plugin/base.py:428-454` — `as_activity()`.
+- `server/services/plugin/scaling.py:17-37` — `TaskQueue` enum, retry defaults.
+- `server/services/temporal/workflow.py:177-183` — orchestrator scheduling (gap noted).
+- `server/services/temporal/activities.py:220-242` — heartbeat-in-WS-read-loop.
+- `server/services/temporal/worker.py:171-268` — `TemporalWorkerPool`.
+- `server/services/events/envelope.py` — `WorkflowEvent` model + 9 typed factories.
+- `server/services/status_broadcaster.py:286-352` — reference broadcaster methods.
+- `server/tests/credentials/test_credential_broadcasts.py:120-152` — CloudEvents shape invariant.
+- `server/tests/test_status_broadcasts.py:87-473` — broadcast contract + `_LEGACY_RAW_DICT_CALLSITES`.
+- `client/src/types/cloudEvents.ts` — frontend envelope interface.
+- `client/src/contexts/WebSocketContext.tsx:698-712, 844-876` — broadcast handler reference.
+- `server/nodes/telegram/`, `stripe/`, `whatsapp/`, `android/` — reference folder plugins.
+
+**External standards:**
+- CloudEvents v1.0 — https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md
+- CloudEvents WebSocket binding — https://github.com/cloudevents/spec/blob/main/cloudevents/bindings/websockets-protocol-binding.md
+- CloudEvents Primer (naming guidance) — https://github.com/cloudevents/spec/blob/main/cloudevents/primer.md
+- Temporal Python SDK — https://docs.temporal.io/develop/python
+- Temporal activity decorator API — https://python.temporal.io/temporalio.activity.html
+- Temporal retry policies — https://docs.temporal.io/encyclopedia/retry-policies
+- Temporal activity failure detection / heartbeats — https://docs.temporal.io/encyclopedia/detecting-activity-failures
+
+**Industry references (architecture patterns):**
+- n8n per-node folder + co-located SVG — https://github.com/n8n-io/n8n/tree/master/packages/nodes-base/nodes/Telegram
+- Pipedream `components/<app>/` + `common/` folder pattern — https://github.com/PipedreamHQ/pipedream/tree/master/components
+- Prefect block + capability-mixin pattern — https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py
+- Nango YAML provider registry (rejected for MachinaOs) — https://github.com/NangoHQ/nango/tree/master/packages/providers
+- Composio cloud-registry model (rejected — we're self-hosted) — https://docs.composio.dev
+
+## 13. Diff size (rough)
+
+| Area | Lines |
+|---|---|
+| `server/services/plugin/base.py` | ~50 changed (dead path, mandatory timeout, NodeUserError mapping, icon URL emission) |
+| `server/services/events/envelope.py` | ~80 changed (extension rename, type prefix, dataschema) + ~50 removed (plugin-specific factories moved out) |
+| `server/nodes/<plugin>/_events.py` (5-8 plugins) | ~40-80 added per plugin (telegram, whatsapp, stripe, twitter, google) |
+| `server/services/plugin/scaling.py` | ~10 changed |
+| `server/routers/schemas.py` | ~30 added (icon endpoint) |
+| `client/src/assets/icons/index.ts` + `NodeIcon.tsx` | ~30 changed (URL dispatch) |
+| `client/src/types/cloudEvents.ts` | ~10 changed (extension keys) |
+| `client/src/contexts/WebSocketContext.tsx` | ~30 changed (extension readers + type pattern updates) |
+| `server/nodes/visuals.json` | ~80 lines removed |
+| `CLAUDE.md` | ~140 (80 changed + 60 added) |
+| `docs-internal/plugin_system.md` | ~400 (150 changed + 250 added — Temporal contract + CloudEvents contract + folder template) |
+| `docs-internal/node_creation.md` | ~180 (80 changed + 100 added) |
+| `docs-internal/schema_source_of_truth_rfc.md` | ~30 changed |
+| `server/nodes/README.md` | ~220 (100 changed + 120 added) |
+| 3 exemplar READMEs (telegram, stripe, calculator) | ~150 added |
+| Pytest assertion updates | ~50 changed |
+| Plugin migration | 117 file moves |
+| SVG migration | 30 file moves |
+
+Total: ~1100-1400 doc lines, ~300 code lines, 147 file moves. Phase 8 is heaviest by volume (mechanical, pytest-gated). Phase 5 has the highest coordination risk (wire-format change requires FE+BE in one commit).