machinaos 0.0.78 → 0.0.80

package/server/nodes/_visuals.py

@@ -1,25 +1,36 @@
 """Central handler for node visuals (icon + color).
 
-Every node plugin's icon and color live in ``visuals.json`` next to
-this module. The base ``BaseNode`` class consults
-:func:`get_icon` / :func:`get_color` at registration time when a
-subclass doesn't set the class attribute itself.
-
-Single source of truth — change the icon for ``aiAgent`` here once
-and every consumer (palette, parameter panel, canvas) picks it up
-the next time the backend NodeSpec cache rehydrates.
-
-Adding a new node: add an entry to ``visuals.json`` (or rely on the
-empty default — the icon resolver falls back to the empty string,
-which the frontend renders as a placeholder). Node files do NOT
-declare ``icon`` or ``color`` themselves.
+Two icon sources co-exist by design (per RFC §6.5):
+
+1. **Per-plugin ``icon.svg``** co-located with the plugin folder
+   (e.g. ``server/nodes/telegram/icon.svg``). Resolved at runtime via
+   :func:`get_plugin_icon_path`. Preferred for new plugins; served
+   by ``GET /api/schemas/nodes/{type}/icon`` (see ``routers/schemas.py``).
+
+2. **``visuals.json``** for emoji entries and library-icon
+   (``lobehub:<brand>``) entries that don't map to a file. Resolved
+   via :func:`get_icon` / :func:`get_color`.
+
+``BaseNode._metadata_dict`` checks the per-folder path first and
+falls back to ``visuals.json``. The frontend resolver dispatches by
+the wire-format prefix (URL paths route to ``<img>``; ``asset:``,
+``lobehub:``, emoji each have their own branch).
+
+Adding a new node:
+- Drop ``icon.svg`` into the plugin folder, OR
+- Add an entry to ``visuals.json`` (emoji or ``lobehub:<brand>``).
+
+Node files do NOT declare ``icon`` or ``color`` themselves.
 """
 
 from __future__ import annotations
 
+import inspect
 import json
 from pathlib import Path
-from typing import Dict
+from typing import Dict, Optional
+
+from services.plugin.identifiers import is_valid_node_type
 
 
 _VISUALS_PATH = Path(__file__).resolve().parent / "visuals.json"
@@ -59,6 +70,10 @@ def get_color(node_type: str) -> str:
 
     Color strings are arbitrary CSS color literals — the canvas node
     components apply them as-is to gradients, borders, and badges.
