Skip to content

Self-improving AI Employees for everyone

89.3 KB
Raw Blame

Plugin System (Wave 11)

The OpenCompany plugin system is a class-based, declarative node authoring model inspired by n8n's INodeType, Nango's providers.yaml, Pipedream's app/component split, and Temporal's activity pattern. One folder under server/nodes/<group>/<plugin>/ rooted at __init__.py = one plugin (one or more node classes). No cross-cutting edits.

Status: shipped. Plugin classes cover every node type in the product — live count via glob server/nodes/**/__init__.py. Pytest contract invariants (live count = test fns under server/tests/test_node_spec.py + test_plugin_self_containment.py) lock the architecture. services/handlers/ shrank from 12.8K → 1.1K LOC across 16 → 4 files. See server/nodes/README.md for the authoring cookbook (5-minute recipe + shared helpers + common pitfalls).

Quick start — adding a new node

The full single-file recipe code block lives in the cookbook — see server/nodes/README.md → Five-minute recipe. A single folder (server/nodes/search/acme_search/__init__.py, class AcmeSearchNode) declares type / display_name / group / component_kind / handles / credentials / task_queue / usable_as_tool / Params / Output plus one @Operation method, and nothing else.

That's it. On server restart:

  • BaseNode.__init_subclass__ eagerly registers the class into four registries: NODE_METADATA, _DIRECT_MODELS, NODE_OUTPUT_SCHEMAS, _HANDLER_REGISTRY.
  • _NODE_CLASS_REGISTRY indexes the class itself so Temporal workers and tool dispatch can look it up by type.
  • NodeSpec emits automatically via GET /api/schemas/nodes/acmeSearch/spec.json.
  • _PLUGIN_HANDLERS merge in NodeExecutor makes it runnable.
  • The node appears in the Component Palette under its group (search + tool) at the next browser reload.

Architecture

The Mobile plugin is an optional runtime example: Mobile Agent (ActionNode) and Android (ToolNode) register together and advertise ui_hints.workspace.kind="mobile". Import only registers the router, schemas and shutdown hook. The Android tool uses a locked, prompt-only ToolInput; saved MobileParams retain time/step limits. Both nodes share owner checks, model resolution, task queue and broker, without integrating through the legacy Android relay. See Mobile Workspace and the Android node contract.

Class hierarchy

BaseNode (services/plugin/base.py)
├── ActionNode   fire-once, {success, result} envelope
├── TriggerNode  long-lived, event (event_waiter) or polling modes
└── ToolNode     AI-invoked, flat return (no success wrapper)

Every subclass auto-registers on import. Pure-visual or abstract intermediaries pass abstract=True in the class definition:

class SpecializedAgentBase(ActionNode, abstract=True):
    ...

Class attributes

Attribute Purpose
type Node type string. Matches workflow JSON + registry key.
version Int, bumped on breaking changes. Activity name includes it.
display_name / subtitle / description Palette + panel header.
(icon / color) Not class attributes (removed in F1 — declaring them has no effect). Icon resolves co-located icon.svg / icon_<nodeType>.svg → the plugin's own meta.json ("icons": {"<nodeType>": "lucide:Send"}, or folder-wide "icon") → visuals.json. Ship the SVG when the node has a brand mark; the meta.json ref is for generic utility nodes, and carries the risk that a third-party export name disappears on upgrade and the node then renders nothing. Color: co-located meta.json {"color": "#..."}. Wire format on the NodeSpec stays asset:<key> / <lib>:<brand> / URL / emoji.
group Tuple of palette groupings (first is primary).
component_kind Frontend dispatch: square / trigger / agent / tool / model / start / generic.
handles React Flow handle topology (input-main, output-main, …).
ui_hints Dict of panel flags (hasCodeEditor, isMemoryPanel, isMasterSkillEditor, isDataPanel, hasSkills, isConfigNode, outputMode: "terminal" for CLI-wrapper nodes whose textual output must render preformatted, …). See "Auto-derived uiHints" below — isConfigNode is set automatically for ('memory', 'tool') group plugins. Live flag list = the known set in test_node_spec.py.
annotations Pipedream-style: destructive / readonly / open_world.
credentials Sequence of Credential subclasses the node uses. More than one is supported — see Multi-credential nodes.
Params Pydantic BaseModel — user-facing parameters. Used for both UI rendering and AI tool schemas.
Output Pydantic BaseModel — runtime output shape.
usable_as_tool ActionNode flag — mints a ToolNode adapter for AI invocation. Combined with component_kind != "model", makes the plugin visible to agentBuilder.add_tool (catalogue + rebind paths). Side effect: setting it auto-sets hide_input_handle / hide_output_handle to True unless the class declares them (BaseNode.__init_subclass__ in base.py, which does the same for component_kind == "tool"), and _metadata_dict adds an output-tool handle. The frontend (SquareNode) reads the hide flags only when a spec declares no handles; a spec with handles renders exactly what it declares. So a dual-purpose node that must stay wirable on the canvas declares input-main / output-main in handles; setting the flags False alone does not add them.
needs_canvas ClassVar[bool] — when True, the F4.B AgentWorkflow tool-dispatch forwards the parent workflow's nodes/edges into the per-tool activity payload. Today only AgentBuilderNode opts in: add_tool compares the run's canvas with the saved graph, so a tool saved earlier but missing from the running snapshot is handed back to be bound. Its calling agent comes from invoking_agent_node_id / parent_node_id, not from edges.
context_keys ClassVar[Sequence[str]] — server-owned execution scope the node reads from ctx.raw, such as the Browser's claim token (_browser_task_id), its binding (_browser_owner), parameter_snapshot and the browser version flags. Both tool adapters, as_activity and the in-process _dispatch_tool, copy these keys from the run's context; a model's arguments never supply them. Without the declaration both adapters rebuilt the node's context from their own key lists, dropped the Browser's token, and the node refused its own task (BrowserBusy).
validate_graph(node_id, graph) Classmethod returning validator errors ({"code", "node_id", "message"}) for the wiring the node needs to run; none by default. validate_workflow collects them for every node, so Start and import refuse the workflow; save does not (it keeps only Context topology errors). The Browser AI Agent reports BROWSER_TOOL_REQUIRED unless exactly one Browser node is on its input-tools.
chat_step / chat_step_hidden How a call of this tool reads as a working step in the chat while it answers the owner ("Searched the web"; default "Used "); chat_step_hidden = True shows none (the clock, the checklist). A tool may put a short line in its result as _step_detail, shown under the step and removed before the model reads the result. See Chat Protocol.
answers_chat_run ClassVar[bool] — the node posts a chat run's answer (Reply in Chat). The agent wired straight into such a node streams its text into the chat.
approval ApprovalSpec (services/plugin/approval.py) for a tool that reaches someone outside: which operations send (operations, when), who it goes to, the body and subject the owner may edit, the card's other lines, refuse_while_asking (Stripe) or restrict_while_asking (the browser, read-only). While the workflow asks first, an agent's call that sends is held as a draft for the owner instead of running. See Chat Protocol, Approvals.
chat_sources ClassVar[bool] — the tool returns web results (results: [{title, snippet, url}], the searches). When the agent answering a chat run calls it, the results are numbered for the conversation in what the model reads, so the answer can cite them as [n]. See Chat Protocol.
task_queue Temporal worker pool. See TaskQueue constants.
retry_policy RetryPolicy dataclass (mirrors temporalio.common.RetryPolicy); attempts, intervals, and non-retryable error types.
start_to_close_timeout / heartbeat_timeout Per-attempt deadline / liveness window for regular Temporal Activities. Heartbeats do not extend the attempt deadline.

Polymorphic result envelope (interpret_result)

BaseNode.interpret_result(result) -> (success: bool, payload: Any, error: Optional[str]) is the classmethod the F4.A activity wrapper at BaseNode.as_activity calls to normalise broadcast inputs across node kinds:

Node kind Contract Default semantics
ActionNode / TriggerNode {success: bool, result: Any, error?: str, ...} envelope (produced by _wrap_success / _wrap_error). Inherits BaseNode.interpret_result — reads success + result + error keys.
ToolNode Flat dict IS the success payload (the LLM-feedable shape). Error paths still produce the standard envelope via _wrap_error. Overridden on ToolNode: if no success key, treat the dict as success payload; otherwise delegate to base.

This is the contract that makes writeTodos / calculatorTool etc. broadcast successfully through F4.A — without the polymorphic override, the wrapper's if result.get("success") check would treat every ToolNode result as failure and never call update_node_output.

Output contract enforcement (_serialize_result)

The declared Output model is enforced at the serialization boundary — the same semantics FastAPI applies to response_model (validate → coerce → serialize). BaseNode._serialize_result (called by both _wrap_success implementations):

  • BaseModel return → model_dump(mode="json") (datetimes → ISO strings, enums → values).
  • dict return + declared Output → Output.model_validate(result).model_dump(mode="json", exclude_unset=True). exclude_unset preserves the producer's exact key set — declared-but-absent Optional fields never materialise as None keys.
  • dict return, no declared Output (_EmptyOutput default) → pass-through.
  • Violation (wrong type in a declared field, or a non-serializable object anywhere) → standard error envelope with error_type="OutputValidationError" + full traceback in the operator log. A contract violation is a plugin bug that fails loudly at the producer instead of corrupting node_outputs persistence or the WS broadcast downstream.

Practical rules for plugin authors:

  1. Prefer returning the Output model instance (return ExampleOutput(...)). Dicts work but get validated.
  2. Output models declare extra="allow" + all-Optional fields by convention — extra context keys pass through; only type mismatches fail.
  3. Never put raw backend or SDK objects (for example a native filesystem ReadResult or provider response object) into the result — unwrap to plain fields. Everything downstream (JSON column, orjson WS broadcast, _serialise_tool_result) expects JSON-compatible data.
  4. LLM-facing string formatting is the dispatcher's job (_serialise_tool_result JSON-dumps the whole payload) — return real lists/dicts, not pre-stringified JSON.
  5. Params fields that may receive LLM-stringified JSON (Gemini sometimes stringifies array/object args in tool calls) coerce at the boundary with field_validator(..., mode="before") — see AndroidServiceParams._coerce_parameters and WriteTodosParams._coerce_todos for the canonical shape.

