Self-improving AI Employees for everyone
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
1e18d3ethrough134e7a8). Preserved here as a design-rationale record. For current state see:
- TEMPORAL_ARCHITECTURE.md — three Temporal dispatch paths (legacy / per-type / AgentWorkflow)
- plugin_system.md — Wave 11 plugin model (BaseNode hierarchy, six generic registries, credentials, Wave 12 event framework)
- server/nodes/README.md — canonical authoring recipe (folder-per-plugin, icon.svg, meta.json)
- status_broadcaster.md — CloudEvents v1.0 envelope contract (
WorkflowEventfactories, broadcaster wrappers)- node_creation.md — decision tree for new plugins
| 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_MODELSdoesn'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
.pyat 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
- One canonical authoring shape: folder-per-plugin, mandatory.
- Backend is the sole authority on all plugin business logic, metadata, and assets. Frontend is a rendering layer that consumes backend APIs.
- Document the Temporal worker contract as a first-class plugin author concern.
- Document the CloudEvents broadcast contract and fix three real spec violations.
- Eliminate dual-source-of-truth patterns (one genuine, two false-positive).
- 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 inShipped post-RFC as F4.A (committemporal/workflow.py(Wave 11.F gap — separate sprint).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_packageswalks the filesystem. Nopackage.json-style manifest; no YAML registry. - Typed envelopes over raw dicts.
WorkflowEventPydantic 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 becomesnode.<type>.v<version>.version: int— bump on backward-incompatible signature changes (Temporal versioning is name-driven).task_queue: str— one ofTaskQueue.*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 ofDEFAULT_RETRY.heartbeat_timeout: timedelta— optional override ofDEFAULT_HEARTBEAT(2 min).
Framework guarantees:
NodeUserErroris auto-injected intoretry_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-minheartbeat_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 resolvesnode.{type}.v{version}per plugin via the registry;BaseNode.as_activity()returns a full pipeline-replacement activity that callsworkflow_service.execute_node()in-process (skipping the legacy WS round-trip). All per-type activities register alongside the legacyexecute_node_activityso flag-off is byte-identical. Per-queue routing (cls.task_queue) waits forTemporalWorkerPoolto be wired inmain.py. - F4.B (commit
a4d009e,TEMPORAL_AGENT_WORKFLOW_ENABLED):AgentWorkflowTemporal child workflow + 3 activities (agent.execute_llm_step.v1,agent.persist_turn.v1,agent.compact_memory.v1). When enabled, the orchestrator schedulesAgentWorkflowfor the 15 migrating agent types instead of an activity; tool calls inside the loop become per-type activities.deep_agent/rlm_agent/claude_code_agentstay 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):
- Extension attribute naming. CloudEvents v1.0 mandates lowercase-alphanumeric extension keys (no underscores, dashes, dots). Today's
workflow_id,trigger_node_id,correlation_idare non-conformant. Rename toworkflowid,triggernodeid,correlationid. Update all 9 typed factories, frontendcloudEvents.tsinterface, WebSocketContext readers, pytest assertions. typereverse-DNS prefix. CloudEvents Primer SHOULDs the reverse-DNS convention. Today'scredential.api_key.connected,agent.progressbecomecom.opencompany.credential.api_key.connected,com.opencompany.agent.progress. Affects all 9 typed factories and frontend glob patterns.dataschemaURI per event type. Adddataschema = f"opencompany://schemas/events/{type_segment}.json"to each factory; pair withGET /api/schemas/events/<type>.jsonendpoint returning the Pydantic-derived JSON Schema for the event'sdatafield.
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 at7c9e873— replaces 3 legacy raw-dict emission sites: parameter-panel save, Claude CLI memory bridge, AgentWorkflow per-turn memory; distinguished bysource_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 centralenvelope.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):
- Add a typed factory in the plugin's
_events.py(NOT centralenvelope.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"), }) - Import + register from the plugin's
__init__.pyso the broadcaster wrapper is reachable:
Plugin code (e.g.from ._events import broadcast_telegram_message_received # noqa: F401 — re-export_service.py) imports the wrapper from the plugin module and calls it with the singletonStatusBroadcasterinstance. - Add a frontend handler in
client/src/contexts/WebSocketContext.tsxrouting 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 onmsg.data. - Add a pytest parity test in
tests/test_status_broadcasts.pyusinginspect.getsourceintrospection (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 centralenvelope.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.pyhand-constructsWorkflowEvent(...)directly. Stripe webhook events keep their producer-side type (stripe.charge.succeeded— nocom.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/…/iconorhttps://) →<img src={url}>; legacyasset:<key>→ bundledICON_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-foldermeta.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] = ""andcolor: ClassVar[str] = ""(lines 123-124). - Simplify
_metadata_dictlines 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_MODELSinplugin_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. Addregister_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>→ bundledICON_REGISTRY; emoji/text → inline;lobehub:<brand>→ React component. Bundled registry removed after Phase 9. - CloudEvents wire keys (the outer
typevalue) stay unchanged for existing event types — only the innerWorkflowEvent.typegains thecom.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.pytoserver/nodes/tool/calculator_tool/__init__.pypreserves the import pathfrom nodes.tool.calculator_tool import CalculatorToolNode. Sub-module imports likefrom nodes.tool.calculator_tool.calculator_tool import Xwork for multi-class plugins. Auditserver/tests/before each batch for deeper imports.
10. Open questions
None blocking. Status of the three original follow-ups:
- ✅ Migrate node colors from
visuals.jsonto per-pluginmeta.json— Shipped (F2, commits796d365+637de1e). 113 plugin folders shipmeta.json. Resolver:get_plugin_meta(type, 'color')falls through toget_color()for legacy entries. - Capability mixins (
RequiresOAuth,SupportsStreaming) — Still deferred (F3). - ✅ Per-node Temporal activity dispatch + AgentWorkflow — Shipped behind flags (F4.A
8261b05+ F4.B infraa4d009e). 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"inserver/services/plugin/base.py→ 0 hits.git grep -E "(icon|color): ClassVar"inserver/→ 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]'inenvelope.py→ 0 hits (every event type starts withcom.opencompany.).- Boot backend;
GET /api/schemas/nodes/aiAgent/spec.jsonreturns populatedmetadata.iconpointing at/api/schemas/nodes/aiAgent/icon. GET /api/schemas/nodes/aiAgent/iconreturns SVG withContent-Type: image/svg+xml.pytest server/tests/ -xpasses, 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
weatherForecastToolNode" 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>/iconreturning 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—TaskQueueenum, 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—WorkflowEventmodel + 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 OpenCompany) — 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).