Skip to content

Self-improving AI Employees for everyone

33.3 KB
Raw Blame

RFC: Plugin Authoring Standard — Folder-Default + Temporal Activities + CloudEvents Broadcasts

ARCHIVED — Shipped Sprint Plan. This RFC's recommendations were shipped across Waves 11.H, F1, F2, F4.A, F4.B, F5, F6, F7 (commits 1e18d3e through 134e7a8). Preserved here as a design-rationale record. For current state see:

Field Value
Status Shipped (archived 2026-05-14)
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 OpenCompany: 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). Shipped post-RFC as F4.A (commit 8261b05).
  • 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).

Status (F4): per-node activity dispatch shipped behind a settings flag:

  • F4.A (commit 8261b05, TEMPORAL_PER_TYPE_DISPATCH): orchestrator resolves node.{type}.v{version} per plugin via the registry; BaseNode.as_activity() returns a full pipeline-replacement activity that calls workflow_service.execute_node() in-process (skipping the legacy WS round-trip). All per-type activities register alongside the legacy execute_node_activity so flag-off is byte-identical. Per-queue routing (cls.task_queue) waits for TemporalWorkerPool to be wired in main.py.
  • F4.B (commit a4d009e, TEMPORAL_AGENT_WORKFLOW_ENABLED): AgentWorkflow Temporal child workflow + 3 activities (agent.execute_llm_step.v1, agent.persist_turn.v1, agent.compact_memory.v1). When enabled, the orchestrator schedules AgentWorkflow for the 15 migrating agent types instead of an activity; tool calls inside the loop become per-type activities. deep_agent / rlm_agent / claude_code_agent stay single-activity (externalised loops). Per-agent orchestrator-dispatch wiring lands in a follow-up commit.

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 OpenCompany 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.opencompany.credential.api_key.connected, com.opencompany.agent.progress. Affects all 9 typed factories and frontend glob patterns.
  3. dataschema URI per event type. Add dataschema = f"opencompany://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, node_parameters_updated (added post-RFC at 7c9e873 — replaces 3 legacy raw-dict emission sites: parameter-panel save, Claude CLI memory bridge, AgentWorkflow per-turn memory; distinguished by source_hint).
  • 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):
    # 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="opencompany://nodes/telegram",
            type="com.opencompany.telegram.message.received",
            subject=chat_id,
            dataschema="opencompany://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:
    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 AND its payload shape differs from peers in the same domain (com.opencompany.telegram.message.received carries chat_id; com.opencompany.whatsapp.message.received carries phone_number + group_jid). These belong in _events.py in the plugin folder.

A factory is cross-cutting if either (a) its type is the same shape across plugins and the payload is identical, OR (b) its construction is invoked from a single centralized helper that fans out per plugin: 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), connection_status (single _emit_connection_typed helper in StatusBroadcaster fans out to every plugin status method). These stay in central envelope.py.

Phase 5b audit outcome:

  • WorkflowEvent.message(plugin, direction, data) — removed in Phase 5b. Zero callers in the codebase; it was speculative. Plugins that later need to emit message envelopes add a typed factory in their own _events.py.
  • WorkflowEvent.connection_status(plugin, ...) — kept in central envelope.py. Single call site (StatusBroadcaster._emit_connection_typed); the parametrization is genuinely shared. Moving per-plugin would duplicate the broadcast helper across plugins with no payload divergence.
  • nodes/stripe/_source.py hand-constructs WorkflowEvent(...) directly. Stripe webhook events keep their producer-side type (stripe.charge.succeeded — no com.opencompany. prefix since OpenCompany isn't the producer). Already in the plugin folder. No move needed.

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 at RFC time: 0 of 122 plugins set the dead class-attr icon/color. Post-Phase-8 plugin count: 113 plugin folders (live count via glob server/nodes/**/__init__.py). _metadata_dict resolves icon in three tiers (RFC §6.5 + F7 closure): per-node-type <plugin>/icon_<nodeType>.svg → shared <plugin>/icon.svg → visuals.json emoji / lobehub:<brand>. The asset:<key> fallback that originally lived in tier 3 is dead post-F7 — visuals.json carries zero asset: entries. Color resolves via per-plugin meta.json (F2) → visuals.json legacy fallback (currently empty — all 117 plugins ship meta.json).

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.opencompany. 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. Status of the three original follow-ups:

  1. ✅ Migrate node colors from visuals.json to per-plugin meta.json — Shipped (F2, commits 796d365 + 637de1e). 113 plugin folders ship meta.json. Resolver: get_plugin_meta(type, 'color') falls through to get_color() for legacy entries.
  2. Capability mixins (RequiresOAuth, SupportsStreaming) — Still deferred (F3).
  3. ✅ Per-node Temporal activity dispatch + AgentWorkflow — Shipped behind flags (F4.A 8261b05 + F4.B infra a4d009e). Per-agent orchestrator wiring for the 15 migrating types is a separate follow-up commit.

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.opencompany.).
  • 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

OpenCompany (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:

Industry references (architecture patterns):

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).