Defense in depth below the plugin layer: the SQLAlchemy engine in core/database.py sets json_serializer=lambda obj: json.dumps(to_jsonable_python(obj, fallback=str)) (pydantic_core.to_jsonable_python — official arbitrary-object → JSON coercion), so every JSON column on the engine tolerates dataclasses / datetimes / enums / sets even if a payload bypasses Output validation. Locked by tests/test_output_contract.py.

Error convention — NodeUserError vs bare Exception. For any failure the user (or the calling LLM) can correct — missing required field, unknown enum value, bad path, service not running — raise NodeUserError("...") (exported from services.plugin). BaseNode.execute() catches it specially: one WARN line in the operator log (no traceback) plus a structured {success: False, error_type: "NodeUserError", error: ...} envelope, and the shared Temporal retry policy treats it as non-retryable (services/plugin/scaling.py) so a bad input doesn't burn three activity attempts. Reserve bare Exception / RuntimeError for genuine server bugs — those keep the full logger.exception traceback.

Use NodeUserError(message, hint="How to recover", requires_user_action=True) for an owner-only blocker such as exhausted billing or an unusable provider credential. Keep both texts safe for public display. The framework preserves hint, requires_user_action, and retryable: false through tool results. Both agent loops stop before another model turn or compaction, and a controlled trigger deployment pauses on its first blocked run. Ordinary input errors leave requires_user_action false so the model can correct them; other run failures retain the configured circuit-breaker threshold. Temporal saves outstanding tool results before stopping so Resume has a complete tool turn. Home and the node output panel display the recovery hint.

Auto-derived uiHints

BaseNode._metadata_dict (server/services/plugin/base.py) calls _derive_auto_ui_hints(cls.group) to pre-populate panel-visibility flags from group membership before merging the plugin's explicit cls.ui_hints:

ui_hints = _derive_auto_ui_hints(cls.group)
ui_hints.update(cls.ui_hints)
if ui_hints:
    meta["uiHints"] = ui_hints

The auto-derivation rule today:

Trigger Sets Used by
Plugin's group tuple contains "memory" or "tool" (centralized as _CONFIG_NODE_GROUPS = frozenset({"memory", "tool"})) uiHints.isConfigNode = True Frontend InputSection.tsx and OutputPanel.tsx — tells the panel that this node is auxiliary configuration and should inherit the parent's main inputs instead of showing direct upstream connections