+
+    Falls back to ``visuals.json`` for legacy entries that haven't been
+    migrated to per-plugin ``meta.json`` yet (F2 cleanup of the plugin
+    authoring RFC).
     """
     entry = _VISUALS.get(node_type)
     if not entry:
@@ -66,6 +81,123 @@ def get_color(node_type: str) -> str:
     return str(entry.get("color", ""))
 
 
+def get_plugin_meta(node_type: str, key: Optional[str] = None) -> Optional[dict | str]:
+    """Read the plugin's co-located ``meta.json`` file.
+
+    Same folder-resolution path as :func:`get_plugin_icon_path` — uses
+    :func:`inspect.getfile` on the plugin class to locate the folder,
+    then loads ``meta.json`` if present.
+
+    Returns the value at ``key`` (str) when given, the whole dict when
+    ``key`` is ``None``, or ``None`` when the file or key is absent.
+    Callers fall back to :func:`get_color` / other ``visuals.json`` keys
+    for legacy entries.
+
+    Per RFC §6.2 / F2 of the deferred follow-ups: ``meta.json`` mirrors
+    ``icon.svg`` co-location so a plugin's entire visual surface area
+    lives in one folder. The previous central ``visuals.json`` color
+    map remains as a transitional fallback for entries without a
+    per-plugin ``meta.json``.
+    """
+    from services.node_registry import get_node_class
+
+    if not is_valid_node_type(node_type):
+        return None
+    cls = get_node_class(node_type)
+    if cls is None:
+        return None
+    try:
+        plugin_dir = Path(inspect.getfile(cls)).resolve().parent
+    except (TypeError, OSError):
+        return None
+    meta_path = plugin_dir / "meta.json"
+    if not meta_path.exists():
+        return None
+    try:
+        with meta_path.open("r", encoding="utf-8") as fh:
+            data = json.load(fh)
+    except (OSError, json.JSONDecodeError):
+        return None
+    if not isinstance(data, dict):
+        return None
+    if key is None:
+        return data
+    value = data.get(key)
+    return None if value is None else str(value)
+
+
+def get_plugin_icon_path(node_type: str, variant: str = "light") -> Optional[Path]:
+    """Return the on-disk path to a plugin's co-located icon SVG.
+
+    ``variant="dark"`` looks for the dark-mode SVG first and falls back
+    to the light variant when no dark file exists.
+
+    Resolution chain (first hit wins):
+    1. **Per-node-type icon** — ``<plugin_dir>/icon_<node_type>.svg``
+       (or ``icon_<node_type>.dark.svg`` for ``variant="dark"``).
+       Lets multi-node-per-plugin folders (whatsapp / telegram / stripe)
+       serve distinct icons per node type WITHOUT splitting the folder.
+       e.g. ``server/nodes/whatsapp/icon_whatsappSend.svg`` serves the
+       ``whatsappSend`` node while sharing the folder with
+       ``whatsappReceive`` and ``whatsappDb``.
+    2. **Shared plugin icon** — ``<plugin_dir>/icon.svg`` (or
+       ``icon.dark.svg``). The original Phase 9 contract; one icon for
+       the whole folder.
+
+    Folder resolution itself:
+    1. Look up the plugin class via :func:`services.node_registry.get_node_class`.
+    2. Resolve the class's source file via ``inspect.getfile``.
+    3. The plugin folder is the file's parent directory — equally
+       correct for single-file plugins (``server/nodes/tool/calc.py``
+       → parent ``server/nodes/tool/``) and self-contained-folder
+       plugins (``server/nodes/telegram/telegram_send.py`` → parent
+       ``server/nodes/telegram/``).
+
+    Returns ``None`` when the type is unknown or no icon SVG is
+    present — caller falls back to :func:`get_icon` (visuals.json).
+    """
+    # Local import to avoid a top-level circular dep (node_registry
+    # itself doesn't import _visuals, but plugin modules import both).
+    from services.node_registry import get_node_class
+
+    if not is_valid_node_type(node_type):
+        return None
+    cls = get_node_class(node_type)
+    if cls is None:
+        return None
+    try:
+        plugin_dir = Path(inspect.getfile(cls)).resolve().parent
+    except (TypeError, OSError):
+        return None
+
+    # Candidate filenames in resolution order. Per-node-type first so
+    # multi-node folders can override the shared icon for specific node
+    # types. ``node_type`` is already constrained to ``NODE_TYPE_PATTERN``
+    # (``^[A-Za-z_][A-Za-z0-9_]*$``) by ``is_valid_node_type`` above --
+    # no path separators possible -- but we resolve the candidate and
+    # call ``Path.relative_to(plugin_dir)`` (which raises ``ValueError``
+    # on traversal). CodeQL's taint tracker recognises
+    # ``Path.relative_to`` as a ``py/path-injection`` sanitizer; the
+    # ``is_relative_to`` predicate it does not.
+    candidates: list[str] = []
+    if variant == "dark":
+        candidates.append(f"icon_{node_type}.dark.svg")
+    candidates.append(f"icon_{node_type}.svg")
+    if variant == "dark":
+        candidates.append("icon.dark.svg")
+    candidates.append("icon.svg")
+
+    for name in candidates:
+        candidate = (plugin_dir / name).resolve()
+        try:
+            candidate.relative_to(plugin_dir)
+        except ValueError:
+            continue
+        if candidate.exists():
+            return candidate
+    return None
+
+
 def get_skill(node_type: str) -> str:
     """Return the teaching skill folder name registered for ``node_type``.
 

package/server/nodes/agent/_events.py

