Self-improving AI Employees for everyone
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_REGISTRYindexes 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_HANDLERSmerge inNodeExecutormakes 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):
BaseModelreturn →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_unsetpreserves the producer's exact key set — declared-but-absentOptionalfields never materialise asNonekeys. - dict return, no declared
Output(_EmptyOutputdefault) → 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 corruptingnode_outputspersistence or the WS broadcast downstream.
Practical rules for plugin authors:
- Prefer returning the
Outputmodel instance (return ExampleOutput(...)). Dicts work but get validated. Outputmodels declareextra="allow"+ all-Optionalfields by convention — extra context keys pass through; only type mismatches fail.- Never put raw backend or SDK objects (for example a native filesystem
ReadResultor provider response object) into the result — unwrap to plain fields. Everything downstream (JSON column, orjson WS broadcast,_serialise_tool_result) expects JSON-compatible data. - LLM-facing string formatting is the dispatcher's job (
_serialise_tool_resultJSON-dumps the whole payload) — return real lists/dicts, not pre-stringified JSON. - 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")— seeAndroidServiceParams._coerce_parametersandWriteTodosParams._coerce_todosfor 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"onField(...). - No
populate_by_name=Trueinmodel_config. - No
model_dump(by_alias=True)in handlers — callmodel_dump()or read typed attributes off the validatedparamsobject. displayOptions.show["driver_field"]must match a Pydantic field name in the sameParamsclass. 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
groupkey are collected into a singletype: "collection"INodeProperty. The collection is positioned at the first child's slot in the original schema order; subsequent children slot into itsoptionsarray. - Missing class-level
groups[<key>]metadata falls back todisplay_name = titleCase(key)(e.g."options"→"Options") andplaceholder = 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 viaauth_service.get_oauth_tokens.Credential— fully custom (overrideresolve()+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()) viaworkflow_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
OutputPydantic class that the centralnode_output_schemas.NODE_OUTPUT_SCHEMASwould 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/groupper class. Params+Outputmust be PydanticBaseModelsubclasses.- Every declared
credentialsentry resolves to a registered class. - Operation names unique per class.
routing=...requirescredentialsdeclared.task_queue∈TaskQueue.ALL.- Every
ToolNodeJSON schema has no$defs/$ref(LLM-compat). - Every event-mode
TriggerNodedeclaresevent_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
- One plugin = one authoring location. Adding a new node never edits multiple files. The filesystem location matches the palette group.
- Backend is SSOT. Node declaration, visual metadata, handlers, schemas, credentials, icons — one authoring location.
- No frontend fallbacks. Missing data surfaces as a visible gap so the backend bug is obvious, not masked.
- Stateful services stay in
services/. AIService, MapsService, NodeJSClient, etc. Plugins call them; never inline them. - Per-handler helpers move WITH the handler.
_format_console_output,_extract_text, … inline into the plugin file. Cross-handler helpers (likeedge_walker) extract to shared modules. - Container injection. Plugins do
from core.container import container; svc = container.X()— never instantiate services directly. - 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_nodedecorator (dict form); filesystem-as-catalog. - Wave 11.A —
services/plugin/package withBaseNodehierarchy. - 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_walkerextracted 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.pyhelpers. - 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.pyfor client + XDK helpers. - Wave 11.D.9 — WhatsApp + Social inlined into
nodes/whatsapp/_base.pyandnodes/social/_base.py(full bodies, RPC dispatch viaservices.whatsapp_service; renamed from the misnamedwhatsapp.pyrouter in Wave 11.E.2 since it was never an APIRouter, and moved again intonodes/whatsapp/_service.pyin Wave 11.I). - Wave 11.D.10 —
utility.pysplit 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())TemporalWorkerPoolclass.
- F4.A — Orchestrator wired to per-type dispatch behind
TEMPORAL_PER_TYPE_DISPATCHflag (commit8261b05). Closes the Wave 11.F orchestrator gap. - F4.B —
AgentWorkflowchild workflow + 3 agent activities behindTEMPORAL_AGENT_WORKFLOW_ENABLEDflag (commita4d009e). Tool calls inside AI agents become per-type activities. - Wave 11.E — Declarative credentials: 25
Credentialsubclasses at the time (GoogleCredential + GoogleMapsCredential + TwitterCredential + TelegramCredential + ApifyCredential + 12 LLM providers + 3 inline search credentials + Stripe / Vercel / GitHub / Cloudflare / WhatsApp); 29 plugins declaredcredentials = (...). Today the live numbers arelen(CREDENTIAL_REGISTRY)(36) and 56 node types with a non-emptycredentialstuple (late September 2026). Agents stay poly-provider (empty tuple). - Wave 11.E.1 — Modularised credentials into per-domain
nodes/<group>/_credentials.pyfiles.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 duplicatehandlers/proxy.py, moved the misnamedwhatsapp.pyrouter →whatsapp_service.pyunder services (nownodes/whatsapp/_service.pysince Wave 11.I), dedup'dTRIGGER_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.py4 ways:handle_ai_chat_model→ChatModelBase.chat,handle_simple_memory→SimpleMemoryNode.read,handle_ai_agent/handle_chat_agent→ deleted entirely.tools.py:_execute_delegated_agentnow looks up the child agent's plugin class viaservices.node_registry.get_node_class(node_type), buildsNodeContext.from_legacy(...), and callsinstance.execute(node_id, params, ctx)directly — no handler shell in the path. - Wave 11.E.4 — Relocated
tools.pymovables: proxyConfig 10-op matrix →nodes/proxy/proxy_config.execute_proxy_config(shared by the plugin'sdispatchop and the AI-tool branch intools.py); Android AI-tool dispatch (toolkit + direct service) →nodes/android/_base.{execute_android_toolkit, execute_android_service_tool}with a single canonicalSERVICE_ID_MAPand a shared_execute_with_broadcasthelper (previously duplicated intools.py).tools.pyfrom 1,255 → 821 LOC. (execute_android_toolkithas since been removed along with theandroidToolaggregator node; onlyexecute_android_service_toolremains.) - 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 asregister_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.pyshrunk by ~808 LOC; three plugin routers (twitter / google / android) moved intonodes/<plugin>/_router.pyand mount via the plugin-router loop inmain.py.tests/test_plugin_self_containment.pylocks 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 viagrep -c '^class Test' server/tests/test_plugin_self_containment.py). - Wave 12 — Generalized event framework
(
services/events/). AddsWorkflowEvent(CloudEvents v1.0 envelope, in-house Pydantic),EventSourcehierarchy (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 oldtelegram_service.pyservice 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_statusremoved),services/handlers/triggers.py(hardcodedif node_type == 'telegramReceive'branch removed),services/node_output_schemas.py(duplicateTelegramReceiveOutputclass removed) — all relocated tonodes/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_typederived fromwebhook_source.typeautomatically. It is the canvas-Run waiter key, so set it yourself whenshapereturns envelopes of another type, orevent_waiter.dispatchmatches no waiter (Stripe setsSTRIPE_EVENT_RECEIVED_TYPE).build_filtercombining CloudEvents type-glob + optional_extra_filter. Override it to read the payload instead. Both callers hand the filter the envelope'sdata, not the envelope: the event waiter on a canvas Run, andevaluate_trigger_filter_activityon a deployed listener. The base rebuilds aWorkflowEventfrom that dict, which raises unless the data happens to carrysourceandtype; a waiter logs the error and stays unresolved, and a deployed listener fails open and ignores the filter.StripeReceiveNodeoverrides it; the WhatsApp Business triggers do not, so a deployed one admits every event whatever itsevent_type_filter.execute()with the_check_preconditionshort-circuit, thenshape_outputon the resolved event (the waiter resolves withdata, which_as_eventwraps back into an envelope). A deployed run receivesevent.dataverbatim and never callsshape_output, so shape the payload in the source and letshape_outputreturnevent.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:
Marker-token write via the existing
auth_service.store_oauth_tokensAPI. Plugin writes synthetic strings (e.g."cli-managed") on login completion. The catalogue's per-providerstoredflag comes fromprovider_connection_stateinservices/credential_registry.py(called byhandle_get_credential_catalogueand by the Normal-mode employee summaries). It checks, in order: a declarativestored_check, thenstatus_hook(auth_service.get_oauth_tokens(status_hook) is not None— identical to Google's OAuth-callback path), then the providerkind(apiKey/oauth), thenconnected_check. The synthetic tokens exist purely to flip that existence check; the CLI owns the real auth.Generic
credential_catalogue_updatedbroadcast. The plugin emits this event after every state change. The frontend's existing handler inWebSocketContext.tsx(case 'credential_catalogue_updated') invalidates the catalogue query; the modal refetches and re-renders. No new broadcast type, no Zustand entry, nocase '<provider>_status'. Frontend has zero references to any CLI-managed plugin's name.OAuthPanel.tsxconnectedfallback. The panel readsuseProviderStatus(config.statusHook)for legacy hook-driven providers and falls back toconfig.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 fromservices.events.verifiers(or contribute a new one). - CLI daemons →
DaemonEventSource. - API polling →
PollingEventSource. - Pure HTTP push without a verifier →
PushEventSourcedirectly.
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 legacyDictpayloads alongsideWorkflowEvent). - Phase 2 (planned): migrate
gmailReceive,emailReceive,twitterReceivetoPollingEventSource. Net delete: ~30 LOC each. - Phase 3 (planned): migrate
telegramReceiveandwhatsappReceivetoDaemonEventSource. Net delete: ~50 LOC each. - Phase 4 (planned): sunset the legacy
Dict-payload shim once every trigger usesWorkflowEvent.