Explicit always wins. A plugin that wants to opt out of an auto-derived flag declares it explicitly: ui_hints = {"isConfigNode": False}. The merge order (auto first, then dict.update with the plugin's declaration) means explicit values overwrite auto-derived ones.

Adding a new auto-derivation rule. Extend _derive_auto_ui_hints in services/plugin/base.py. The rule must be derivable from declared class attributes (group / kind / etc.) — never from runtime state. Add the new flag name to INodeUIHints in client/src/types/INodeProperties.ts and to the known set in server/tests/test_node_spec.py::test_ui_hints_only_carry_known_flags (the pytest invariant locks the flag set so unknown keys fail CI).

Params schema conventions

snake_case everywhere. Field names are the JSON Schema keys, the UI parameter keys, and the displayOptions.show reference keys. Keeping a single naming convention makes cross-references trivially correct.

  • No alias="camelName" on Field(...).
  • No populate_by_name=True in model_config.
  • No model_dump(by_alias=True) in handlers — call model_dump() or read typed attributes off the validated params object.
  • displayOptions.show["driver_field"] must match a Pydantic field name in the same Params class. The frontend's visibility evaluator looks up that exact key.

Example:

class ExampleParams(BaseModel):
    operation: Literal["send", "search"] = Field(default="send")
    recipient: str = Field(
        default="",
        description="Email recipient",
        json_schema_extra={"displayOptions": {"show": {"operation": ["send"]}}},
    )
    query: str = Field(
        default="",
        json_schema_extra={"displayOptions": {"show": {"operation": ["search"]}}},
    )
    model_config = ConfigDict(extra="ignore")

Option labels (the name shown in dropdowns) ride on json_schema_extra:

operation: Literal["send", "search"] = Field(
    default="send",
    json_schema_extra={"options": [
        {"name": "Send", "value": "send"},
        {"name": "Search", "value": "search"},
    ]},
)

If a user-facing input needs multi-line, a password mask, or a code editor, set those via json_schema_extra keys the adapter lifts into typeOptions: rows, password, editor, editorLanguage, dynamicOptions, loadOptionsMethod, numberStepSize, widget, accept.

Field grouping (collapsible collections)

Mark a field with json_schema_extra={"group": "<key>"} to nest it under a collapsible collection container in the parameter panel (same UX as an n8n "Options" accordion). Group membership is opt-in — plugins that don't declare any group render flat exactly like today.

class AIAgentParams(BaseModel):
    # Top-level fields (always visible)
    provider: ProviderRef = "openai"   # loader-driven (aiProviders), nodes/agent/_provider.py
    model: str = Field(default="")
    prompt: str = Field(default="", json_schema_extra={"rows": 4})
    system_message: Optional[str] = Field(default="")

    # "Options" group — collapsed by default, "Add Option" reveals them
    temperature: float = Field(
        default=0.7, ge=0.0, le=2.0,
        json_schema_extra={"group": "options"},
    )
    max_tokens: Optional[int] = Field(
        default=1000, ge=1, le=200000,
        json_schema_extra={"group": "options"},
    )

    # Class-level metadata (optional — title-cased defaults otherwise)
    model_config = ConfigDict(
        extra="ignore",
        json_schema_extra={
            "groups": {
                "options": {
                    "display_name": "Options",
                    "placeholder": "Add Option",
                },
            },
        },
    )

Adapter behaviour (client/src/adapters/nodeSpecToDescription.ts):

  • Fields with the same group key are collected into a single type: "collection" INodeProperty. The collection is positioned at the first child's slot in the original schema order; subsequent children slot into its options array.
  • Missing class-level groups[<key>] metadata falls back to display_name = titleCase(key) (e.g. "options" → "Options") and placeholder = f"Add {displayName.rstrip('s')}" (e.g. "Add Option").
  • Multiple groups per class are supported — just declare each key.

When to use it: cluster advanced / rarely-tuned knobs (temperature, max_tokens, thinking params) behind an "Add Option" button so the default panel stays small. Main-entry fields (provider, prompt, required inputs) stay at the top level.

Credentials vs. Params

api_key is never a declared Params field. Credentials live in the credentials DB via ApiKeyCredential / OAuthCredential subclasses; services/node_executor._inject_api_keys() resolves them at execution time and puts them in the raw parameters dict. Plugins that need the injected key read ctx.raw["_raw_parameters"]["api_key"] (stashed by BaseNode.execute before Pydantic validation strips it).

If you find yourself declaring an api_key: str = Field(...) on a Params class, stop: add an ApiKeyCredential subclass instead and wire it via the credentials = (...) tuple on the node class.

Multi-credential nodes

credentials is a sequence, and ctx.connection(id) is a lookup over it — so a node that talks to several vendors declares them all and selects at runtime from a parameter:

credentials = (OpenAICredential, ElevenLabsCredential, SarvamCredential)

@Operation("synthesize")
async def synthesize(self, ctx, params):
    async with ctx.connection(credential_id_for(params.provider)) as conn:
        ...

_make_connection_factory (base.py) precomputes an {id: class} dict; an id the node never declared raises RuntimeError synchronously, before any HTTP. A declared credential with no stored key fails later, at conn.credentials(), as an annotated PermissionError — which BaseNode.execute turns into a credential envelope plus a CloudEvents broadcast, so the Credentials modal lights up the right provider.

A multi-credential node MUST use imperative operations. The declarative routing= path resolves self.credentials[0] (BaseNode._run_operation in base.py), so a routed op would authenticate every provider with the first key in the tuple regardless of what the user picked. test_plugin_contract.py only asserts the tuple is non-empty, so nothing else catches it. nodes/speech/ has a test asserting neither of its nodes declares routing=.

Reference implementation: nodes/speech/ — the first multi-credential plugin in the repo. Its _config.credential_id(provider) reads the id from JSON, keeping the mapping declarative, and cross-plugin credential imports (from ..model._credentials import OpenAICredential) are idiomatic — nodes/sarvam/ already does the same.

Operations (@Operation)

A multi-op node declares multiple methods, each decorated with @Operation("name"). BaseNode._pick_operation reads parameters.operation to choose which to run.

@Operation("send", cost={"service": "googleGmail", "action": "send", "count": 1})
async def send(self, ctx: NodeContext, params: GmailParams) -> Any: ...

@Operation("search")
async def search(self, ctx: NodeContext, params: GmailParams) -> Any: ...

@Operation("read")
async def read(self, ctx: NodeContext, params: GmailParams) -> Any: ...

Single-op nodes use one method; parameters.operation can be omitted.

Declarative REST via Routing

For pure REST integrations, leave the op body empty and attach a Routing object:

@Operation("search", routing=Routing(
    request=RoutingRequest(
        method="GET",
        url="https://api.example.com/search",
        qs={"q": "={{params.query}}"},
        headers={"X-API-Key": "={{credentials.api_key}}"},
    ),
    output=RoutingOutput(
        post_receive=[PostReceiveAction(type="root_property", property="data.hits")],
    ),
))
async def search(self, ctx, params): pass  # body unused — routing handles it

Supported post_receive strategies: root_property, limit, filter, set.

Connection facade (Nango pattern)

Plugins never see tokens. ctx.connection(credential_id) returns an authed httpx-compatible client:

async with ctx.connection("brave_search") as conn:
    resp = await conn.get(url, params={"q": query})
    # X-Subscription-Token header auto-injected by Credential.inject()

401/403 responses trigger one refresh-and-retry transparently.

Credentials

Declarative credentials live in each node folder's _credentials.py (Wave 11.E.1) — same "one domain owns its own code" principle as _base.py and _inline.py helpers. Three base classes (stay in services/plugin/credential.py as infrastructure):

  • ApiKeyCredential — header / query / bearer injection.
  • OAuth2Credential — Authorization: Bearer <access_token> with auto-refresh via auth_service.get_oauth_tokens.
  • Credential — fully custom (override resolve() + inject()).

Validation probe: subclasses normally declare probe_url / probe_method / probe_json so the default _probe issues a probe HTTP request and reads the status code through _classify_status. When the provider has no cheap auth-gated endpoint (Perplexity's /v1/models returns 200 for any key including garbage; every other endpoint charges tokens), override _probe to return ProbeResult(valid=True) directly and let runtime calls surface the 401 — see nodes/search/perplexity_search/__init__.py for the canonical no-probe pattern. ProbeResult is exported from services.plugin for this override.

Auto-discovery rides on node-package import. When nodes/__init__.py:pkgutil.walk_packages imports a plugin module, that module's from ._credentials import XCredential statement imports the sibling _credentials.py, which triggers Credential.__init_subclass__ → writes to CREDENTIAL_REGISTRY before the plugin class is defined. The walker skips underscore-prefixed files, so _credentials.py is never double-imported. Contract invariant test_credentials_are_registered ensures every declared credential on a plugin resolves to a registered class.

Cards built from what was saved: a credential whose cards are the owner's own entries, not one fixed provider, overrides the async classmethod catalogue_entries(*, principal=None) (default []). get_credential_catalogue appends what every registered class returns, after the static providers, and those cards carry their own stored / connected. Shared card fields come from an _abstract template in credential_providers.json, read with CredentialRegistry.get_template. nodes/mcp/_credentials.py is the one user: one card per custom MCP connector (MCP Connectors).

Apps from what was saved: when a node's app is one the owner saved, not one of config/employee_apps.json's, the plugin registers a source with services.employees.apps.register_app_source(kind, source). source(principal) returns AppSpecs, and Connections.apps reads them with the file's, so the setup screen, Hire and the employee's card see them. Such a node declares app_field, the parameter that holds its app's id, so the card can tell two nodes of one type apart. nodes/mcp is the one user: each custom connector is an app.

Shipped credentials (Wave 11.E → E.1):

File Class(es) Auth Covers
nodes/google/_credentials.py GoogleCredential oauth2 gmail, calendar, drive, sheets, tasks, contacts, gmailReceive
nodes/location/_credentials.py GoogleMapsCredential api_key (query) gmaps_create / gmaps_locations / gmaps_nearby_places
nodes/twitter/_credentials.py TwitterCredential oauth2 twitterSend / twitterSearch / twitterUser / twitterReceive
nodes/telegram/_credentials.py TelegramCredential api_key telegramSend / telegramReceive
nodes/scraper/_credentials.py ApifyCredential / TikHubCredential api_key (bearer) apifyActor / tikhubAction (TikHub probes tikhub/user/get_user_info declaratively — see tikhub_service.md)
nodes/model/_credentials.py OpenAI / Anthropic / Gemini / OpenRouter / Groq / Cerebras / DeepSeek / Kimi / Mistral / Xai / Sarvam / Ollama / LMStudio / OpenAICompatible api_key One credential class per LLM provider, covering every agent-selectable provider and every standalone chat-model node (ls server/nodes/model/*_chat_model). Ollama / LM Studio store a local server URL; OpenAICompatibleCredential stores any number of named endpoints, each under its own openai_compatible:<slug> reference (RFC-0003); xAI is agent-selectable but has no standalone node; SarvamCredential also serves the speech / translate plugins.
nodes/search/<name>/__init__.py (inline) BraveSearch / Serper / Perplexity api_key single-use search nodes

This table is the Wave 11.E snapshot, not an inventory — later plugins (Stripe, Vercel, GitHub, Cloudflare, gcloud, AWS, WhatsApp, WhatsApp Business, Discord, Microsoft, ElevenLabs, Deepgram, DeepL, ...) each ship their own _credentials.py. Read the live set from len(services.plugin.credential.CREDENTIAL_REGISTRY).

GoogleCredential exposes a build_credentials() classmethod that returns a google.oauth2.credentials.Credentials — hand-off to googleapiclient.discovery.build(...) is unchanged from Wave 11.D.4.

Agents (aiAgent / chatAgent / the 13 SpecializedAgentBase subclasses) stay credentials = () because they are poly-provider — the user picks the provider at runtime via params.provider, so declaring any single credential would be misleading.

Shared agent helpers

Every agent plugin (ai_agent, chat_agent, and the 13 SpecializedAgentBase subclasses — 11 domain agents + 2 team leads) calls one helper:

from ._inline import prepare_agent_call

kwargs = await prepare_agent_call(
    node_id=ctx.node_id, node_type=self.type,
    parameters=params.model_dump(),
    context=ctx.raw, database=database,
    log_prefix=f"[{self.type}]",
)
response = await ai_service.execute_chat_agent(ctx.node_id, **kwargs)

prepare_agent_call wraps the shared edge-walker (services/plugin/edge_walker.py) + task context injection + auto-prompt fallback + team-lead teammate injection. Plugin-specific logic stays in the execute_op method.

Temporal per-node activities (Wave 11.F → F4.A wiring)

Every BaseNode subclass exposes cls.as_activity(), a Temporal @activity.defn-decorated callable with name node.{type}.v{version}. As of F4.A (commit 8261b05) these activities are wired into the orchestrator behind TEMPORAL_PER_TYPE_DISPATCH (default on; set it to false for rollback):

  • Flag OFF: orchestrator schedules legacy execute_node_activity (status quo since Wave 11; WS round-trip back to FastAPI).
  • Flag ON: orchestrator schedules f"node.{cls.type}.v{cls.version}". The per-type activity body runs the full pipeline (broadcast + pre-executed / disabled checks + parameter fetch + instance.execute()) via workflow_service.execute_node() — no WebSocket round-trip because the worker shares the FastAPI process.

TemporalWorkerManager._worker registers BOTH the legacy activity AND every per-type activity. With the default-on TEMPORAL_WORKER_POOL_ENABLED, main.py also starts a TemporalWorkerPool, and MachinaWorkflow._resolve_activity() routes each per-type activity to its plugin-declared cls.task_queue. Setting TEMPORAL_WORKER_POOL_ENABLED=false stops the pool and routes activities back to the manager's single default queue.

Execution routing is recorded in the run's input; changing environment settings does not redirect an already-running workflow. New controlled generations (execution_control_version=1) also freeze resolved agent-tool bindings and the plugin's timeout, heartbeat, retry, and queue declarations during payload preparation. Ordinary per-type tools use these policies and carry them through Continue-As-New. Existing histories retain their recorded policy decisions. A tool call outside a controlled generation (a manual Run) applies the declared timeout, heartbeat and retry too, but not the queue. The in-process executor does not enforce Temporal Activity policies.

Graph Activity starts currently honor plugin retry and queue declarations, while ordinary graph nodes retain generic 24-hour attempt / 2-minute heartbeat defaults. The existing Workspace-task override applies its declared timeout and heartbeat. The frozen v1 ordinary-agent-tool policy described above is stronger; do not assume the graph path applies every timeout declaration.

Cooperative Stop is owned by workflow admission gates before node, tool, model, polling, compaction, refresh, and child-start work. Admitted work finishes under its existing retries and retains its result/bookkeeping; Resume releases the existing continuation's next pending action. Already-admitted parallel work drains concurrently. Keep provider I/O in regular Activities, and add heartbeat progress recovery only when the operation actually supports it. A status heartbeat cannot resume an opaque subprocess or HTTP request. See Workflow control and Node creation: execution contract.

# Worker collection patterns (both supported).

# All per-type activities (no queue filter; what TemporalWorkerManager uses today):
from services.temporal.plugin_activities import collect_plugin_activities
activities = collect_plugin_activities()

# Filter by declared queue (what each TemporalWorkerPool worker uses):
ai_heavy = collect_plugin_activities(task_queue="ai-heavy")
worker = Worker(client, task_queue="ai-heavy", activities=ai_heavy, ...)

# Multi-queue pool (started by main.py when TEMPORAL_WORKER_POOL_ENABLED=true):
from services.temporal.worker import TemporalWorkerPool
pool = TemporalWorkerPool(client)  # defaults to all declared queues
await pool.start()

Temporal agent workflows (F4.B)

TEMPORAL_AGENT_WORKFLOW_ENABLED (default on; set it to false for rollback) flips agent dispatch from activity to child workflow. The AgentWorkflow class in services/temporal/agent_workflow.py orchestrates the agent loop:

AgentWorkflow.run(payload):
  loop until "final" or max_iterations:
    1. execute_activity("agent.execute_llm_step") -> kind + content/calls
    2. if kind == "tool_calls":
         for each call: execute_activity(f"node.{tool_type}.v{version}")
    3. execute_activity("agent.persist_turn")   # append memory per turn
    4. if compaction threshold: execute_activity("agent.compact_context")

The worker registers the agent.* activities alongside the per-type activities. The three shown above are the core model/persistence/compaction steps; the remainder cover payload preparation, progress and output persistence, tool/skill refresh, delegation lifecycle, and team finalization.

Native agent types: aiAgent, chatAgent, specialized agents (android_agent, browser_agent, coding_agent, web_agent, task_agent, social_agent, travel_agent, tool_agent, productivity_agent, payments_agent, consumer_agent, autonomous_agent), 2 team leads (orchestrator_agent, ai_employee).

browser_agent uses this same loop and a saved Browser tool. Its shared atomic creation recipe, direct Workspace tasks and private credential flow are described in node creation and Browser deployment. Distributed Browser Activities use their frozen owner's physical queue regardless of the worker pool switch; generic orchestration workers exclude them. The authoritative native type set is AGENT_WORKFLOW_TYPES in services/temporal/workflow.py.

Agents that stay as single activities: rlm_agent and claude_code_agent. Their internal session state (RLM REPL or Claude CLI --resume with stable cwd) remains inside one Activity. Cooperative Stop drains that whole Activity; it cannot stop between tools hidden inside that session.

Queue distribution (live count via distinct_task_queues() and len(_NODE_CLASS_REGISTRY)):

Queue Use case Default concurrency
ai-heavy LLM agent loops 4
rest-api Lightweight HTTP / Google / Twitter 50
machina-default Catch-all 20
android ADB / relay ops 10
messaging WhatsApp / Telegram 20
triggers-event Push-based triggers 100
triggers-poll Polling triggers (Gmail, etc.) 100
code-exec Python / JS / TS sandboxes 10
browser Installed Chrome/Edge/Chromium / browser-use / CDP 4

The current Browser plugin launches installed Chrome/Edge/Chromium in dedicated profiles rendered headless in the workspace UI by default, owns browser-use tool execution and the CDP live view, and offers Chrome for Testing only through explicit testing mode. See browser.md and browser_workspace.md; the retired browserHarness node is not a second active plugin.

Env overrides: TEMPORAL_<QUEUE>_CONCURRENCY (e.g. TEMPORAL_AI_HEAVY_CONCURRENCY=8).

Trigger registry auto-populate (Wave 11.D.11)

services/event_waiter.py:TRIGGER_REGISTRY + FILTER_BUILDERS are backfilled from plugin TriggerNode subclasses on first access. A plugin declaring event_type + build_filter auto-registers — no hand-edit of event_waiter.py required.

Hardcoded entries still win when present (authoritative), so plugin upgrades never silently replace hand-tuned filter behaviour.

Self-contained plugin folders

Some plugins are richer than a single BaseNode subclass — they own a long-lived service (a bot connection, a WebSocket bridge, an SDK session), their own credentials-modal WebSocket commands, custom event filtering, lifecycle hooks. Telegram is the reference shape.

Principle: every cross-cutting concern resolves to a generic registry that the consumer (router, broadcaster, event waiter, schema emitter) reads at dispatch time. Plugin packages register themselves into those registries from their package __init__.py. Nothing outside the plugin folder hardcodes the plugin's name.

Folder shape (Telegram reference)

server/nodes/telegram/
├── __init__.py          # imports + one register_* call per concern (no logic)
├── _credentials.py      # TelegramCredential (ApiKeyCredential)
├── _service.py          # TelegramService singleton (bot lifecycle)
├── _handlers.py         # WebSocket handlers + WS_HANDLERS dict
├── _filters.py          # build_telegram_filter (event_waiter filter)
├── _refresh.py          # refresh_telegram_status + precheck_telegram_trigger
├── _events.py           # typed CloudEvents factory + broadcast_telegram_status
├── _send.py             # perform_send / resolve_chat_id, shared by the node and the WS send command
├── telegram_send.py     # ActionNode, also an AI tool (usable_as_tool; ApprovalSpec: held while Ask first is on)
├── telegram_receive.py  # TriggerNode
├── icon.svg             # node icon for every node type in the folder
├── telegram.svg         # credential brand icon (Credential.get_icon_path)
└── meta.json            # palette colour

Underscore-prefixed files are package-private; the nodes walker skips them. The two non-underscore .py files are the plugin classes (one per node type) — same pattern as every other folder.

Cross-cutting registries (hand-curated below; grep -rn '^def register_' server/services server/core lists the live set, plus the node / group / provider / session-pool registration internals) — use only what your plugin needs

Concern Registry module Register from plugin via
Credentials-modal WebSocket commands (Connect / Disconnect / Send / Status / etc.) services.ws_handler_registry register_ws_handlers({type: handler, ...})
FastAPI HTTP router (OAuth callbacks, webhook receivers, etc.) services.ws_handler_registry register_router(router, name='<plugin>') — Wave 11.I; declare a _router.py exposing an APIRouter and call from __init__.py. Discovered at startup via services.ws_handler_registry.get_routers().
loadOptionsMethod async loader for a dynamic dropdown (json_schema_extra={"loadOptionsMethod": "..."}). A loader that lists one user's things reads the caller from current_load_options_principal(), never a user_id in its params (the client writes those) services.ws_handler_registry register_option_loader(method_name, fn)
OAuth callback path (/api/<provider>/callback) so services.oauth_utils.get_redirect_uri never cross-imports nodes/<plugin>/_oauth.py services.ws_handler_registry register_oauth_callback_path(provider, path)
A route a provider calls without a session cookie (Discord's signed interactions). AuthMiddleware lets the path and everything below it through, so the route must authenticate each request itself and fail closed services.ws_handler_registry register_public_ingress_path(path, name='<plugin>')
Trigger event-filter builder services.event_waiter register_filter_builder(node_type, fn)
Trigger pre-execution check (e.g. "bot not connected") services.event_waiter register_trigger_precheck(node_type, fn)
Service-status refresh (runs once, in a background task at startup; not on each WebSocket connect) services.status_broadcaster register_service_refresh(callback)
Per-node output schema (when not auto-derivable) services.node_output_schemas register_output_schema(node_type, ModelClass)
Master-Skill expander (how a masterSkill node expands into its enabled skills during edge walking) services.plugin.edge_walker register_master_skill_expander(fn) — registered by nodes.skill on package import.
Agent Context descriptor (node connected on input-context) services.plugin.edge_walker register_agent_context_builder(async_fn) — RFC-0002; the framework walks the edge but owns no knowledge of the descriptor's keys or thread-selection rules. Reference: nodes/context/_descriptor.py.
HTTP-webhook event source on the shared catch-all (/webhook/<path>) services.events.webhook register_webhook_source(source) — same instance for the same path is a no-op; a different source on an existing path raises.
Opt a trigger node type into the Wave 12 canary (Temporal) path services.deployment.canary_registry register_canary_trigger_type(node_type, cloudevent_type) — the CloudEvents type must match the producer's WorkflowEvent.type exactly; a diverging re-registration raises ValueError.
Polling-coroutine factory for a pull-based trigger (Gmail, Twitter) services.deployment.poll_registry register_poll_coroutine_factory(node_type, factory)
Send handler for one social platform behind the generic socialSend node services.plugin.social_provider_registry register_social_send_handler(platform, handler)
FastAPI-lifespan shutdown hook for plugin-owned long-lived state services.plugin.shutdown_hooks register_shutdown_hook(label, hook) — label surfaces in shutdown logs.
Service factory for the DI container (container.<name>() resolves to a plugin-owned service) services.plugin.service_factories register_service_factory(name, factory)
Short Terminal-UI log tag for a logger-name prefix (only when the nodes.<plugin> auto-rule yields an unwanted tag) core.logging register_log_source_tag(prefix, tag)
Callback fired after a conversation durably saves (RFC-0002 Context live-view) services.agent_context.listeners register_conversation_listener(listener) — keyword-args only; a listener can never fail a save.
Long-lived process supervisor (WhatsApp bridge, the JS executor sidecar on bun, Discord gateway) services._supervisor register_supervisor(supervisor) — idempotent per supervisor.label; a label collision raises ValueError.

All accept idempotent re-imports (same callable / class for the same key is a no-op; conflicts raise ValueError).

Plugins use only the registries they need. Telegram registers no router; Stripe is webhook-driven, with no filter or precheck; Android registers a router. There is no "register every hook" rule — read a plugin's __init__.py for what it actually registers.

Telegram __init__.py (canonical wiring)

# server/nodes/telegram/__init__.py (abridged: docstring, re-exports and __all__ omitted)
from services.deployment.canary_registry import register_canary_trigger_type
from services.event_waiter import register_filter_builder, register_trigger_precheck
from services.node_output_schemas import register_output_schema
from services.plugin.shutdown_hooks import register_shutdown_hook
from services.status_broadcaster import register_service_refresh
from services.ws_handler_registry import register_ws_handlers

from ._credentials import TelegramCredential
from ._filters import build_telegram_filter
from ._handlers import WS_HANDLERS
from ._refresh import precheck_telegram_trigger, refresh_telegram_status
from ._service import TelegramService, get_telegram_service

# Plugin classes (importing them runs __init_subclass__ for the node registry)
from .telegram_receive import TelegramReceiveNode, TelegramReceiveOutput
from .telegram_send import TelegramSendNode, TelegramSendOutput

# --- self-registration on import -------------------------------------------
register_ws_handlers(WS_HANDLERS)
register_filter_builder("telegramReceive", build_telegram_filter)
register_trigger_precheck("telegramReceive", precheck_telegram_trigger)
register_service_refresh(refresh_telegram_status)
register_output_schema("telegramReceive", TelegramReceiveOutput)
register_output_schema("telegramSend", TelegramSendOutput)
register_canary_trigger_type(TelegramReceiveNode.type, "com.opencompany.telegram.message.received")


async def _shutdown_telegram() -> None:
    # Release the single getUpdates slot before the process exits.
    service = get_telegram_service()
    if service.connected:
        await service.disconnect()


register_shutdown_hook("telegram", _shutdown_telegram)

That's the entire wiring. Adding telegram-style cross-cutting code to a new plugin folder takes one register call per concern; the consumer never learns the plugin's name.

How consumers consult the registries

Each consumer hits its registry at dispatch time, not at module load, so plugins registered later still work:

# routers/websocket.py — central WS dispatcher
from services.ws_handler_registry import get_ws_handlers

def _resolve_handler(msg_type):
    return MESSAGE_HANDLERS.get(msg_type) or get_ws_handlers().get(msg_type)

# services/handlers/triggers.py — generic trigger handler
precheck_error = await event_waiter.run_trigger_precheck(node_type, parameters)
if precheck_error:
    return error_envelope(precheck_error)
waiter = await event_waiter.register(node_type, node_id, parameters)

# services/status_broadcaster.py — refresh_all_services (runs once at
# lifespan startup, Wave 11.I; no per-plugin knowledge remains here)
async with asyncio.TaskGroup() as tg:
    for callback in list(_SERVICE_REFRESH_CALLBACKS):
        tg.create_task(callback(self))

When does a plugin need the full self-contained shape?

Most plugins are a single BaseNode subclass — that's the right default. Promote to the self-contained folder shape only when the plugin owns one of:

  • A long-lived stateful object (bot / device / session / subprocess).
  • Credentials-modal lifecycle commands beyond the standard Save / Load / Delete (e.g. Connect / Disconnect).
  • Trigger pre-checks that need plugin-specific service state.
  • A status refresh that runs on WebSocket connect.
  • A duplicate Output Pydantic class that the central node_output_schemas.NODE_OUTPUT_SCHEMAS would otherwise pin.

If none of those apply: a single <name>/__init__.py folder under the right group is the whole node. Don't create _service.py / _handlers.py / etc. just because telegram has them.

Wire format is the contract — not module paths

The frontend identifies plugin commands by WebSocket message type strings (telegram_connect, telegram_status, …). Moving the handler implementation between Python files is invisible to the frontend so long as the registered keys stay the same. The server/config/credential_providers.json declarative config — served to the frontend via handle_get_credential_catalogue and consumed by useCatalogueQuery — is likewise stable across backend reorganisations. (The pre-Wave-13 providers.tsx static fallback in the credentials component folder no longer exists; the server catalogue is the single source of truth for the credentials panel.)

This is why the telegram refactor changed zero frontend code despite moving 754 lines out of the old telegram_service.py service module.

Folder layout

server/
├── nodes/                        # One self-contained folder per plugin (Wave 11.H)
│   ├── __init__.py              # pkgutil.walk_packages discovery
│   ├── groups.py                # Palette group metadata
│   ├── agent/                   # AI agents (aiAgent, chatAgent, SpecializedAgentBase
│   │   │                        # subclasses, rlm / claude_code / codex variants)
│   │   ├── _handles.py          # Shared handle topology helpers
│   │   ├── _inline.py           # prepare_agent_call()
│   │   ├── _provider.py         # ProviderRef: the loader-driven provider field every agent shares
│   │   ├── _specialized.py      # SpecializedAgentBase
│   │   └── <agent>/__init__.py  # one folder per agent
│   ├── model/                   # AI chat models (one per provider except xAI, plus openaiCompatibleChatModel for named endpoints)
│   │   ├── _base.py             # ChatModelBase + ChatModelParams/Output
│   │   └── <provider>_chat_model/__init__.py
│   ├── android/                 # 16 Android service nodes
│   │   ├── _base.py             # AndroidServiceBase
│   │   └── <service>/__init__.py
│   ├── code/                    # python/js/ts executors
│   │   ├── _base.py             # CodeExecutorBase
│   │   ├── _nodejs.py           # Shared NodeJSClient singleton
│   │   └── <lang>_executor/__init__.py
│   ├── filesystem/              # file_read / file_modify / shell / fs_search / gallery
│   │   ├── _backend.py          # Native workspace-contained filesystem helper
│   │   └── <op>/__init__.py
│   ├── document/                # http_scraper / parser / chunker / embedding / vector / file_downloader
│   │   └── <stage>/__init__.py
│   ├── google/                  # gmail / calendar / drive / sheets / tasks / contacts
│   ├── proxy/                   # proxy_request / proxy_config / proxy_status
│   │   └── _usage.py            # Shared track_proxy_usage
│   ├── search/                  # brave / serper / perplexity / duckduckgo
│   ├── scraper/                 # apify / crawlee / tikhub_action (SDK-backed, reflective resource.method dispatch)
│   ├── tool/                    # calculator / currentTime / taskManager / writeTodos / agent_builder / canvas / data_source / simple_memory
│   ├── trigger/                 # webhookTrigger / chatTrigger / taskTrigger
│   ├── workflow/                # start
│   ├── scheduler/               # cronScheduler / timer
│   ├── whatsapp/                # whatsappSend / whatsappDb / whatsappReceive
│   ├── telegram/                # telegramSend / telegramReceive
│   ├── twitter/                 # twitterSend / search / user / receive
│   ├── email/                   # emailSend / emailRead / emailReceive
│   ├── chat/                    # chatSend / chatHistory
│   ├── social/                  # socialSend / socialReceive
│   ├── browser/                 # browser (managed Chrome, browser-use CLI, live CDP view)
│   ├── utility/                 # httpRequest / webhookResponse / console / team_monitor / process_manager
│   ├── text/                    # textGenerator / fileHandler
│   ├── location/                # gmaps_create / gmaps_locations / gmaps_nearby_places
│   ├── skill/                   # masterSkill (+ _expander.py; skill/simple_memory is an import shim —
│   │                            # the canonical simpleMemory plugin is nodes/tool/simple_memory/)
│   └── ...                      # context / speech / translate / vision / discord / microsoft /
│                                # whatsapp_business / stripe / vercel / github / cloudflare / gcloud / aws —
│                                # `ls server/nodes` is the inventory; each group folder owns its
│                                # own _credentials.py (Wave 11.E.1), no central credentials package.
└── services/
    ├── plugin/                  # Plugin runtime
    │   ├── base.py              # BaseNode
    │   ├── action.py / trigger.py / tool.py
    │   ├── operation.py         # @Operation decorator + collector
    │   ├── routing.py           # Declarative REST DSL
    │   ├── credential.py        # Credential base classes
    │   ├── connection.py        # Nango-style authed httpx wrapper
    │   ├── context.py           # NodeContext dataclass
    │   ├── scaling.py           # TaskQueue / RetryPolicy
    │   ├── edge_walker.py       # collect_agent_connections / collect_teammate_connections
    │   └── interceptor.py       # Interceptor ABC + chain
    ├── node_registry.py         # register_node + _NODE_CLASS_REGISTRY + helpers
    ├── node_spec.py             # NodeSpec envelope emission
    └── temporal/
        ├── plugin_activities.py # collect_plugin_activities / distinct_task_queues
        └── worker.py            # TemporalWorkerManager + TemporalWorkerPool

Contract invariants

server/tests/test_plugin_contract.py — contract invariants enforced on every CI run (live count via pytest --collect-only). Examples:

  • Non-empty type / display_name / group per class.
  • Params + Output must be Pydantic BaseModel subclasses.
  • Every declared credentials entry resolves to a registered class.
  • Operation names unique per class.
  • routing=... requires credentials declared.
  • task_queue ∈ TaskQueue.ALL.
  • Every ToolNode JSON schema has no $defs / $ref (LLM-compat).
  • Every event-mode TriggerNode declares event_type.
  • Fast-path covers every AI-tool-usable plugin (no hardcoded schema dependency).
  • Trigger registry auto-populates for every event-mode plugin.

All Wave 10 invariants in test_node_spec.py still run; Wave 11 invariants in test_plugin_self_containment.py. Live total via pytest --collect-only.

Canonical principles

  1. One plugin = one authoring location. Adding a new node never edits multiple files. The filesystem location matches the palette group.
  2. Backend is SSOT. Node declaration, visual metadata, handlers, schemas, credentials, icons — one authoring location.
  3. No frontend fallbacks. Missing data surfaces as a visible gap so the backend bug is obvious, not masked.
  4. Stateful services stay in services/. AIService, MapsService, NodeJSClient, etc. Plugins call them; never inline them.
  5. Per-handler helpers move WITH the handler. _format_console_output, _extract_text, … inline into the plugin file. Cross-handler helpers (like edge_walker) extract to shared modules.
  6. Container injection. Plugins do from core.container import container; svc = container.X() — never instantiate services directly.
  7. Pydantic for everything. Params, Output, Credential config, Routing — all Pydantic. Validation at the boundary, typed at the core.

Migration history (for future readers)

  • Wave 6 — Output schemas on backend.
  • Wave 10 — Input schemas + metadata on backend; @register_node decorator (dict form); filesystem-as-catalog.
  • Wave 11.A — services/plugin/ package with BaseNode hierarchy.
  • Wave 11.B — Reference migrations (5 nodes across all kinds).
  • Wave 11.B.1 — Unified tool dispatch via plugin fast-path.
  • Wave 11.C — 111/111 nodes migrated across 5 batches; folder layout mirrors palette groups.
  • Wave 11.D.0 — edge_walker extracted to services/plugin/.
  • Wave 11.D.1-6 — Handler bodies inlined into plugins (trivial wrappers, code executors, HTTP/proxy, polling triggers, agents).
  • Wave 11.D.4 — Google Workspace (gmail / calendar / drive / sheets / tasks / contacts) inlined under nodes/google/, shared _base.py + _gmail.py helpers.
  • Wave 11.D.7 — Document pipeline (httpScraper, fileDownloader, documentParser, textChunker, embeddingGenerator, vectorStore) inlined under nodes/document/.
  • Wave 11.D.8 — Twitter / Crawlee / Apify inlined. Twitter shares nodes/twitter/_base.py for client + XDK helpers.
  • Wave 11.D.9 — WhatsApp + Social inlined into nodes/whatsapp/_base.py and nodes/social/_base.py (full bodies, RPC dispatch via services.whatsapp_service; renamed from the misnamed whatsapp.py router in Wave 11.E.2 since it was never an APIRouter, and moved again into nodes/whatsapp/_service.py in Wave 11.I).
  • Wave 11.D.10 — utility.py split across 12 plugin files (maps, text, workflow start, timer, cron, console, team monitor, chat).
  • Wave 11.D.11 — Auto-populate trigger registries.
  • Wave 11.D.12 — Fast-path contract invariants.
  • Wave 11.D.13 — Sunset empty bulk files + dead dispatch.
  • Wave 11.F — Per-plugin Temporal activities (BaseNode.as_activity())
    • TemporalWorkerPool class.
  • F4.A — Orchestrator wired to per-type dispatch behind TEMPORAL_PER_TYPE_DISPATCH flag (commit 8261b05). Closes the Wave 11.F orchestrator gap.
  • F4.B — AgentWorkflow child workflow + 3 agent activities behind TEMPORAL_AGENT_WORKFLOW_ENABLED flag (commit a4d009e). Tool calls inside AI agents become per-type activities.
  • Wave 11.E — Declarative credentials: 25 Credential subclasses at the time (GoogleCredential + GoogleMapsCredential + TwitterCredential + TelegramCredential + ApifyCredential + 12 LLM providers + 3 inline search credentials + Stripe / Vercel / GitHub / Cloudflare / WhatsApp); 29 plugins declared credentials = (...). Today the live numbers are len(CREDENTIAL_REGISTRY) (36) and 56 node types with a non-empty credentials tuple (late September 2026). Agents stay poly-provider (empty tuple).
  • Wave 11.E.1 — Modularised credentials into per-domain nodes/<group>/_credentials.py files. server/credentials/ directory deleted; auto-discovery rides on node-package import.
  • Wave 11.E.2 — Dead-code sweep: fixed 2 broken agent imports, stripped 13 dead dispatch branches in tools.py, deleted duplicate handlers/proxy.py, moved the misnamed whatsapp.py router → whatsapp_service.py under services (now nodes/whatsapp/_service.py since Wave 11.I), dedup'd TRIGGER_NODE_TYPES.
  • Wave 11.E.3 — Inlined the last per-domain handler bodies into plugins. Deleted 8 fully-orphan handler files (search, code, telegram, http, filesystem, email, process, todo) and 4 still-referenced ones (browser, android, claude_code, rlm) by inlining into their plugins. Split handlers/ai.py 4 ways: handle_ai_chat_model → ChatModelBase.chat, handle_simple_memory → SimpleMemoryNode.read, handle_ai_agent / handle_chat_agent → deleted entirely. tools.py:_execute_delegated_agent now looks up the child agent's plugin class via services.node_registry.get_node_class(node_type), builds NodeContext.from_legacy(...), and calls instance.execute(node_id, params, ctx) directly — no handler shell in the path.
  • Wave 11.E.4 — Relocated tools.py movables: proxyConfig 10-op matrix → nodes/proxy/proxy_config.execute_proxy_config (shared by the plugin's dispatch op and the AI-tool branch in tools.py); Android AI-tool dispatch (toolkit + direct service) → nodes/android/_base.{execute_android_toolkit, execute_android_service_tool} with a single canonical SERVICE_ID_MAP and a shared _execute_with_broadcast helper (previously duplicated in tools.py). tools.py from 1,255 → 821 LOC. (execute_android_toolkit has since been removed along with the androidTool aggregator node; only execute_android_service_tool remains.)
  • Wave 11.G — Nodes cookbook (server/nodes/README.md) + CLAUDE.md plugin section + this file refreshed to match shipped state.
  • Wave 11.H — Self-contained plugin folders. Seven generic registries replace per-plugin hardcoding in core services: services.ws_handler_registry.register_ws_handlers (WebSocket commands), services.ws_handler_registry.register_router (FastAPI routers — sibling concern in the same file as register_ws_handlers, added Wave 11.I), event_waiter.register_filter_builder (event filters), event_waiter.register_trigger_precheck (trigger pre-execution checks), status_broadcaster.register_service_refresh (service-status refresh callbacks), node_output_schemas.register_output_schema (output schemas).
  • Wave 11.I — Eight more plugin domains migrated to the self-contained pattern: WhatsApp, Twitter, Google Workspace, Android, Browser, Email, Code (Claude Code), and the credential validation scaffold (Credential.validate + Credential._probe) for Maps / Apify / Ollama / LM Studio. routers/websocket.py shrunk by ~808 LOC; three plugin routers (twitter / google / android) moved into nodes/<plugin>/_router.py and mount via the plugin-router loop in main.py. tests/test_plugin_self_containment.py locks the contract with 10 invariant classes (forbidden-imports / no-router-outside-nodes / per-plugin self-registration / registry-API sanity / stale-paths-absent / main.py-does-not-mount / WS_HANDLERS-non-empty + plugin-folder-has-node-file / typed-event-factories / package-imports-cleanly; live count via grep -c '^class Test' server/tests/test_plugin_self_containment.py).
  • Wave 12 — Generalized event framework (services/events/). Adds WorkflowEvent (CloudEvents v1.0 envelope, in-house Pydantic), EventSource hierarchy (PushEventSource / PollingEventSource / DaemonEventSource / WebhookSource / WebhookTriggerNode), a verifier registry (Stripe / GitHub / Standard Webhooks / generic HMAC), and three wiring helpers (make_lifecycle_handlers, make_status_refresh, run_cli_command). Future event-source plugins drop to ≈150 executable lines. Stripe is the reference implementation; Phase 2-4 migrate the existing polling and daemon triggers onto the framework. Telegram is the reference implementation: ~870 lines of telegram-specific code moved out of the old telegram_service.py service module (deleted), routers/websocket.py (7 inline handlers removed), services/event_waiter.py (build_telegram_filter + hardcoded registry entry removed), services/status_broadcaster.py (_refresh_telegram_status removed), services/handlers/triggers.py (hardcoded if node_type == 'telegramReceive' branch removed), services/node_output_schemas.py (duplicate TelegramReceiveOutput class removed) — all relocated to nodes/telegram/. Wire-format unchanged → zero frontend changes. Frontend identifies plugin commands by WebSocket message type strings, not Python module paths.

services/handlers/ is now 4 files / ~1,240 LOC (down from 16 files / 12,800 LOC; google_auth.py moved to nodes/google/_auth_helper.py in Wave 11.I commit D; wc -l server/services/handlers/*.py for the live figure):

File LOC Purpose
tools.py ~1,024 AI-tool dispatcher, plugin fast-path, agent delegation infrastructure (shared _delegated_tasks / _delegation_results state).
triggers.py ~123 Generic event-trigger handler for polling triggers (gmailReceive, twitterReceive, etc.).
todo.py ~75 TaskManager / writeTodos invocation surface for AI tool nodes.
__init__.py ~19 Package docstring; nothing imports from services.handlers at package level.

Every domain owns its own code under nodes/<group>/ — plugin file + optional _base.py / _inline.py / _credentials.py siblings. No handler shells, no central credential registry, no cross-domain reach.

Wave 12 — Generalized event framework (services/events/)

Wave 11.H proved the self-contained-folder pattern. Wave 12 takes the next step: stop re-implementing the same event-source plumbing in every folder. The new package server/services/events/ provides the shared base classes that every trigger / daemon / signed-webhook plugin builds on top of.

Why

Pre-framework, every event-source plugin re-wrote the same boilerplate:

  • Polling loop frame duplicated verbatim across gmail_receive, email_receive, twitter_receive (sleep → poll → diff baseline → dispatch).
  • Subprocess supervision had no shared base — telegram (SDK loop), whatsapp (Go RPC), stripe (CLI subprocess) each owned their singleton.
  • HMAC signature verification was about to be re-implemented per signed-webhook integration (Stripe, GitHub, Slack, Standard Webhooks / Svix providers).
  • Lifecycle WebSocket handlers (connect / disconnect / reconnect / status) were ~25 LOC of identical boilerplate per plugin.
  • Status-refresh callback (auto-reconnect on WS-client connect) was another ~12 LOC of identical boilerplate per plugin.
  • CLI invocation (find binary on PATH, inject API key, subprocess with timeout, parse JSON, uniform error envelope) was a copy-paste target.

Wave 12 absorbs all of this into framework code. New event-source plugins drop to ~150 executable lines (vs ~600+ pre-framework).

Public surface

from services.events import (
    # Envelope
    WorkflowEvent,                # CloudEvents v1.0 model (in-house)

    # EventSource hierarchy
    EventSource,                  # ABC: start / stop / status / emit
    PushEventSource,              #   external code calls receive()
    PollingEventSource,           #   poll_once() at intervals
    DaemonEventSource,            #   ProcessService-supervised subprocess
    WebhookSource,                #   HTTP POST to /webhook/{path}
    BaseTriggerParams,            # Pydantic base for trigger Params
    WebhookTriggerNode,           # TriggerNode bound to a WebhookSource

    # Webhook signature verifiers
    WebhookVerifier,              # ABC
    StripeVerifier,               # t=,v1=,HMAC-SHA256
    GitHubVerifier,               # X-Hub-Signature-256
    StandardWebhooksVerifier,     # Svix scheme (id.timestamp.body)
    HmacVerifier,                 # Generic single-header HMAC fallback

    # Wiring helpers
    register_webhook_source,      # WEBHOOK_SOURCES[path] = source
    make_lifecycle_handlers,      # connect/disconnect/reconnect/status WS dict
    make_status_refresh,          # register_service_refresh callback factory
    run_cli_command,              # subprocess + credential + JSON parse
)

Source taxonomy

Modality-axis hierarchy aligned with Apache Camel EIP and n8n trigger modes:

EventSource (abstract)
├── PushEventSource         events arrive via external write (HTTP, RPC, SSE)
│   └── WebhookSource       HTTP POST to /webhook/{path}
├── PollingEventSource      sleep → poll_once → emit; framework owns the loop
└── DaemonEventSource       long-lived subprocess via ProcessService;
                            tail stdout/stderr; parse_line() → events

Cron / scheduled events are Temporal Schedules (created by the deployment manager via services/temporal/schedules.py; the APScheduler path was retired in Wave 15.2) — they don't need this base. Internal in-process events go through event_waiter.dispatch directly.

Unified envelope (WorkflowEvent)

Mirrors CloudEvents v1.0 verbatim (spec) plus three OpenCompany routing extras (workflow_id, trigger_node_id, correlation_id). Field set: specversion / id / source / type / time / subject / datacontenttype / dataschema / data plus the extras.

WorkflowEvent(
    id=payload["id"],                                # provider's event id (replay safety)
    source="stripe://acct_test",                     # URI: scheme://provider/account
    type="com.opencompany.stripe.event.received",    # reverse-DNS event type
    time=datetime.fromtimestamp(payload["created"], tz=timezone.utc),
    subject=payload.get("type"),                     # the provider's own type, "charge.succeeded"
    data=shape_stripe_event(payload),
)

A deployed trigger listens for exactly one CloudEvents type (the string register_canary_trigger_type records), so a provider with many event types sends them all under one type and carries its own type in subject and data, where the trigger's filter reads it (nodes/stripe/_events.py).

WorkflowEvent.matches_type(pattern) does CloudEvents-style glob matching: "all" / "" matches everything, "foo.*" matches "foo.X" and "foo.X.Y", exact strings match exactly.

from_legacy(event_type, payload) wraps pre-framework Dict dispatches as a back-compat shim — every existing trigger keeps working untouched.

WebhookTriggerNode — the canonical TriggerNode base

Subclass for any signed-webhook trigger. Plugin declares only what differs from the generic shape:

from services.events import (
    BaseTriggerParams, WebhookTriggerNode, WorkflowEvent,
)
from services.events.envelope import event_type_matches

class MyParams(BaseTriggerParams):
    livemode_filter: Literal["all", "test", "live"] = "all"

class MyReceiveNode(WebhookTriggerNode):
    type = "myReceive"
    display_name = "My Receive"
    group = ("myprovider", "trigger")
    handles = (...,)
    credentials = (MyCredential,)

    webhook_source = MyWebhookSource          # required: which source feeds events
    event_type = MY_EVENT_TYPE                 # the type MyWebhookSource.shape emits
    Params = MyParams
    Output = MyOutput

    async def _check_precondition(self) -> Optional[str]:
        from ._source import get_listen_source
        return None if get_listen_source()._started else "Daemon not running"

    def build_filter(self, params):            # both callers pass the envelope's data
        pattern = params.event_type_filter or "all"

        def matches(event):
            data = event.data if isinstance(event, WorkflowEvent) else event
            if not isinstance(data, dict):
                return False
            if not event_type_matches(str(data.get("event_type") or ""), pattern):
                return False
            return params.livemode_filter == "all" or (
                bool(data.get("livemode")) is (params.livemode_filter == "live")
            )

        return matches

    def shape_output(self, event: WorkflowEvent) -> Dict:
        return event.data                      # shaped by the source, as the deployed run sees it

WebhookTriggerNode provides:

  • event_type derived from webhook_source.type automatically. It is the canvas-Run waiter key, so set it yourself when shape returns envelopes of another type, or event_waiter.dispatch matches no waiter (Stripe sets STRIPE_EVENT_RECEIVED_TYPE).
  • build_filter combining CloudEvents type-glob + optional _extra_filter. Override it to read the payload instead. Both callers hand the filter the envelope's data, not the envelope: the event waiter on a canvas Run, and evaluate_trigger_filter_activity on a deployed listener. The base rebuilds a WorkflowEvent from that dict, which raises unless the data happens to carry source and type; a waiter logs the error and stays unresolved, and a deployed listener fails open and ignores the filter. StripeReceiveNode overrides it; the WhatsApp Business triggers do not, so a deployed one admits every event whatever its event_type_filter.
  • execute() with the _check_precondition short-circuit, then shape_output on the resolved event (the waiter resolves with data, which _as_event wraps back into an envelope). A deployed run receives event.data verbatim and never calls shape_output, so shape the payload in the source and let shape_output return event.data, or Run and deploy disagree about the fields.
  • The @Operation("wait") stub.

A trigger whose events need something running (Stripe's stripe listen daemon) starts it from the TriggerNode.prepare_deployment classmethod, which the deployment manager calls for every trigger it arms, at Start and at the boot re-arm. Return quickly and schedule slow work; a raise is logged and the trigger is armed anyway.

WebhookSource — HTTP receiver

Plugin pairs the trigger with a WebhookSource that owns signature verification + payload shaping:

from services.events import StripeVerifier, WebhookSource, WorkflowEvent

class StripeWebhookSource(WebhookSource):
    type = "stripe.webhook"
    path = "stripe"                             # /webhook/stripe
    verifier = StripeVerifier
    secret_field = "stripe_webhook_secret"
    credential = StripeCredential

    async def shape(self, request, body, payload) -> WorkflowEvent:
        data = shape_stripe_event(payload)          # the trigger's output fields
        return stripe_event_received(               # type: com.opencompany.stripe.event.received
            data, event_id=data["event_id"], account=data["account"], time=...,
        )

    async def handle(self, request):
        event = await super().handle(request)       # verify, shape, wake the in-process waiter
        await emit_stripe_event(event)              # dispatch.emit: deployed listeners
        return event

The shared dispatch path lives in routers/webhook.py — it consults WEBHOOK_SOURCES, runs the verifier, calls shape(), dispatches via event_waiter. No plugin name is hardcoded in core. That reaches a canvas Run, and a deploy only when it runs without Temporal. A trigger that deploys on Temporal also needs register_canary_trigger_type and a dispatch.emit of each envelope, as StripeWebhookSource.handle does above.

DaemonEventSource — supervised subprocess driver

For plugins that wrap a long-lived CLI tool or SDK loop (the Stripe CLI's stripe listen; one-shot CLI wrappers such as GitHub, Vercel, Cloudflare and gcloud call run_cli_command instead). Delegates lifecycle to ProcessService (battle-tested PATHEXT-aware launching, kill_tree cleanup, log capture, Terminal-tab broadcast). The base subscribes to ProcessService's per-line callback hook (line_handler), so plugins just provide the parser:

import shlex
from services.events import DaemonEventSource, WorkflowEvent

class StripeListenSource(DaemonEventSource):
    type = "stripe.listen"
    process_name = "stripe-listen"
    binary_name = ""                  # see "binary_name" note below
    workflow_namespace = "_stripe"
    install_hint = "https://stripe.com/docs/stripe-cli#install"
    credential = StripeCredential

    def build_command(self, secrets: Dict) -> str:
        # `shlex.quote` the binary so the path round-trips through
        # ProcessService's POSIX-mode `shlex.split` unchanged.
        binary = shlex.quote(str(stripe_cli_path() or "stripe"))
        return f"{binary} listen --forward-to ... --print-secret"

    async def has_credential(self) -> bool:
        # Override the default ``secrets["api_key"]`` gate when auth lives
        # outside OpenCompany (e.g. the CLI's own ~/.config/stripe/config.toml).
        return is_logged_in()

    def parse_line(self, stream: str, line: str) -> Optional[WorkflowEvent]:
        # called per-line for both stdout and stderr
        if stream == "stderr" and (m := WHSEC_RE.search(line)):
            asyncio.create_task(self._persist_secret(m.group(0)))
        return None

The base provides start() / stop() / restart() / status() / lifecycle locking / pre-flight shutil.which check (skip via binary_name = "" if the plugin resolves the binary itself).

Output ingestion: DaemonEventSource registers self._on_line as the line_handler callback on ProcessService.start(). ProcessService runs the single stream.readline() loop per stdout/stderr; on each decoded line it writes the log file, broadcasts to the Terminal tab, and invokes the callback — which calls parse_line(stream, line). No log-file tailing.

Credential gate: start() consults await self.has_credential() before spawning. Default implementation tests secrets["api_key"]; subclasses override for non-api-key auth (Stripe → is_logged_in()).

Webhook verifiers

Drop-in HMAC schemes covering the major providers:

Class Header Algorithm Used by
StripeVerifier Stripe-Signature: t=…,v1=… HMAC-SHA256 over t.body Stripe
StandardWebhooksVerifier webhook-id / webhook-timestamp / webhook-signature HMAC-SHA256 base64 over id.ts.body; a webhook-timestamp more than 5 minutes from now is refused (the spec's replay window) Dodo Payments (dodoPaymentsReceive); also fits Svix-backed providers (Resend, Clerk, Loops, …)
GitHubVerifier X-Hub-Signature-256: sha256=… HMAC-SHA256 over body GitHub
HmacVerifier configurable header + prefix HMAC-SHA256 over body generic fallback

Each verifier raises ValueError on mismatch; WebhookSource.handle catches it and returns HTTP 400. When a verifier is declared but no signing secret resolves, handle fails closed: HTTP 503 with Retry-After: 5 (the provider retries the delivery once the secret lands). The legacy generic /webhook/{path} route used by webhookTrigger is unaffected.

Wiring helpers

Two factory functions collapse the per-plugin __init__.py boilerplate to four lines:

# nodes/stripe/_handlers.py
from services.events import make_lifecycle_handlers, run_cli_command
from ._source import get_listen_source

WS_HANDLERS = make_lifecycle_handlers(
    prefix="stripe",
    source=get_listen_source(),
    extra={"stripe_trigger": handle_stripe_trigger},  # plugin-specific extras
)
# → registers stripe_connect / stripe_disconnect / stripe_reconnect /
#   stripe_status from the source's start/stop/restart/status methods +
#   the stripe_trigger handler the plugin owns.

# nodes/stripe/__init__.py
register_service_refresh(make_status_refresh(
    get_listen_source(),
    status_key="stripe",
    broadcast_type="stripe_status",
))
# → auto-reconnect on WS-client connect + mirror status into
#   broadcaster._status["stripe"] + broadcast.

run_cli_command — generic CLI invocation

Used by ActionNodes that wrap a CLI tool. Resolves the binary on PATH, optionally injects the credential's api_key via the convention flag (--api-key by default), runs subprocess with timeout, parses stdout as JSON, returns a uniform envelope:

from services.events import run_cli_command

result = await run_cli_command(
    binary="stripe",
    argv=["customers", "create", "--email", "[email protected]"],
    credential=StripeCredential,
)
# {"success": bool, "result": parsed-or-None, "stdout": str,
#  "stderr": str, "error": str-or-None}

Stripe — reference implementation

The Stripe plugin (server/nodes/stripe/) is the canonical Wave 12 example: 540 LOC total / 258 executable, supervising a CLI daemon, verifying signed webhooks, exposing both a TriggerNode (stripeReceive) and a dual-purpose ActionNode + AI tool (stripeAction). See stripe_service.md for the per-file walkthrough.

CLI-managed auth pattern

Some plugins delegate auth to an external CLI tool that runs its own OAuth flow and persists tokens in its own config file (Stripe → ~/.config/stripe/config.toml; future gh auth login → ~/.config/gh/hosts.yml; gcloud auth login → ~/.config/gcloud/...). Three reuse points let these plugins ship without any node-specific code in the frontend or in core services:

  1. Marker-token write via the existing auth_service.store_oauth_tokens API. Plugin writes synthetic strings (e.g. "cli-managed") on login completion. The catalogue's per-provider stored flag comes from provider_connection_state in services/credential_registry.py (called by handle_get_credential_catalogue and by the Normal-mode employee summaries). It checks, in order: a declarative stored_check, then status_hook (auth_service.get_oauth_tokens(status_hook) is not None — identical to Google's OAuth-callback path), then the provider kind (apiKey / oauth), then connected_check. The synthetic tokens exist purely to flip that existence check; the CLI owns the real auth.

  2. Generic credential_catalogue_updated broadcast. The plugin emits this event after every state change. The frontend's existing handler in WebSocketContext.tsx (case 'credential_catalogue_updated') invalidates the catalogue query; the modal refetches and re-renders. No new broadcast type, no Zustand entry, no case '<provider>_status'. Frontend has zero references to any CLI-managed plugin's name.

  3. OAuthPanel.tsx connected fallback. The panel reads useProviderStatus(config.statusHook) for legacy hook-driven providers and falls back to config.stored (the catalogue's authoritative flag) for everything else:

    const connected = status ? !!status.connected : !!config.stored;
    

    Generic — no provider names anywhere. Future CLI-managed plugins inherit correct connection-indicator behaviour automatically.

Auto-installer pattern. Plugins wrapping a CLI binary that may not be on the user's PATH ship a _install.py exposing a single async helper:

# server/nodes/<provider>/_install.py
_VERSION = "1.40.9"  # pinned
_ASSETS = {
    ("Windows", "AMD64"):  ("…_windows_x86_64.zip", "zip", "stripe.exe"),
    ("Linux",   "x86_64"): ("…_linux_x86_64.tar.gz", "tar", "stripe"),
    …
}

async def ensure_<cli>_cli() -> Path:
    # 1. cached path → 2. shutil.which(...) → 3. workspace cache →
    # 4. fresh download from GitHub releases.

The plugin's DaemonEventSource subclass overrides start() to await ensure_<cli>_cli() first, sets binary_name = "" so the framework's pre-flight shutil.which check is skipped, and uses the resolved path inside build_command. The same shape suits any project that publishes pre-built binaries via GitHub releases.

Integration points (no core edits per plugin)

Concern Framework integration Plugin contribution
HTTP webhook ingress routers/webhook.py consults WEBHOOK_SOURCES registry register_webhook_source(MySource())
Event dispatch into workflows event_waiter.dispatch(event) from WebhookSource.handle (canvas Run, and a deploy that runs without Temporal) provider-specific shape() returning WorkflowEvent
Deployed delivery (Temporal) services.events.dispatch.emit discovers consumers through Visibility and sends on_event Signals; controlled deployments queue/filter in WorkflowControlWorkflow, separate listeners are compatibility paths register_canary_trigger_type(node_type, <the envelope type>) + an emit of each envelope (Stripe: _events.emit_stripe_event, called from handle)
Trigger waiting + filtering WebhookTriggerNode.build_filter (CloudEvents glob); both callers pass the envelope's data override build_filter to read the payload (the base rebuilds an envelope from it and raises); _extra_filter(params) only on top of the base
Deploy-time setup DeploymentManager._prepare_trigger_deployment calls the trigger class's prepare_deployment at Start and at the boot re-arm; a raise is logged and the trigger armed anyway optional prepare_deployment(node_id=, workflow_id=, parameters=) classmethod (Stripe starts stripe listen in a background task)
Daemon lifecycle DaemonEventSource.start/stop/restart via ProcessService build_command(secrets) + parse_line(stream, line) (subscribed via ProcessService.start(line_handler=...) — no log-file tailing)
Daemon credential gate DaemonEventSource.start consults await self.has_credential() before spawning optional override when auth is non-api-key (Stripe → is_logged_in()); default tests secrets["api_key"]
Lifecycle WebSocket commands make_lifecycle_handlers(prefix, source, extra=…) provider-specific extra handlers
Status refresh on WS connect make_status_refresh(source, status_key, broadcast_type) nothing — auto-derived from source
CLI subprocess invocation run_cli_command(binary=…, argv=…, credential=…) nothing — credential injection is automatic
Credentials Modal panel server/config/credential_providers.json (read by services.credential_registry) one provider entry: name, category, color, kind: "oauth", icon_ref, status_hook, ws.{login,logout,status} handler names, fields list, instructions string. Frontend modal renders it automatically — no React file edits.
AI tool surface per-plugin tool_name / tool_description ClassVars resolved via the node registry (Wave 12 D5 retired the services/ai.py DEFAULT_TOOL_NAMES / DEFAULT_TOOL_DESCRIPTIONS dicts — reintroduction is blocked by tests/test_tool_registry.py) tool_name + tool_description on the dual-purpose ActionNode, plus a row in tests/fixtures/tool_names_snapshot.json locking the name
Skill (LLM teaching markdown) server/skills/<agent>/<skill-name>/SKILL.md (auto-discovered by SkillLoader) the markdown itself, plus the linkage in visuals.json ("<nodeType>": { ..., "skill": "<skill-name>" })
Connection state surfaced to the modal (CLI-managed auth) auth_service.store_oauth_tokens(provider, "cli-managed", "cli-managed") + StatusBroadcaster.broadcast_credential_event (CloudEvents v1.0 envelope wrapping WorkflowEvent; locked by tests/credentials/test_credential_broadcasts.py) _mark_logged_in / _mark_logged_out helper pair; one broadcaster.broadcast_credential_event("credential.oauth.connected", provider="<id>") after login and …disconnected after logout. Same shape Twitter / Google logout use.
Auto-install of an external CLI binary _install.py with ensure_<cli>_cli() + GitHub-releases asset map pinned _VERSION constant, (system, machine) -> (asset, kind, member) table, and an override on DaemonEventSource.start() that awaits the helper before super().start() (also set binary_name = "" to skip the framework's shutil.which pre-check)

Use a stable provider event ID when the complete identity is available and preserve it on redelivery; otherwise retain the random envelope fallback. The controller borrows durable pending-key, deduplication, and rollover practices from the Event Accumulator pattern while preserving immediate per-event processing. Accepted Signals queue while stopped, including across overflow spill and Continue-As-New. Consumer discovery and delivery errors remain best effort before Signal acceptance; there is no producer outbox or external exactly-once guarantee. Same-label/type trigger Workflow-ID collisions remain a known naming limit. See Node creation: event identity and delivery, Workflow control, Event Accumulator, and Workflow messaging.

Tool / skill / visuals naming contract

Three coordinates have to agree for both the LLM tool dispatcher and the skill icon resolver to find their target:

Place Form Example
Plugin node type camelCase stripeAction
visuals.json key matches node type (camelCase) "stripeAction": { "skill": "stripe-skill" } (icon + color come from the plugin folder's icon.svg / meta.json; visuals.json carries zero asset: values post-F1/F7)
Plugin tool_name ClassVar (snapshot: tests/fixtures/tool_names_snapshot.json) snake_case of node type tool_name = "stripe_action"
Skill allowed-tools token matches the LLM tool name above allowed-tools: "stripe_action"

SkillLoader._parse_skill_metadata runs each allowed-tools token through snake → camel and looks the result up in visuals.json. Mismatches silently break icon resolution — a skill with allowed-tools: "stripe_cli" would convert to stripeCli and find nothing in visuals.json even though the node stripeAction is registered. Stick to <snake_case_of_node_type> unless you're prepared to maintain alias entries in visuals.json. See server/skills/GUIDE.md → Tool naming.

This is not hypothetical: githubAction / vercelAction deliberately use the short LLM tool names github / vercel, and their Master Skill rows shipped with blank icons until lowercase alias entries were added. The alias must carry BOTH icon and color — color normally comes from the plugin's meta.json, which is keyed by node type and therefore also misses for a custom tool name:

"github":  { "icon": "lobehub:Github", "color": "#8250df" },
"vercel":  { "icon": "lobehub:Vercel", "color": "#666666" }

The invariant is locked by server/tests/test_skill_icon_resolution.py — every shipped skill must resolve a non-empty icon, so a new plugin/skill pairing that breaks this contract fails CI instead of shipping a blank row.

When to use the framework

Use it for any new event-source plugin:

  • Signed webhooks → WebhookSource + WebhookTriggerNode + a verifier from services.events.verifiers (or contribute a new one).
  • CLI daemons → DaemonEventSource.
  • API polling → PollingEventSource.
  • Pure HTTP push without a verifier → PushEventSource directly.

Use plain TriggerNode only for in-process / synthetic events (taskTrigger, chatTrigger) that don't have an external source.

Phase rollout

  • Phase 1 (shipped): framework lands, Stripe plugin built natively on top. Existing 9 trigger plugins keep using their pre-framework paths (the event_waiter.dispatch(event_type, Dict) shim accepts legacy Dict payloads alongside WorkflowEvent).
  • Phase 2 (planned): migrate gmailReceive, emailReceive, twitterReceive to PollingEventSource. Net delete: ~30 LOC each.
  • Phase 3 (planned): migrate telegramReceive and whatsappReceive to DaemonEventSource. Net delete: ~50 LOC each.
  • Phase 4 (planned): sunset the legacy Dict-payload shim once every trigger uses WorkflowEvent.