@@ -0,0 +1,124 @@
+"""CloudEvents broadcaster wrappers for agent task delegation.
+
+Plugin-folder-owned wrappers around the cross-cutting
+``WorkflowEvent.task_completed`` factory. The factory itself stays in
+``services/events/envelope.py`` per RFC §6.4 — it's parametrised by
+``task_id`` + ``agent`` + ``status`` and uniformly applies to every
+delegated agent task, not a single-plugin shape. The broadcaster
+wrappers below live with the agent plugin folder so the 3 callsites in
+``services/handlers/tools.py`` (the fire-and-forget delegation
+dispatcher) import from ``nodes.agent._events`` rather than building
+the wire frame inline.
+
+Delivery: a single ``dispatch.emit`` call. ``dispatch.emit`` Signals
+running :class:`TriggerListenerWorkflow` consumers via Temporal
+Visibility AND broadcasts the same envelope to in-process WS clients on
+the ``task_completed`` wire-routing key — one canonical path. Pre-Wave-13
+this also called ``broadcaster.send_custom_event`` for the legacy
+collector path; that's dead since taskTrigger is canary-registered and
+the deployment manager skips ``setup_event_trigger`` for canary types.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+# Outer wire-routing key. FE consumers (if any) and the legacy
+# back-compat receipt path still switch on this string; the inner
+# envelope carries ``com.machinaos.agent.task.completed``.
+_WIRE_ROUTING_KEY = "task_completed"
+
+
+async def broadcast_agent_task_completed(
+    *,
+    task_id: str,
+    agent_name: str,
+    agent_node_id: str,
+    parent_node_id: str,
+    workflow_id: Optional[str] = None,
+    result: Optional[str] = None,
+) -> None:
+    """Broadcast a delegated agent task completing successfully."""
+    await _broadcast_task_event(
+        task_id=task_id,
+        status="completed",
+        agent_name=agent_name,
+        agent_node_id=agent_node_id,
+        parent_node_id=parent_node_id,
+        workflow_id=workflow_id,
+        result=result,
+    )
+
+
+async def broadcast_agent_task_failed(
+    *,
+    task_id: str,
+    agent_name: str,
+    agent_node_id: str,
+    parent_node_id: str,
+    workflow_id: Optional[str] = None,
+    error: str,
+) -> None:
+    """Broadcast a delegated agent task failing."""
+    await _broadcast_task_event(
+        task_id=task_id,
+        status="error",
+        agent_name=agent_name,
+        agent_node_id=agent_node_id,
+        parent_node_id=parent_node_id,
+        workflow_id=workflow_id,
+        error=error,
+    )
+
+
+async def _broadcast_task_event(
+    *,
+    task_id: str,
+    status: str,  # "completed" | "error"
+    agent_name: str,
+    agent_node_id: str,
+    parent_node_id: str,
+    workflow_id: Optional[str] = None,
+    result: Optional[str] = None,
+    error: Optional[str] = None,
+) -> None:
+    """Single delivery path: build the envelope, route through
+    :func:`services.events.dispatch.emit`.
+
+    ``emit`` does two things in one call: (a) Visibility query for
+    running :class:`TriggerListenerWorkflow` consumers tagged with
+    ``EventType='com.machinaos.agent.task.completed'`` and signals each;
+    (b) direct in-process WS broadcast on the ``task_completed`` wire
+    key so any FE consumers receive the envelope. Payload shape in
+    ``data`` is exactly what the taskTrigger filter reads.
+    """
+    from services.events.dispatch import emit
+    from services.events.envelope import WorkflowEvent
+
+    payload: dict[str, Any] = {
+        "task_id": task_id,
+        "status": status,
+        "agent_name": agent_name,
+        "agent_node_id": agent_node_id,
+        "parent_node_id": parent_node_id,
+        "workflow_id": workflow_id,
+    }
+    if status == "completed" and result is not None:
+        payload["result"] = result
+    elif status == "error" and error is not None:
+        payload["error"] = error
+
+    envelope = WorkflowEvent.task_completed(
+        task_id=task_id,
+        status="completed" if status == "completed" else "error",
+        agent=agent_name,
+        data=payload,
+    )
+    await emit(envelope, wire_routing_key=_WIRE_ROUTING_KEY)
+
+
+__all__ = [
+    "broadcast_agent_task_completed",
+    "broadcast_agent_task_failed",
+]

package/server/nodes/agent/_handles.py

@@ -16,13 +16,13 @@ def std_agent_handles() -> tuple:
     of the 20 agent variants. Returned as a tuple so the BaseNode
     `handles` class attribute is immutable."""
     return (
-        {"name": "input-skill",  "kind": "input",  "position": "bottom", "offset": "25%", "label": "Skill",  "role": "skill"},
-        {"name": "input-tools",  "kind": "input",  "position": "bottom", "offset": "75%", "label": "Tool",   "role": "tools"},
-        {"name": "input-main",   "kind": "input",  "position": "left",   "offset": "25%", "label": "Input",  "role": "main"},
-        {"name": "input-memory", "kind": "input",  "position": "left",   "offset": "50%", "label": "Memory", "role": "memory"},
-        {"name": "input-task",   "kind": "input",  "position": "left",   "offset": "75%", "label": "Task",   "role": "task"},
-        {"name": "output-main",  "kind": "output", "position": "right",  "offset": "50%", "label": "Output", "role": "main"},
-        {"name": "output-top",   "kind": "output", "position": "top",                     "label": "Output", "role": "main"},
+        {"name": "input-skill", "kind": "input", "position": "bottom", "offset": "25%", "label": "Skill", "role": "skill"},
+        {"name": "input-tools", "kind": "input", "position": "bottom", "offset": "75%", "label": "Tool", "role": "tools"},
+        {"name": "input-main", "kind": "input", "position": "left", "offset": "25%", "label": "Input", "role": "main"},
+        {"name": "input-memory", "kind": "input", "position": "left", "offset": "50%", "label": "Memory", "role": "memory"},
+        {"name": "input-task", "kind": "input", "position": "left", "offset": "75%", "label": "Task", "role": "task"},
+        {"name": "output-main", "kind": "output", "position": "right", "offset": "50%", "label": "Output", "role": "main"},
+        {"name": "output-top", "kind": "output", "position": "top", "label": "Output", "role": "main"},
     )
 
 
