machinaos 0.0.78 → 0.0.80

package/server/services/plugin/base.py

@@ -20,11 +20,12 @@ from __future__ import annotations
 
 import time
 from datetime import datetime, timezone
-from typing import Any, Awaitable, Callable, ClassVar, Dict, List, Optional, Sequence, Type
+from typing import Any, Awaitable, Callable, ClassVar, Dict, Optional, Sequence, Type
 
+from opentelemetry import trace
 from pydantic import BaseModel, ValidationError
 
-from core.logging import get_logger
+from core.logging import get_logger, log_context
 from services.plugin.connection import Connection
 from services.plugin.context import NodeContext
 from services.plugin.credential import Credential
@@ -39,6 +40,7 @@ from services.plugin.scaling import (
 )
 
 logger = get_logger(__name__)
+tracer = trace.get_tracer(__name__)
 
 
 class NodeUserError(Exception):
@@ -120,8 +122,6 @@ class BaseNode:
     version: ClassVar[int] = 1
     display_name: ClassVar[str] = ""
     subtitle: ClassVar[str] = ""
-    icon: ClassVar[str] = ""
-    color: ClassVar[str] = ""
     group: ClassVar[Sequence[str]] = ()
     description: ClassVar[str] = ""
     handles: ClassVar[Sequence[Dict[str, Any]]] = ()
@@ -144,6 +144,23 @@ class BaseNode:
     component_kind: ClassVar[str] = "generic"
     usable_as_tool: ClassVar[bool] = False
 
+    # Wave 12 D5: LLM-visible name + description for plugins surfaced as
+    # AI tools (ToolNode subclasses, ActionNodes marked usable_as_tool=True,
+    # SpecializedAgentBase subclasses).
+    #
+    # ``tool_name`` is genuinely distinct from ``type`` (camelCase → snake;
+    # e.g. ``calculatorTool`` → ``calculator``, ``pythonExecutor`` →
+    # ``python_code``); plugins declare it when they want an LLM-facing
+    # name that differs from the registry key.
+    #
+    # ``tool_description`` defaults to falling back to ``cls.description``
+    # at resolve time — plugins ONLY override when the LLM-facing variant
+    # needs to differ materially from the human-facing description
+    # (writeTodos' instruction-heavy prompt, pythonExecutor's available-
+    # libraries hint, specialized agents' ONE-SHOT pattern, etc.).
+    tool_name: ClassVar[str] = ""
+    tool_description: ClassVar[str] = ""
+
     # Set by __init_subclass__: {op_name: OperationSpec}
     _operations: ClassVar[Dict[str, OperationSpec]] = {}
     # Flag so concrete subclasses auto-register; abstract kinds don't.
@@ -170,16 +187,40 @@ class BaseNode:
         #     the canvas.
         # Subclasses opt out by explicitly setting either flag to False
         # on the class.
-        is_tool_oriented = (
-            cls.usable_as_tool or cls.component_kind == "tool"
-        )
+        is_tool_oriented = cls.usable_as_tool or cls.component_kind == "tool"
         if is_tool_oriented:
             if "hide_input_handle" not in cls.__dict__:
                 cls.hide_input_handle = True
             if "hide_output_handle" not in cls.__dict__:
                 cls.hide_output_handle = True
+        # Wave 12 D5: auto-derive ``tool_name`` / ``tool_description`` for
+        # agents (component_kind=="agent") that don't declare their own.
+        # Pattern is parametric — every agent surfaces as
+        # ``delegate_to_<type>`` to the parent LLM. Subclasses with a
+        # distinct delegation contract (autonomous_agent's Code Mode hint,
+        # orchestrator_agent / ai_employee's "Coordinates multiple agents",
+        # rlm_agent's REPL note, claude_code_agent's coding note) override
+        # ``tool_description`` directly on the class.
+        if cls.component_kind == "agent":
+            if "tool_name" not in cls.__dict__:
+                cls.tool_name = f"delegate_to_{cls.type}"
+            if "tool_description" not in cls.__dict__:
+                agent_label = cls.display_name or cls.type
+                cls.tool_description = (
+                    f"ONE-SHOT delegation to {agent_label}. Call ONCE per "
+                    f"task, returns task_id immediately. Agent works in "
+                    f"background - do NOT re-call."
+                )
         # Eager registry write — same four registries as @register_node.
