Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
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.mdnew file mode 100644index 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).