@@ -30,26 +30,12 @@ def team_lead_agent_handles() -> tuple:
     """Skill / Tool / Teammates bottom + Memory/Task/Input left + Outputs.
     Used by orchestrator_agent and ai_employee."""
     return (
-        {"name": "input-skill",     "kind": "input",  "position": "bottom", "offset": "20%", "label": "Skill", "role": "skill"},
-        {"name": "input-tools",     "kind": "input",  "position": "bottom", "offset": "50%", "label": "Tool",  "role": "tools"},
-        {"name": "input-teammates", "kind": "input",  "position": "bottom", "offset": "80%", "label": "Team",  "role": "teammates"},
-        {"name": "input-main",      "kind": "input",  "position": "left",   "offset": "25%", "label": "Input", "role": "main"},
-        {"name": "input-memory",    "kind": "input",  "position": "left",   "offset": "50%", "label": "Memory","role": "memory"},
-        {"name": "input-task",      "kind": "input",  "position": "left",   "offset": "75%", "label": "Task",  "role": "task"},
-        {"name": "output-main",     "kind": "output", "position": "right",  "offset": "50%", "label": "Output","role": "main"},
-        {"name": "output-top",      "kind": "output", "position": "top",                     "label": "Output","role": "main"},
-    )
-
-
-def deep_agent_handles() -> tuple:
-    """Skill / Teammates / Tool bottom — used by deep_agent only."""
-    return (
-        {"name": "input-skill",     "kind": "input",  "position": "bottom", "offset": "30%", "label": "Skill", "role": "skill"},
-        {"name": "input-teammates", "kind": "input",  "position": "bottom", "offset": "55%", "label": "Team",  "role": "teammates"},
-        {"name": "input-tools",     "kind": "input",  "position": "bottom", "offset": "80%", "label": "Tool",  "role": "tools"},
-        {"name": "input-main",      "kind": "input",  "position": "left",   "offset": "25%", "label": "Input", "role": "main"},
-        {"name": "input-memory",    "kind": "input",  "position": "left",   "offset": "50%", "label": "Memory","role": "memory"},
-        {"name": "input-task",      "kind": "input",  "position": "left",   "offset": "75%", "label": "Task",  "role": "task"},
-        {"name": "output-main",     "kind": "output", "position": "right",  "offset": "50%", "label": "Output","role": "main"},
-        {"name": "output-top",      "kind": "output", "position": "top",                     "label": "Output","role": "main"},
+        {"name": "input-skill", "kind": "input", "position": "bottom", "offset": "20%", "label": "Skill", "role": "skill"},
+        {"name": "input-tools", "kind": "input", "position": "bottom", "offset": "50%", "label": "Tool", "role": "tools"},
+        {"name": "input-teammates", "kind": "input", "position": "bottom", "offset": "80%", "label": "Team", "role": "teammates"},
+        {"name": "input-main", "kind": "input", "position": "left", "offset": "25%", "label": "Input", "role": "main"},
+        {"name": "input-memory", "kind": "input", "position": "left", "offset": "50%", "label": "Memory", "role": "memory"},
+        {"name": "input-task", "kind": "input", "position": "left", "offset": "75%", "label": "Task", "role": "task"},
+        {"name": "output-main", "kind": "output", "position": "right", "offset": "50%", "label": "Output", "role": "main"},
+        {"name": "output-top", "kind": "output", "position": "top", "label": "Output", "role": "main"},
     )