+        # ORDER MATTERS: register_node_class MUST precede register_node so
+        # that cls._metadata_dict() (evaluated as the metadata argument)
+        # can resolve the plugin folder via get_node_class(cls.type) inside
+        # get_plugin_icon_path. Without this order the icon falls through
+        # to visuals.json — defeating the per-plugin icon.svg endpoint
+        # (RFC §6.5 / Phase 6).
         from services.node_registry import register_node, register_node_class
+
+        register_node_class(cls)
         register_node(
             type=cls.type,
             metadata=cls._metadata_dict(),
@@ -187,7 +228,6 @@ class BaseNode:
             output_model=cls.Output if cls.Output is not _EmptyOutput else None,
             handler=cls._make_legacy_handler(),
         )
-        register_node_class(cls)
 
     # ---- metadata projection ---------------------------------------------
 
@@ -196,15 +236,29 @@ class BaseNode:
         """Project class attributes onto the :data:`NodeMetadata` TypedDict
         expected by the existing node_spec emitter.
 
-        ``icon`` and ``color`` are sourced from
-        ``server/nodes/visuals.json`` via the central handler — node
-        plugins don't declare them on the class. A subclass MAY still
-        override by setting the class attribute, in which case the
-        explicit value wins.
+        Icon resolution (per RFC §6.5):
+        1. Per-plugin ``icon.svg`` co-located with the plugin folder —
+           emitted as a URL routed through ``GET /api/schemas/nodes/<type>/icon``.
+        2. Fallback to ``visuals.json`` (emoji / ``lobehub:<brand>``).
+
+        Color resolution (per RFC §6.6 / F2):
+        1. Per-plugin ``meta.json`` ``color`` field, co-located with the
+           plugin folder. Mirrors icon co-location.
+        2. Fallback to ``visuals.json`` for legacy entries that have
+           not been migrated yet.
         """
