machinaos 0.0.78 → 0.0.80

package/server/nodes/telegram/telegram_send.py

@@ -1,14 +1,15 @@
 """Telegram Send — Wave 11.C migration.
 
 Workflow-only ActionNode (no AI-tool exposure). The Telegram bot
-token lives in ``auth_service`` under ``telegram_bot_token``. Plugin
-delegates to the legacy ``handle_telegram_send`` handler during
-thin-migration; 11.E converts to a declarative ``TelegramCredential``.
+token lives in ``auth_service`` under the ``telegram`` credential id
+(was ``telegram_bot_token`` pre-rename). Plugin delegates to the
+legacy ``handle_telegram_send`` handler during thin-migration; 11.E
+converts to a declarative ``TelegramCredential``.
 """
 
 from __future__ import annotations
 
-from typing import Any, Dict, Literal, Optional
+from typing import Any, Literal, Optional
 
 from pydantic import BaseModel, ConfigDict, Field
 
@@ -116,10 +117,7 @@ class TelegramSendParams(BaseModel):
     # ===== OPTIONS =====
     parse_mode: Literal["Auto", "", "HTML", "Markdown", "MarkdownV2"] = Field(
         default="Auto",
-        description=(
-            "Auto converts LLM markdown to Telegram HTML. "
-            "Empty string = no parse mode (raw text)."
-        ),
+        description=("Auto converts LLM markdown to Telegram HTML. " "Empty string = no parse mode (raw text)."),
         json_schema_extra={
             "displayOptions": {"show": {"message_type": ["text", "photo", "document"]}},
         },
@@ -152,10 +150,8 @@ class TelegramSendNode(ActionNode):
     description = "Send text, photo, document, location, or contact via Telegram bot"
     component_kind = "square"
     handles = (
-        {"name": "input-main", "kind": "input", "position": "left",
-         "label": "Input", "role": "main"},
-        {"name": "output-main", "kind": "output", "position": "right",
-         "label": "Output", "role": "main"},
+        {"name": "input-main", "kind": "input", "position": "left", "label": "Input", "role": "main"},
+        {"name": "output-main", "kind": "output", "position": "right", "label": "Output", "role": "main"},
     )
     annotations = {"destructive": False, "readonly": False, "open_world": True}
     credentials = (TelegramCredential,)
@@ -183,6 +179,7 @@ class TelegramSendNode(ActionNode):
             if not chat_id:
                 try:
                     from services.plugin.deps import get_auth_service
+
                     saved = await get_auth_service().get_api_key("telegram_owner_chat_id")
                     if saved:
                         owner_id = int(saved)
@@ -216,21 +213,27 @@ class TelegramSendNode(ActionNode):
             if not params.text:
                 raise RuntimeError("text is required for text message")
             result = await service.send_message(
-                text=params.text, parse_mode=parse_mode, **common,
+                text=params.text,
+                parse_mode=parse_mode,
+                **common,
             )
         elif mt == "photo":
             if not params.media_url:
                 raise RuntimeError("media_url is required for photo message")
             result = await service.send_photo(
-                photo=params.media_url, caption=params.caption or None,
-                parse_mode=parse_mode, **common,
+                photo=params.media_url,
+                caption=params.caption or None,
+                parse_mode=parse_mode,
+                **common,
             )
         elif mt == "document":
             if not params.media_url:
                 raise RuntimeError("media_url is required for document message")
             result = await service.send_document(
-                document=params.media_url, caption=params.caption or None,
-                parse_mode=parse_mode, **common,
+                document=params.media_url,
+                caption=params.caption or None,
+                parse_mode=parse_mode,
+                **common,
             )
         elif mt == "location":
             if params.latitude is None or params.longitude is None:
@@ -257,8 +260,7 @@ class TelegramSendNode(ActionNode):
             raise RuntimeError(f"Unsupported message type: {mt}")
 
         log.info(
-            f"[Telegram] Message sent: type={mt}, chat={chat_id}, "
-            f"msg_id={result.get('message_id')}",
+            f"[Telegram] Message sent: type={mt}, chat={chat_id}, " f"msg_id={result.get('message_id')}",
         )
         return {
             "message_id": result.get("message_id"),

package/server/nodes/text/{file_handler.py → file_handler/__init__.py}

@@ -17,7 +17,13 @@ from services.plugin import ActionNode, NodeContext, Operation, TaskQueue
 
 class FileHandlerParams(BaseModel):
     file_type: Literal[
-        "generic", "markdown", "text", "json", "csv", "html", "xml",
+        "generic",
+        "markdown",
+        "text",
+        "json",
+        "csv",
+        "html",
+        "xml",
     ] = Field(
         default="generic",
         description="Content type tag used for downstream processing hints.",

package/server/nodes/text/file_handler/meta.json

@@ -0,0 +1,3 @@
+{
+  "color": "#bd93f9"
+}

package/server/nodes/text/{text_generator.py → text_generator/__init__.py}

@@ -48,7 +48,8 @@ class TextGeneratorNode(ActionNode):
 
         text_service = get_text_service()
         response = await text_service.execute_text_generator(
-            ctx.node_id, params.model_dump(),
+            ctx.node_id,
+            params.model_dump(),
         )
         if response.get("success"):
             return response.get("result") or response

package/server/nodes/text/text_generator/meta.json

@@ -0,0 +1,3 @@
+{
+  "color": "#bd93f9"
+}

package/server/nodes/tool/{agent_builder.py → agent_builder/__init__.py}

@@ -19,10 +19,10 @@ The five operations are pure canvas mutations:
 * ``create_workflow`` -- persist a fresh empty workflow + return its
   workflow_id.
 
-Each mutation pushes a ``workflow_ops_apply`` event via
-``status_broadcaster.send_custom_event`` so the live canvas updates.
-LangGraph binds tools at graph compile time, so a mutation made
-mid-run does NOT add a callable tool to the current run; the
+Each mutation pushes a ``workflow_ops_apply`` event via the plugin's
+``_events.broadcast_workflow_ops`` wrapper so the live canvas updates.
+The agent loop binds tools at the start of each turn, so a mutation
+made mid-run does NOT add a callable tool to the current turn; the
 agent's NEXT invocation rediscovers it. Each summary string ends
 with "Available on your next turn" so the LLM doesn't loop trying
 to call something that isn't there yet.
@@ -58,7 +58,7 @@ _TOOL_OUTPUT_HANDLE = "output-main"
 _MASTER_SKILL_TYPE = "masterSkill"
 _MASTER_SKILL_LABEL = "Master Skill"
 _AGENT_BUILDER_TYPE = "agentBuilder"
-_TEAM_LEAD_TYPES = frozenset({"orchestrator_agent", "ai_employee", "deep_agent"})
+_TEAM_LEAD_TYPES = frozenset({"orchestrator_agent", "ai_employee"})
 _DENIED_TOOL_TYPES = frozenset({_AGENT_BUILDER_TYPE, _MASTER_SKILL_TYPE})
 _KEY_PARAM_FIELDS = ("provider", "model", "operation", "url", "query")
 _SKILLS_DIR = Path(__file__).resolve().parents[2] / "skills"
@@ -70,20 +70,25 @@ _SKILLS_DIR = Path(__file__).resolve().parents[2] / "skills"
 
 
 async def _broadcast(workflow_id: Optional[str], caller_id: str, ops: List[Dict[str, Any]]) -> None:
-    """Push a workflow_ops_apply event so the live canvas updates."""
+    """Push a workflow_ops_apply event so the live canvas updates.
+
+    Wave 12 B10: routes through plugin _events.py wrapper.
+    """
     if not ops:
         return
     try:
-        from services.status_broadcaster import get_status_broadcaster
-        broadcaster = get_status_broadcaster()
-        await broadcaster.send_custom_event(
-            "workflow_ops_apply",
-            {"workflow_id": workflow_id, "caller_node_id": caller_id, "operations": ops},
+        from ._events import broadcast_workflow_ops
+
+        await broadcast_workflow_ops(
+            workflow_id=workflow_id,
+            caller_node_id=caller_id,
+            operations=ops,
         )
         logger.info(
-            "[agentBuilder] broadcast workflow_ops_apply: workflow_id=%s "
-            "caller=%s ops=%s",
-            workflow_id, caller_id, [op.get("type") for op in ops],
+            "[agentBuilder] broadcast workflow_ops_apply: workflow_id=%s " "caller=%s ops=%s",
+            workflow_id,
+            caller_id,
+            [op.get("type") for op in ops],
         )
     except Exception as exc:
         logger.warning(f"[agentBuilder] broadcast failed: {exc}", exc_info=True)
@@ -92,17 +97,14 @@ async def _broadcast(workflow_id: Optional[str], caller_id: str, ops: List[Dict[
 def _allowed_tool_types() -> set[str]:
     """Tool nodes the LLM may spawn -- excludes the builder + masterSkill."""
     return {
-        ntype for ntype, cls in registered_node_classes().items()
-        if getattr(cls, "component_kind", "") == "tool"
-        and ntype not in _DENIED_TOOL_TYPES
+        ntype
+        for ntype, cls in registered_node_classes().items()
+        if getattr(cls, "component_kind", "") == "tool" and ntype not in _DENIED_TOOL_TYPES
     }
 
 
 def _allowed_subagent_types() -> set[str]:
-    return {
-        ntype for ntype, cls in registered_node_classes().items()
-        if getattr(cls, "component_kind", "") == "agent"
-    }
+    return {ntype for ntype, cls in registered_node_classes().items() if getattr(cls, "component_kind", "") == "agent"}
 
 
 def _is_team_lead(node_type: str) -> bool:
@@ -150,21 +152,20 @@ def _resolve_caller(ctx: NodeContext) -> str:
     """
     self_id = ctx.node_id
     for edge in ctx.edges or []:
-        if (
-            edge.get("source") == self_id
-            and edge.get("targetHandle") == _TOOL_HANDLE
-        ):
+        if edge.get("source") == self_id and edge.get("targetHandle") == _TOOL_HANDLE:
             target = edge.get("target")
             if target:
                 logger.info(
-                    "[agentBuilder] caller resolved via input-tools edge: "
-                    "self=%s -> agent=%s", self_id, target,
+                    "[agentBuilder] caller resolved via input-tools edge: " "self=%s -> agent=%s",
+                    self_id,
+                    target,
                 )
                 return target
     logger.info(
-        "[agentBuilder] no input-tools edge found from %s; "
-        "falling back to self as caller (canvas: %d nodes, %d edges)",
-        self_id, len(ctx.nodes or []), len(ctx.edges or []),
+        "[agentBuilder] no input-tools edge found from %s; " "falling back to self as caller (canvas: %d nodes, %d edges)",
+        self_id,
+        len(ctx.nodes or []),
+        len(ctx.edges or []),
     )
     return self_id
 
@@ -179,10 +180,12 @@ def _log_op_entry(op: str, ctx: NodeContext, **fields: Any) -> None:
     edges = ctx.edges or []
     extra = " ".join(f"{k}={v!r}" for k, v in fields.items() if v not in (None, ""))
     logger.info(
-        "[agentBuilder.%s] workflow_id=%s self=%s nodes=%d edges=%d "
-        "raw_keys=%s%s",
-        op, ctx.workflow_id, ctx.node_id,
-        len(nodes), len(edges),
+        "[agentBuilder.%s] workflow_id=%s self=%s nodes=%d edges=%d " "raw_keys=%s%s",
+        op,
+        ctx.workflow_id,
+        ctx.node_id,
+        len(nodes),
+        len(edges),
         sorted((ctx.raw or {}).keys()),
         f" {extra}" if extra else "",
     )
@@ -227,10 +230,7 @@ class AgentBuilderParams(BaseModel):
     # add_skill
     skill_folder: str = Field(
         default="",
-        description=(
-            "For add_skill: skill folder name under server/skills/** "
-            "(e.g. 'http-request-skill', 'memory-skill')."
-        ),
+        description=("For add_skill: skill folder name under server/skills/** " "(e.g. 'http-request-skill', 'memory-skill')."),
         json_schema_extra={"displayOptions": {"show": {"operation": ["add_skill"]}}},
     )
 
@@ -241,7 +241,7 @@ class AgentBuilderParams(BaseModel):
             "For add_subagent: agent node type to spawn (e.g. "
             "'coding_agent', 'web_agent'). Must be component_kind='agent' "
             "and not a team-lead. Caller must itself be a team-lead "
-            "(orchestrator_agent / ai_employee / deep_agent)."
+            "(orchestrator_agent / ai_employee)."
         ),
         json_schema_extra={"displayOptions": {"show": {"operation": ["add_subagent"]}}},
     )
@@ -296,11 +296,11 @@ class AgentBuilderNode(ToolNode):
         "agent calls operations through the standard tool path."
     )
     component_kind = "tool"
+    tool_name = "agent_builder"
+    tool_description = "Inspect and modify the workflow canvas at runtime. Operations: inspect_canvas (read current nodes/edges), spawn_tool (add a tool node + wire it), enable_skill (add a skill folder to a connected masterSkill), add_delegate_agent (add a specialized agent), create_workflow (spawn a brand-new workflow)."
     handles = (
-        {"name": "input-main", "kind": "input", "position": "left",
-         "label": "Input", "role": "main"},
-        {"name": "output-tool", "kind": "output", "position": "top",
-         "label": "Tool", "role": "tools"},
+        {"name": "input-main", "kind": "input", "position": "left", "label": "Input", "role": "main"},
+        {"name": "output-tool", "kind": "output", "position": "top", "label": "Tool", "role": "tools"},
     )
     ui_hints = {"isToolPanel": True, "hideRunButton": True}
     annotations = {"destructive": False, "readonly": False, "open_world": True}
@@ -313,7 +313,9 @@ class AgentBuilderNode(ToolNode):
 
     @Operation("inspect_canvas")
     async def inspect_canvas(
-        self, ctx: NodeContext, params: AgentBuilderParams,
+        self,
+        ctx: NodeContext,
+        params: AgentBuilderParams,
     ) -> AgentBuilderOutput:
         _log_op_entry("inspect_canvas", ctx)
         nodes = list(ctx.nodes or [])
@@ -345,7 +347,8 @@ class AgentBuilderNode(ToolNode):
                 "source_type": type_by_id.get(e.get("source")),
                 "target_handle": e.get("targetHandle"),
             }
-            for e in edges if e.get("target") == caller_id
+            for e in edges
+            if e.get("target") == caller_id
         ]
         outgoing = [
             {
@@ -353,7 +356,8 @@ class AgentBuilderNode(ToolNode):
                 "target_type": type_by_id.get(e.get("target")),
                 "source_handle": e.get("sourceHandle"),
             }
-            for e in edges if e.get("source") == caller_id
+            for e in edges
+            if e.get("source") == caller_id
         ]
 
         tools = [c for c in incoming if c["target_handle"] == _TOOL_HANDLE]
@@ -380,7 +384,9 @@ class AgentBuilderNode(ToolNode):
 
     @Operation("add_tool")
     async def add_tool(
-        self, ctx: NodeContext, params: AgentBuilderParams,
+        self,
+        ctx: NodeContext,
+        params: AgentBuilderParams,
     ) -> AgentBuilderOutput:
         _log_op_entry("add_tool", ctx, node_type=params.node_type)
         node_type = (params.node_type or "").strip()
@@ -395,10 +401,7 @@ class AgentBuilderNode(ToolNode):
             sample = ", ".join(sorted(allowed)[:10])
             return AgentBuilderOutput(
                 operation="add_tool",
-                summary=(
-                    f"add_tool: '{node_type}' is not an allowed tool type. "
-                    f"Examples of allowed types: {sample}..."
-                ),
+                summary=(f"add_tool: '{node_type}' is not an allowed tool type. " f"Examples of allowed types: {sample}..."),
                 operations=[],
             )
 
@@ -406,13 +409,17 @@ class AgentBuilderNode(ToolNode):
         client_ref = f"new_{node_type}"
         ops = [
             workflow_ops.add_node(
-                client_ref, node_type, {},
+                client_ref,
+                node_type,
+                {},
                 label=node_type,
                 position=workflow_ops.anchored(caller_id, offset_x=200, offset_y=80),
             ),
             workflow_ops.add_edge(
-                {"client_ref": client_ref}, caller_id,
-                source_handle=_TOOL_OUTPUT_HANDLE, target_handle=_TOOL_HANDLE,
+                {"client_ref": client_ref},
+                caller_id,
+                source_handle=_TOOL_OUTPUT_HANDLE,
+                target_handle=_TOOL_HANDLE,
             ),
         ]
         await _broadcast(ctx.workflow_id, caller_id, ops)
@@ -426,7 +433,9 @@ class AgentBuilderNode(ToolNode):
 
     @Operation("add_skill")
     async def add_skill(
-        self, ctx: NodeContext, params: AgentBuilderParams,
+        self,
+        ctx: NodeContext,
+        params: AgentBuilderParams,
     ) -> AgentBuilderOutput:
         _log_op_entry("add_skill", ctx, skill_folder=params.skill_folder)
         skill = (params.skill_folder or "").strip()
@@ -448,27 +457,25 @@ class AgentBuilderNode(ToolNode):
         caller_id = _resolve_caller(ctx)
 
         skill_edge = next(
-            (e for e in edges if e.get("target") == caller_id
-             and e.get("targetHandle") == _SKILL_HANDLE),
+            (e for e in edges if e.get("target") == caller_id and e.get("targetHandle") == _SKILL_HANDLE),
             None,
         )
         master_skill = None
         if skill_edge:
             master_skill = next(
-                (n for n in nodes if n.get("id") == skill_edge.get("source")
-                 and n.get("type") == _MASTER_SKILL_TYPE),
+                (n for n in nodes if n.get("id") == skill_edge.get("source") and n.get("type") == _MASTER_SKILL_TYPE),
                 None,
             )
 
         if master_skill:
-            existing = (
-                ((master_skill.get("data") or {}).get("parameters") or {})
-                .get("skills_config") or {}
-            )
+            existing = ((master_skill.get("data") or {}).get("parameters") or {}).get("skills_config") or {}
             new_config = _toggle_skill(existing, skill, True)
-            ops = [workflow_ops.set_node_parameters(
-                master_skill["id"], {"skills_config": new_config},
-            )]
+            ops = [
+                workflow_ops.set_node_parameters(
+                    master_skill["id"],
+                    {"skills_config": new_config},
+                )
+            ]
             await _broadcast(ctx.workflow_id, caller_id, ops)
             return AgentBuilderOutput(
                 operation="add_skill",
@@ -480,23 +487,23 @@ class AgentBuilderNode(ToolNode):
         client_ref = "new_master_skill"
         ops = [
             workflow_ops.add_node(
-                client_ref, _MASTER_SKILL_TYPE,
+                client_ref,
+                _MASTER_SKILL_TYPE,
                 {"skills_config": new_config},
                 label=_MASTER_SKILL_LABEL,
                 position=workflow_ops.anchored(caller_id, offset_x=-60, offset_y=220),
             ),
             workflow_ops.add_edge(
-                {"client_ref": client_ref}, caller_id,
-                source_handle=_SKILL_OUTPUT_HANDLE, target_handle=_SKILL_HANDLE,
+                {"client_ref": client_ref},
+                caller_id,
+                source_handle=_SKILL_OUTPUT_HANDLE,
+                target_handle=_SKILL_HANDLE,
             ),
         ]
         await _broadcast(ctx.workflow_id, caller_id, ops)
         return AgentBuilderOutput(
             operation="add_skill",
-            summary=(
-                f"Created Master Skill node and enabled '{skill}'. "
-                "Available on your next turn."
-            ),
+            summary=(f"Created Master Skill node and enabled '{skill}'. " "Available on your next turn."),
             operations=ops,
         )
 
@@ -504,7 +511,9 @@ class AgentBuilderNode(ToolNode):
 
     @Operation("add_subagent")
     async def add_subagent(
-        self, ctx: NodeContext, params: AgentBuilderParams,
+        self,
+        ctx: NodeContext,
+        params: AgentBuilderParams,
     ) -> AgentBuilderOutput:
         _log_op_entry("add_subagent", ctx, agent_type=params.agent_type)
         agent_type = (params.agent_type or "").strip()
@@ -524,10 +533,7 @@ class AgentBuilderNode(ToolNode):
             leads = ", ".join(sorted(_TEAM_LEAD_TYPES))
             return AgentBuilderOutput(
                 operation="add_subagent",
-                summary=(
-                    f"add_subagent: only team-lead agents ({leads}) can spawn "
-                    f"delegates. This agent is '{caller_type}'."
-                ),
+                summary=(f"add_subagent: only team-lead agents ({leads}) can spawn " f"delegates. This agent is '{caller_type}'."),
                 operations=[],
             )
         allowed = _allowed_subagent_types()
@@ -535,41 +541,36 @@ class AgentBuilderNode(ToolNode):
             sample = ", ".join(sorted(allowed)[:10])
             return AgentBuilderOutput(
                 operation="add_subagent",
-                summary=(
-                    f"add_subagent: '{agent_type}' is not an allowed agent "
-                    f"type. Examples: {sample}..."
-                ),
+                summary=(f"add_subagent: '{agent_type}' is not an allowed agent " f"type. Examples: {sample}..."),
                 operations=[],
             )
         if _is_team_lead(agent_type):
             return AgentBuilderOutput(
                 operation="add_subagent",
-                summary=(
-                    f"add_subagent: cannot spawn another team-lead "
-                    f"('{agent_type}'); pick a specialized agent instead."
-                ),
+                summary=(f"add_subagent: cannot spawn another team-lead " f"('{agent_type}'); pick a specialized agent instead."),
                 operations=[],
             )
 
         client_ref = f"new_{agent_type}"
         ops = [
             workflow_ops.add_node(
-                client_ref, agent_type, {},
+                client_ref,
+                agent_type,
+                {},
                 label=agent_type,
                 position=workflow_ops.anchored(caller_id, offset_x=300, offset_y=200),
             ),
             workflow_ops.add_edge(
-                {"client_ref": client_ref}, caller_id,
-                source_handle=_TEAMMATES_OUTPUT_HANDLE, target_handle=_TEAMMATES_HANDLE,
+                {"client_ref": client_ref},
+                caller_id,
+                source_handle=_TEAMMATES_OUTPUT_HANDLE,
+                target_handle=_TEAMMATES_HANDLE,
             ),
         ]
         await _broadcast(ctx.workflow_id, caller_id, ops)
         return AgentBuilderOutput(
             operation="add_subagent",
-            summary=(
-                f"Added '{agent_type}' as a teammate. Available on your "
-                "next turn (configure provider/model first)."
-            ),
+            summary=(f"Added '{agent_type}' as a teammate. Available on your " "next turn (configure provider/model first)."),
             operations=ops,
         )
 
@@ -577,10 +578,13 @@ class AgentBuilderNode(ToolNode):
 
     @Operation("create_workflow")
     async def create_workflow(
-        self, ctx: NodeContext, params: AgentBuilderParams,
+        self,
+        ctx: NodeContext,
+        params: AgentBuilderParams,
     ) -> AgentBuilderOutput:
         _log_op_entry(
-            "create_workflow", ctx,
+            "create_workflow",
+            ctx,
             workflow_name=params.workflow_name,
             workflow_description=params.workflow_description,
         )
@@ -611,9 +615,13 @@ class AgentBuilderNode(ToolNode):
         }
 
         from services.plugin.deps import get_database
+
         database = get_database()
         ok = await database.save_workflow(
-            workflow_id, name, workflow_data, description=description or None,
+            workflow_id,
+            name,
+            workflow_data,
+            description=description or None,
         )
         if not ok:
             return AgentBuilderOutput(
@@ -622,9 +630,6 @@ class AgentBuilderNode(ToolNode):
             )
         return AgentBuilderOutput(
             operation="create_workflow",
-            summary=(
-                f"Created workflow '{name}' (id: {workflow_id}). "
-                "User can switch to it from the toast notification."
-            ),
+            summary=(f"Created workflow '{name}' (id: {workflow_id}). " "User can switch to it from the toast notification."),
             workflow_id=workflow_id,
         )

package/server/nodes/tool/agent_builder/_events.py

@@ -0,0 +1,91 @@
+"""CloudEvents factory + broadcaster wrapper for agent_builder.
+
+Per RFC plugin_authoring_rfc.md §6.4: plugin-specific factories live in
+the plugin folder.
+
+This is NOT a trigger event — it's a canvas-mutation broadcast consumed
+by the frontend's ``useWorkflowOpsListener`` hook. The wire format is
+flat (``{workflow_id, caller_node_id, operations}``) for FE back-compat;
+the typed envelope is constructed for parity with the other plugin
+``_events.py`` modules but not consumed today.
+
+Delivery: direct WS broadcast (no ``dispatch.emit`` — no
+:class:`TriggerListenerWorkflow` consumer exists for canvas mutations,
+and no legacy ``event_waiter`` waiter listens on ``workflow_ops_apply``
+either). Pre-Wave-13 this routed through ``send_custom_event`` which
+also called ``event_waiter.dispatch_async`` — that dispatch was dead.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from services.events.envelope import WorkflowEvent
+
+
+# Flat wire-routing key consumed by ``client/src/hooks/useWorkflowOpsListener``.
+_WIRE_ROUTING_KEY = "workflow_ops_apply"
+
+
+def workflow_ops_applied(
+    *,
+    workflow_id: Optional[str],
+    caller_node_id: str,
+    operations: List[Dict[str, Any]],
+) -> WorkflowEvent:
+    """Canvas-mutation envelope. ``subject`` is the caller node id so
+    consumers can route per-builder."""
+    return WorkflowEvent(
+        source="machinaos://nodes/agent_builder",
+        type="com.machinaos.workflow.ops.applied",
+        subject=caller_node_id,
+        workflow_id=workflow_id,
+        data={
+            "workflow_id": workflow_id,
+            "caller_node_id": caller_node_id,
+            "operations": list(operations),
+        },
+    )
+
+
+async def broadcast_workflow_ops(
+    *,
+    workflow_id: Optional[str],
+    caller_node_id: str,
+    operations: List[Dict[str, Any]],
+) -> None:
+    """Broadcast a canvas-mutation event for the FE to apply.
+
+    Flat payload (FE back-compat with ``useWorkflowOpsListener``); the
+    typed envelope is constructed for audit/future migration but not
+    on the wire today.
+    """
+    if not operations:
+        return
+    from services.status_broadcaster import get_status_broadcaster
+
+    broadcaster = get_status_broadcaster()
+    payload = {
+        "workflow_id": workflow_id,
+        "caller_node_id": caller_node_id,
+        "operations": list(operations),
+    }
+    # Envelope constructed for parity / future migration; not on the
+    # wire today because FE listener reads the flat shape.
+    _ = workflow_ops_applied(
+        workflow_id=workflow_id,
+        caller_node_id=caller_node_id,
+        operations=operations,
+    )
+    await broadcaster.broadcast(
+        {
+            "type": _WIRE_ROUTING_KEY,
+            "data": payload,
+        }
+    )
+
+
+__all__ = [
+    "broadcast_workflow_ops",
+    "workflow_ops_applied",
+]

package/server/nodes/tool/agent_builder/meta.json

@@ -0,0 +1,3 @@
+{
+  "color": "#ffb86c"
+}