package/server/nodes/agent/_inline.py

@@ -22,7 +22,7 @@ to ``ai_service.execute_agent(...)`` or ``ai_service.execute_chat_agent(...)``.
 
 from __future__ import annotations
 
-from typing import Any, Dict, Optional
+from typing import Any, Dict
 
 from core.logging import get_logger
 from services.plugin.edge_walker import (
@@ -60,7 +60,10 @@ async def prepare_agent_call(
         parameters = {**parameters, "api_key": raw_params["api_key"]}
 
     memory_data, skill_data, tool_data, input_data, task_data = await collect_agent_connections(
-        node_id, context, database, log_prefix=log_prefix,
+        node_id,
+        context,
+        database,
+        log_prefix=log_prefix,
     )
 
     # Step 1: task-context injection + tool-strip.
@@ -76,8 +79,7 @@ async def prepare_agent_call(
             original_tool_count = len(tool_data)
             tool_data = []
             logger.info(
-                f"{log_prefix} Stripped ALL {original_tool_count} tools for "
-                "task completion handling",
+                f"{log_prefix} Stripped ALL {original_tool_count} tools for " "task completion handling",
             )
 
     # Step 2: auto-prompt fallback.
@@ -113,31 +115,34 @@ async def prepare_agent_call(
                 tm_id = tm["node_id"]
                 child_tools = []
                 for child_edge in all_edges:
-                    if (
-                        child_edge.get("target") != tm_id
-                        or child_edge.get("targetHandle") != "input-tools"
-                    ):
+                    if child_edge.get("target") != tm_id or child_edge.get("targetHandle") != "input-tools":
                         continue
                     child_id = child_edge.get("source")
                     child_node = next(
-                        (n for n in all_nodes if n.get("id") == child_id), None,
+                        (n for n in all_nodes if n.get("id") == child_id),
+                        None,
                     )
                     if not child_node:
                         continue
-                    child_tools.append({
-                        "node_id": child_id,
-                        "node_type": child_node.get("type"),
-                        "label": child_node.get("data", {}).get(
-                            "label", child_node.get("type"),
-                        ),
-                    })
-                tool_data.append({
-                    "node_id": tm_id,
-                    "node_type": tm["node_type"],
-                    "label": tm["label"],
-                    "parameters": tm.get("parameters", {}),
-                    "child_tools": child_tools,
-                })
+                    child_tools.append(
+                        {
+                            "node_id": child_id,
+                            "node_type": child_node.get("type"),
+                            "label": child_node.get("data", {}).get(
+                                "label",
+                                child_node.get("type"),
+                            ),
+                        }
+                    )
+                tool_data.append(
+                    {
+                        "node_id": tm_id,
+                        "node_type": tm["node_type"],
+                        "label": tm["label"],
+                        "parameters": tm.get("parameters", {}),
+                        "child_tools": child_tools,
+                    }
+                )
             logger.info(f"[Teams] Added {len(teammates)} teammates as delegation tools")
 
     from services.status_broadcaster import get_status_broadcaster
@@ -152,5 +157,3 @@ async def prepare_agent_call(
         "context": context,
         "database": database,
     }
-
-

package/server/nodes/agent/_specialized.py

@@ -1,12 +1,12 @@
 """Specialized agent base — subclass + set 5 attrs to mint a new agent.
 
-13 specialized agents (android / coding / web / task / social / travel
-/ tool / productivity / payments / consumer / autonomous / rlm /
-claude_code) all share the LangGraph-via-handle_chat_agent execution
-path. The only differences are display name, icon, colour, subtitle,
-description. Each agent gets its own file under ``nodes/agent/`` so
-the user can find ``android_agent.py`` directly — but the body lives
-here so changing the dispatch path is a one-file edit.
+All specialized agents (android / coding / web / task / social / travel
+/ tool / productivity / payments / consumer / autonomous) share the
+``handle_chat_agent`` execution path. The only differences are display
+name, icon, colour, subtitle, description. Each agent gets its own file
+under ``nodes/agent/`` so the user can find ``android_agent.py``
+directly — but the body lives here so changing the dispatch path is a
+one-file edit.
 """
 
 from __future__ import annotations
@@ -36,14 +36,23 @@ class SpecializedAgentParams(BaseModel):
         },
     )
     provider: Literal[
-        "openai", "anthropic", "gemini", "openrouter",
-        "groq", "cerebras", "deepseek", "kimi", "mistral",
+        "openai",
+        "anthropic",
+        "gemini",
+        "openrouter",
+        "groq",
+        "cerebras",
+        "deepseek",
+        "kimi",
+        "mistral",
         # Local-server providers — see ai_agent.Params for the proxy_url
         # rationale. Same fix; same reason.
-        "ollama", "lmstudio",
+        "ollama",
+        "lmstudio",
     ] = "openai"
     model: str = Field(
-        default="", json_schema_extra={"placeholder": "Select a model..."},
+        default="",
+        json_schema_extra={"placeholder": "Select a model..."},
     )
     system_message: Optional[str] = Field(
         default="You are a helpful assistant",
@@ -54,14 +63,18 @@ class SpecializedAgentParams(BaseModel):
     # default=None so an unset value falls through to ``agent.default_temperature``
     # in server/config/llm_defaults.json (resolved by _resolve_temperature).
     temperature: Optional[float] = Field(
-        default=None, ge=0.0, le=2.0,
+        default=None,
+        ge=0.0,
+        le=2.0,
         json_schema_extra={"group": "options"},
     )
     # default=None so an unset value is absent from the dumped dict and the
     # backend (_resolve_max_tokens) falls through to the per-model default
     # in server/config/llm_defaults.json instead of being silently capped.
     max_tokens: Optional[int] = Field(
-        default=None, ge=1, le=200000,
+        default=None,
+        ge=1,
+        le=200000,
         json_schema_extra={"group": "options"},
     )
 
@@ -117,9 +130,11 @@ class SpecializedAgentBase(ActionNode, abstract=True):
         ai_service = get_ai_service()
         database = get_database()
         kwargs = await prepare_agent_call(
-            node_id=ctx.node_id, node_type=self.type,
+            node_id=ctx.node_id,
+            node_type=self.type,
             parameters=params.model_dump(),
-            context=ctx.raw, database=database,
+            context=ctx.raw,
+            database=database,
             log_prefix=f"[{self.type}]",
         )
         response = await ai_service.execute_chat_agent(ctx.node_id, **kwargs)

package/server/nodes/agent/{ai_agent.py → ai_agent/__init__.py}

@@ -1,8 +1,8 @@
-"""AI Agent — Wave 11.C migration (LangGraph agent).
+"""AI Agent — Wave 11.C migration (tool-calling agent).
 
-Tool-calling LangGraph agent with memory, skills, and iterative
+Tool-calling agent with memory, skills, and iterative
 reasoning. Delegates execution to ``handlers/ai.handle_ai_agent`` —
-that body owns the LangGraph graph construction + tool binding +
+that body owns the agent-loop construction + tool binding +
 streaming + memory persistence + delegation.
 """
 
@@ -14,7 +14,7 @@ from pydantic import BaseModel, ConfigDict, Field
 
 from services.plugin import ActionNode, NodeContext, Operation, TaskQueue
 
-from ._handles import STD_AGENT_HINTS, std_agent_handles
+from .._handles import STD_AGENT_HINTS, std_agent_handles
 
 
 class AIAgentParams(BaseModel):
@@ -39,17 +39,26 @@ class AIAgentParams(BaseModel):
         },
     )
     provider: Literal[
-        "openai", "anthropic", "gemini", "openrouter",
-        "groq", "cerebras", "deepseek", "kimi", "mistral",
+        "openai",
+        "anthropic",
+        "gemini",
+        "openrouter",
+        "groq",
+        "cerebras",
+        "deepseek",
+        "kimi",
+        "mistral",
         # Local-server providers — agent execution reads
         # ``{provider}_proxy`` to point the LangChain client at the
         # user's localhost server. Without these entries the dropdown
         # silently falls back to ``"openai"`` and execute_agent ends
         # up calling api.openai.com instead.
-        "ollama", "lmstudio",
+        "ollama",
+        "lmstudio",
     ] = "openai"
     model: str = Field(
-        default="", json_schema_extra={"placeholder": "Select a model..."},
+        default="",
+        json_schema_extra={"placeholder": "Select a model..."},
     )
     system_message: Optional[str] = Field(
         default="You are a helpful assistant",
@@ -60,14 +69,18 @@ class AIAgentParams(BaseModel):
     # default=None so an unset value falls through to ``agent.default_temperature``
     # in server/config/llm_defaults.json (resolved by _resolve_temperature).
     temperature: Optional[float] = Field(
-        default=None, ge=0.0, le=2.0,
+        default=None,
+        ge=0.0,
+        le=2.0,
         json_schema_extra={"numberStepSize": 0.1, "group": "options"},
     )
     # default=None so an unset value is absent from the dumped dict and the
     # backend (_resolve_max_tokens) falls through to the per-model default
     # in server/config/llm_defaults.json instead of being silently capped.
     max_tokens: Optional[int] = Field(
-        default=None, ge=1, le=200000,
+        default=None,
+        ge=1,
+        le=200000,
         json_schema_extra={"group": "options"},
     )
 
@@ -98,10 +111,11 @@ class AIAgentOutput(BaseModel):
 class AIAgentNode(ActionNode):
     type = "aiAgent"
     display_name = "AI Agent"
-    subtitle = "LangGraph Agent"
+    subtitle = "AI Agent"
     group = ("agent",)
-    description = "LangGraph agent with tool calling, memory, and iterative reasoning"
+    description = "AI agent with tool calling, memory, and iterative reasoning"
     component_kind = "agent"
+    tool_name = "delegate_to_ai_agent"
     handles = std_agent_handles()
     ui_hints = STD_AGENT_HINTS
     annotations = {"destructive": False, "readonly": False, "open_world": True}
@@ -117,19 +131,21 @@ class AIAgentNode(ActionNode):
         Pre-dispatch flow (edge walk + task inject + prompt fallback)
         lives in :mod:`nodes.agent._inline`. This method just calls
         ``AIService.execute_agent`` with the prepared kwargs. The
-        underlying LangGraph orchestration + tool binding + memory
-        I/O + streaming hooks stay in AIService.
+        underlying agent loop + tool binding + memory I/O + streaming
+        hooks stay in AIService.
         """
         from services.plugin.deps import get_ai_service, get_database
 
-        from ._inline import prepare_agent_call
+        from .._inline import prepare_agent_call
 
         ai_service = get_ai_service()
         database = get_database()
         kwargs = await prepare_agent_call(
-            node_id=ctx.node_id, node_type=self.type,
+            node_id=ctx.node_id,
+            node_type=self.type,
             parameters=params.model_dump(),
-            context=ctx.raw, database=database,
+            context=ctx.raw,
+            database=database,
             log_prefix="[AI Agent]",
         )
         # ``execute_agent`` raises ``NodeUserError`` directly for typed