-        from nodes._visuals import get_icon, get_color
-        icon = cls.icon or get_icon(cls.type)
-        color = cls.color or get_color(cls.type)
+        from nodes._visuals import (
+            get_icon,
+            get_color,
+            get_plugin_icon_path,
+            get_plugin_meta,
+        )
+
+        if get_plugin_icon_path(cls.type) is not None:
+            icon = f"/api/schemas/nodes/{cls.type}/icon"
+        else:
+            icon = get_icon(cls.type)
+        color = get_plugin_meta(cls.type, "color") or get_color(cls.type)
         meta: Dict[str, Any] = {
             "displayName": cls.display_name or cls.type,
             "icon": icon,
@@ -242,6 +296,7 @@ class BaseNode:
         (redundant — class is already the dispatch target) and route
         through :meth:`execute`.
         """
+
         async def _legacy(
             node_id: str,
             node_type: str,
@@ -256,7 +311,8 @@ class BaseNode:
                 connection_factory=_make_connection_factory(cls, context),
             )
             return await instance.execute(node_id, parameters, ctx)
-        _legacy.__node_class__ = cls       # type: ignore[attr-defined]
+
+        _legacy.__node_class__ = cls  # type: ignore[attr-defined]
         _legacy.__qualname__ = f"{cls.__qualname__}._legacy_handler"
         return _legacy
 
@@ -271,9 +327,58 @@ class BaseNode:
         """Universal entry point. Validate params → dispatch op →
         wrap result. Subclasses (TriggerNode, ToolNode) override to
         change the return shape or lifetime.
+
+        The body runs under two ambient contexts:
+
+        - :func:`core.logging.log_context` binds ``node_id`` /
+          ``node_type`` / ``workflow_id`` to every log record emitted
+          while the operation runs, via ``structlog.contextvars``.
+          Survives ``asyncio.gather`` child tasks (stdlib
+          ``contextvars`` is task-local).
+        - An OpenTelemetry span named ``node.{type}.execute`` so
+          per-plugin latency / failures show up in any tracer backend
+          without per-plugin instrumentation. Span attributes carry
+          the same identifiers as the log context.
         """
         start_time = time.time()
+        workflow_id_attr: Optional[str] = None
+        if isinstance(context.raw, dict):
+            workflow_id_attr = context.raw.get("workflow_id")
 
+        log_fields: Dict[str, Any] = {
+            "node_id": node_id,
+            "node_type": self.type,
+        }
+        if workflow_id_attr is not None:
+            log_fields["workflow_id"] = workflow_id_attr
+
+        async with log_context(**log_fields):
+            with tracer.start_as_current_span(
+                f"node.{self.type}.execute",
+                attributes={
+                    "node.id": node_id,
+                    "node.type": self.type,
+                    **({"workflow.id": workflow_id_attr} if workflow_id_attr else {}),
+                },
+            ):
+                return await self._execute_body(
+                    node_id=node_id,
+                    parameters=parameters,
+                    context=context,
+                    start_time=start_time,
+                )
+
+    async def _execute_body(
+        self,
+        *,
+        node_id: str,
+        parameters: Dict[str, Any],
+        context: NodeContext,
+        start_time: float,
+    ) -> Dict[str, Any]:
+        """The actual execute pipeline — extracted so :meth:`execute`
+        stays a thin shell around the ambient log-context + span. Kept
+        method-private; callers should always go through :meth:`execute`."""
         # Stash the raw (pre-validation) parameters dict in context.raw
         # so plugins can recover values the Pydantic extra="ignore" policy
         # would drop — e.g. ``api_key`` injected by node_executor's
@@ -303,8 +408,62 @@ class BaseNode:
         try:
             result = await self._run_operation(op_spec, params_obj, context)
         except PermissionError as e:
+            # Credential.resolve() raises PermissionError annotated with
+            # .provider / .reason / .auth attributes (see
+            # services/plugin/credential.py). When .provider is present,
+            # emit a CloudEvents-typed broadcast via
+            # ``broadcast_credential_event`` — the existing wire used by
+            # every credential mutation. The envelope rides as a
+            # WorkflowEvent with type ``credential.{auth}.runtime_failed``
+            # so frontend consumers can glob-match ``credential.*.*``
+            # without inventing a new wire-frame key. Surface a
+            # ``credential`` block in the operation response so the user
+            # gets a structured error envelope rather than a raw string.
+            provider = getattr(e, "provider", None)
+            reason = getattr(e, "reason", "denied")
+            auth = getattr(e, "auth", "api_key")
+            # Normalize "oauth2" -> "oauth" so the event type aligns with
+            # the existing CloudEvents naming (``credential.oauth.connected``,
+            # ``credential.oauth.disconnected``, ``credential.oauth.validated``).
+            auth_kind = "oauth" if auth == "oauth2" else auth
+            workflow_id: Optional[str] = None
+            if isinstance(context.raw, dict):
+                workflow_id = context.raw.get("workflow_id")
+            if provider:
+                try:
+                    from services.status_broadcaster import get_status_broadcaster
+
+                    broadcaster = get_status_broadcaster()
+                    await broadcaster.broadcast_credential_event(
+                        event_type=f"credential.{auth_kind}.runtime_failed",
+                        provider=provider,
+                        workflow_id=workflow_id,
+                        reason=reason,
+                        node_id=node_id,
+                        error=str(e),
+                    )
+                except Exception:
+                    # Broadcast failure must never mask the original error.
+                    logger.debug(
+                        "[%s] failed to broadcast credential runtime failure for %s",
+                        self.type,
+                        provider,
+                        exc_info=True,
+                    )
+            extra: Optional[Dict[str, Any]] = None
+            if provider:
+                extra = {
+                    "credential": {
+                        "provider": provider,
+                        "reason": reason,
+                        "remediation": "add_key" if reason == "missing" else "reconnect",
+                    }
+                }
             return self._wrap_error(
-                start_time=start_time, error=str(e), error_type="PermissionDeniedError"
+                start_time=start_time,
+                error=str(e),
+                error_type="PermissionDeniedError",
+                extra=extra,
             )
         except NodeUserError as e:
             # Expected, user-correctable: log a single WARN line so it
@@ -312,9 +471,7 @@ class BaseNode:
             # LLM gets the message in the structured response and can
             # retry with corrected input.
             logger.warning("[%s] %s op %s: %s", self.type, op_name, type(e).__name__, e)
-            return self._wrap_error(
-                start_time=start_time, error=str(e), error_type="NodeUserError"
-            )
+            return self._wrap_error(start_time=start_time, error=str(e), error_type="NodeUserError")
         except Exception as e:
             logger.exception("[%s] operation %s failed", self.type, op_name)
             return self._wrap_error(start_time=start_time, error=str(e), error_type=type(e).__name__)
@@ -383,14 +540,15 @@ class BaseNode:
             # is expected to be empty.
             if not self.credentials:
                 raise RuntimeError(
-                    f"Node {self.type} op {spec.name} has routing but no "
-                    "credentials declared — routing needs a Connection."
+                    f"Node {self.type} op {spec.name} has routing but no " "credentials declared — routing needs a Connection."
                 )
             cred = self.credentials[0]
             conn = ctx.connection(cred.id)
             try:
                 return await execute_routing(
-                    spec.routing, params=params_obj.model_dump(), connection=conn,
+                    spec.routing,
+                    params=params_obj.model_dump(),
+                    connection=conn,
                 )
             finally:
                 await conn.aclose()
@@ -413,24 +571,40 @@ class BaseNode:
         }
 
     def _wrap_error(
-        self, *, start_time: float, error: str, error_type: str = "Error"
+        self,
+        *,
+        start_time: float,
+        error: str,
+        error_type: str = "Error",
+        extra: Optional[Dict[str, Any]] = None,
     ) -> Dict[str, Any]:
-        return {
+        envelope: Dict[str, Any] = {
             "success": False,
             "error": error,
             "error_type": error_type,
             "execution_time": round(time.time() - start_time, 3),
             "timestamp": datetime.now(timezone.utc).isoformat(),
         }
+        if extra:
+            envelope.update(extra)
+        return envelope
 
     # ---- Temporal ---------------------------------------------------------
 
     @classmethod
     def as_activity(cls):
         """Wrap this node as a ``@activity.defn`` callable for Temporal
-        worker registration (11.F). Uses a stable activity name:
+        worker registration (F4.A). Stable activity name:
         ``node.{type}.v{version}``.
 
+        Accepts the same ``context`` dict shape as the legacy
+        ``execute_node_activity`` so the orchestrator can swap by name
+        without reshaping the payload. Delegates to
+        ``workflow_service.execute_node(...)`` — same execution pipeline
+        the WebSocket path uses — so status broadcasts, parameter
+        fetching, NodeContext build, and error handling all match. The
+        Temporal worker shares the FastAPI process, so direct DI works.
+
         Returns the decorated async function; the worker collects these
         into ``activities=[...]``.
         """
@@ -439,17 +613,122 @@ class BaseNode:
         activity_name = f"node.{cls.type}.v{cls.version}"
 
         @activity.defn(name=activity_name)
-        async def _node_activity(payload: Dict[str, Any]) -> Dict[str, Any]:
-            # Temporal lives in another process — rebuild NodeContext.
-            context_dict = payload.get("context", {})
-            instance = cls()
-            ctx = NodeContext.from_legacy(
-                node_id=payload["node_id"],
-                node_type=cls.type,
-                context=context_dict,
-                connection_factory=_make_connection_factory(cls, context_dict),
+        async def _node_activity(context: Dict[str, Any]) -> Dict[str, Any]:
+            from datetime import datetime
+            from core.container import container
+            from services.status_broadcaster import get_status_broadcaster
+
+            node_id = context["node_id"]
+            workflow_id = context.get("workflow_id")
+            broadcaster = get_status_broadcaster()
+
+            # Pre-executed trigger nodes — return cached output without dispatching.
+            if context.get("pre_executed"):
+                activity.logger.debug(f"Node {node_id} pre-executed; passthrough")
+                result = {
+                    "success": True,
+                    "node_id": node_id,
+                    "node_type": cls.type,
+                    "result": context.get("trigger_output", {}),
+                    "pre_executed": True,
+                    "timestamp": datetime.now().isoformat(),
+                }
+                await broadcaster.update_node_status(
+                    node_id,
+                    "success",
+                    result,
+                    workflow_id=workflow_id,
+                )
+                return result
+
+            # Disabled nodes — skip.
+            node_data = context.get("node_data", {})
+            if node_data.get("disabled"):
+                activity.logger.debug(f"Node {node_id} disabled; skipping")
+                result = {
+                    "success": True,
+                    "node_id": node_id,
+                    "node_type": cls.type,
+                    "skipped": True,
+                    "reason": "disabled",
+                    "timestamp": datetime.now().isoformat(),
+                }
+                await broadcaster.update_node_status(
+                    node_id,
+                    "skipped",
+                    {"disabled": True},
+                    workflow_id=workflow_id,
+                )
+                return result
+
+            # Broadcast executing — UI cyan-glow.
+            await broadcaster.update_node_status(
+                node_id,
+                "executing",
+                {"node_type": cls.type},
+                workflow_id=workflow_id,
             )
-            return await instance.execute(payload["node_id"], payload["parameters"], ctx)
+
+            try:
+                # Heartbeat the long-running side of the pipeline.
+                activity.heartbeat(f"Executing {cls.type}: {node_id}")
+
+                # Delegate to the same pipeline the WS handler uses. Parameters
+                # are read from DB inside execute_node (handler-specific). The
+                # legacy execute_node_activity does this via a WS roundtrip;
+                # per-type activities skip the loopback because the worker
+                # shares the FastAPI process.
+                workflow_service = container.workflow_service()
+                result = await workflow_service.execute_node(
+                    node_id=node_id,
+                    node_type=cls.type,
+                    parameters=node_data,
+                    nodes=context.get("nodes", []),
+                    edges=context.get("edges", []),
+                    session_id=context.get("session_id", "default"),
+                    workflow_id=workflow_id,
+                    outputs=context.get("inputs", {}),
+                )
+
+                result["node_id"] = node_id
+                result["node_type"] = cls.type
+                result["timestamp"] = datetime.now().isoformat()
+
+                if result.get("success"):
+                    activity.logger.info(f"Node {node_id} succeeded")
+                    await broadcaster.update_node_status(
+                        node_id,
+                        "success",
+                        result.get("result", {}),
+                        workflow_id=workflow_id,
+                    )
+                    await broadcaster.update_node_output(
+                        node_id,
+                        result.get("result", {}),
+                        workflow_id=workflow_id,
+                    )
+                else:
+                    activity.logger.warning(f"Node {node_id} failed: {result.get('error')}")
+                    await broadcaster.update_node_status(
+                        node_id,
+                        "error",
+                        {"error": result.get("error")},
+                        workflow_id=workflow_id,
+                    )
+
+                activity.heartbeat(f"Node {node_id} completed")
+                return result
+
+            except Exception as e:
+                error_msg = f"{type(e).__name__}: {e}"
+                activity.logger.error(f"Node {node_id} crashed: {error_msg}")
+                await broadcaster.update_node_status(
+                    node_id,
+                    "error",
+                    {"error": error_msg},
+                    workflow_id=workflow_id,
+                )
+                raise
 
         return _node_activity
 
@@ -457,6 +736,7 @@ class BaseNode:
 # ---------------------------------------------------------------------------
 # Connection factory — avoids circular import with NodeContext.
 
+
 def _make_connection_factory(
     node_cls: Type[BaseNode],
     context: Dict[str, Any],
@@ -475,7 +755,10 @@ def _make_connection_factory(
                 f"but tried to use it. Add it to the `credentials` class attribute."
             )
         return Connection(
-            cred_cls, user_id=user_id, session_id=session_id, node_id=node_id,
+            cred_cls,
+            user_id=user_id,
+            session_id=session_id,
+            node_id=node_id,
         )
 
     return factory

package/server/services/plugin/connection.py

@@ -106,16 +106,21 @@ class Connection:
         if _retry_on_auth and response.status_code in (401, 403):
             logger.debug(
                 "[Connection] auth retry for %s (%s) status=%s",
-                self.credential_id, method, response.status_code,
+                self.credential_id,
+                method,
+                response.status_code,
             )
             await self.refresh()
             secrets = await self.credentials()
-            req_retry = self._cred_cls.inject(secrets, {
-                "headers": dict(headers or {}),
-                "params": dict(params or {}),
-                **({"json": json} if json is not None else {}),
-                **({"data": data} if data is not None else {}),
-            })
+            req_retry = self._cred_cls.inject(
+                secrets,
+                {
+                    "headers": dict(headers or {}),
+                    "params": dict(params or {}),
+                    **({"json": json} if json is not None else {}),
+                    **({"data": data} if data is not None else {}),
+                },
+            )
             response = await client.request(method, url, **req_retry)
 
         return response