machinaos 0.0.78 → 0.0.80

package/server/services/plugin/credential.py

@@ -62,9 +62,7 @@ class ProbeResult:
     extra: Dict[str, Any] = field(default_factory=dict)
 
 
-def classify_credential_error(
-    exc: BaseException, *, display_name: str
-) -> ProbeResult:
+def classify_credential_error(exc: BaseException, *, display_name: str) -> ProbeResult:
     """Map a transport / SDK exception to a typed ``ProbeResult``.
 
     Single source of truth for credential-error → user-message mapping.
@@ -169,10 +167,7 @@ class Credential:
                 # Idempotent on re-import — only warn on genuine conflict.
                 existing = CREDENTIAL_REGISTRY[cls.id]
                 if existing.__qualname__ != cls.__qualname__:
-                    raise ValueError(
-                        f"Credential id '{cls.id}' registered by "
-                        f"{existing.__qualname__} and now by {cls.__qualname__}"
-                    )
+                    raise ValueError(f"Credential id '{cls.id}' registered by " f"{existing.__qualname__} and now by {cls.__qualname__}")
             CREDENTIAL_REGISTRY[cls.id] = cls
 
     @classmethod
@@ -183,6 +178,63 @@ class Credential:
         """
         raise NotImplementedError
 
+    # ---- F7: credential icon resolution -----------------------------
+    #
+    # Mirrors :func:`nodes._visuals.get_plugin_icon_path` for credentials.
+    # The frontend credential modal reads ``cls.icon`` strings of the
+    # form ``"asset:<key>"`` / ``"lobehub:<brand>"`` / emoji, OR fetches
+    # the SVG from the backend via ``GET /api/schemas/credentials/{provider}/icon``.
+    #
+    # Plugin-folder canonical convention (brand-name files):
+    #     ``server/nodes/<plugin>/<cls.id>.svg``
+    #
+    # The credential icon lives directly inside its owner plugin's
+    # folder, named after the credential's brand (e.g.
+    # ``server/nodes/telegram/telegram.svg``). Distinguished from node
+    # icons by the absence of the ``icon`` / ``icon_<type>`` prefix —
+    # node icons follow that convention (see
+    # ``nodes/_visuals.py::get_plugin_icon_path``), credential icons
+    # don't. No ambiguity.
+    #
+    # Resolution order:
+    # 1. ``<plugin_folder>/<cls.id>.svg`` — co-located brand-name file.
+    # 2. ``server/credentials/icons/<cls.id>.svg`` — legacy central
+    #    catalogue (pre-Wave 11.K; new credentials should ship the icon
+    #    inside their plugin folder).
+    # 3. ``None`` — no backend icon; frontend falls back to ``cls.icon``.
+
+    @classmethod
+    def get_icon_path(cls) -> Optional["Path"]:
+        """Return the on-disk path to this credential's icon SVG, or None.
+
+        Lazy import of ``inspect`` + ``pathlib`` keeps the credential
+        module's import cost flat — both are stdlib so it's free.
+        """
+        from pathlib import Path as _Path
+        import inspect
+
+        if not cls.id:
+            return None
+
+        # 1. Co-located in the plugin folder, brand-name basename.
+        try:
+            cred_file = _Path(inspect.getfile(cls)).resolve()
+        except (TypeError, OSError):
+            cred_file = None
+        if cred_file is not None:
+            co_located = cred_file.parent / f"{cls.id}.svg"
+            if co_located.exists():
+                return co_located
+
+        # 2. Legacy central catalogue. ``server/`` resolves from this
+        # file: services/plugin/credential.py -> services/.. -> server/.
+        server_root = _Path(__file__).resolve().parent.parent.parent
+        central = server_root / "credentials" / "icons" / f"{cls.id}.svg"
+        if central.exists():
+            return central
+
+        return None
+
     @classmethod
     def inject(cls, secrets: Dict[str, Any], request: Dict[str, Any]) -> Dict[str, Any]:
         """Mutate an httpx request dict (headers / params / json / auth)
@@ -286,9 +338,7 @@ class Credential:
         ``openai.OpenAIError`` to let the base map them to a typed
         message via :func:`classify_credential_error`.
         """
-        raise NotImplementedError(
-            f"Credential subclass {cls.__name__} must override _probe()"
-        )
+        raise NotImplementedError(f"Credential subclass {cls.__name__} must override _probe()")
 
 
 class OAuth2Credential(Credential):
@@ -307,8 +357,8 @@ class OAuth2Credential(Credential):
     token_header: ClassVar[str] = "Authorization"
     token_prefix: ClassVar[str] = "Bearer "
     # Keys the user enters in credentials modal (API-key style rows)
-    client_id_api_key: ClassVar[str] = ""       # e.g. "google_client_id"
-    client_secret_api_key: ClassVar[str] = ""   # e.g. "google_client_secret"
+    client_id_api_key: ClassVar[str] = ""  # e.g. "google_client_id"
+    client_secret_api_key: ClassVar[str] = ""  # e.g. "google_client_secret"
 
     @classmethod
     async def resolve(cls, *, user_id: str = "owner") -> Dict[str, Any]:
@@ -317,9 +367,16 @@ class OAuth2Credential(Credential):
         auth_service = container.auth_service()
         tokens = await auth_service.get_oauth_tokens(cls.id, user_id)
         if not tokens or not tokens.get("access_token"):
-            raise PermissionError(
-                f"No OAuth tokens for '{cls.id}'. Connect via Credentials modal."
-            )
+            # Annotate the exception so BaseNode.execute can surface the
+            # failing provider in the response envelope and emit a
+            # CloudEvents-typed broadcast (credential.oauth.runtime_failed)
+            # via broadcast_credential_event. Plain attribute assignment —
+            # no new exception class.
+            err = PermissionError(f"No OAuth tokens for '{cls.id}'. Connect via Credentials modal.")
+            err.provider = cls.id
+            err.reason = "missing"
+            err.auth = cls.auth  # "oauth2"
+            raise err
         return tokens
 
     @classmethod
@@ -360,7 +417,7 @@ class ApiKeyCredential(Credential):
 
     auth: ClassVar[Literal["api_key"]] = "api_key"
     # Where the key goes
-    key_name: ClassVar[str] = ""              # header name or query-string key
+    key_name: ClassVar[str] = ""  # header name or query-string key
     key_location: ClassVar[Literal["header", "query", "bearer"]] = "header"
     # Extra fields stored alongside (e.g. "apify_account_id" for Apify)
     extra_fields: ClassVar[Sequence[str]] = ()
@@ -373,7 +430,7 @@ class ApiKeyCredential(Credential):
     # ``httpx.HTTPStatusError`` / ``TimeoutException`` / ``ConnectError``
     # propagate to :meth:`Credential.validate`, where
     # :func:`classify_credential_error` produces the user-facing message.
-    probe_url: ClassVar[str] = ""             # set to enable the default probe
+    probe_url: ClassVar[str] = ""  # set to enable the default probe
     probe_method: ClassVar[str] = "GET"
     probe_params: ClassVar[Dict[str, Any]] = {}
     probe_json: ClassVar[Optional[Dict[str, Any]]] = None
@@ -386,9 +443,11 @@ class ApiKeyCredential(Credential):
         auth_service = container.auth_service()
         api_key = await auth_service.get_api_key(cls.id)
         if not api_key:
-            raise PermissionError(
-                f"No API key for '{cls.id}'. Add via Credentials modal."
-            )
+            err = PermissionError(f"No API key for '{cls.id}'. Add via Credentials modal.")
+            err.provider = cls.id
+            err.reason = "missing"
+            err.auth = cls.auth  # "api_key"
+            raise err
         secrets: Dict[str, Any] = {"api_key": api_key}
         for field in cls.extra_fields:
             value = await auth_service.get_api_key(field)
@@ -427,8 +486,7 @@ class ApiKeyCredential(Credential):
         """
         if not cls.probe_url:
             raise NotImplementedError(
-                f"Credential subclass {cls.__name__} must override _probe() "
-                f"or set the `probe_url` class attribute"
+                f"Credential subclass {cls.__name__} must override _probe() " f"or set the `probe_url` class attribute"
             )
 
         request = cls.inject(

package/server/services/plugin/edge_walker.py

@@ -3,8 +3,8 @@
 Pure functions extracted from ``services/handlers/ai.py`` so every
 agent plugin can call them without depending on the legacy handler
 module. Used by :class:`AIAgentNode`, :class:`ChatAgentNode`,
-:class:`SpecializedAgentBase`, :class:`DeepAgentNode`,
-:class:`RLMAgentNode`, :class:`ClaudeCodeAgentNode`.
+:class:`SpecializedAgentBase`, :class:`RLMAgentNode`,
+:class:`ClaudeCodeAgentNode`.
 
 Three helpers:
 
@@ -14,18 +14,26 @@ Three helpers:
   ``masterSkill`` expansion + the ``androidTool`` Sub-Node pattern +
   child-agent tool discovery.
 - :func:`collect_teammate_connections` — walks ``input-teammates``
-  edges (orchestrator / ai_employee / deep_agent team-lead pattern).
+  edges (orchestrator / ai_employee team-lead pattern).
 - :func:`format_task_context` — renders ``taskTrigger`` payload as a
   prompt prepend block.
 
+Wave 11.I, X3: the Master-Skill expansion logic moved out of this
+module (it used to ``from services.skill_loader import get_skill_loader``
+inline). The :mod:`nodes.skill` package registers an expander callback
+via :func:`register_master_skill_expander` from its ``__init__.py``;
+edge_walker calls the registered callback instead of importing
+``skill_loader`` directly.
+
 These functions have **no service dependencies** beyond the
-``Database`` instance. They mutate nothing. Wave 11.D.6 inlines the
-old ``handlers/ai.py:_collect_*`` shims to call here directly.
+``Database`` instance and the registered expander callback. They
+mutate nothing. Wave 11.D.6 inlines the old ``handlers/ai.py:_collect_*``
+shims to call here directly.
 """
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple
+from typing import TYPE_CHECKING, Any, Awaitable, Callable, Dict, List, Optional, Tuple
 
 from constants import AI_AGENT_TYPES, ANDROID_SERVICE_NODE_TYPES
 from core.logging import get_logger
@@ -36,17 +44,52 @@ if TYPE_CHECKING:
 logger = get_logger(__name__)
 
 
+# ---- Master-Skill expander callback registry ----------------------------
+
+MasterSkillExpander = Callable[
+    [str, Dict[str, Any]],
+    Awaitable[List[Dict[str, Any]]],
+]
+"""Async callable that expands a Master Skill node's ``skills_config``
+into a list of per-skill entries (the same shape ``_append_skill_entries``
+produces for non-master skills). Signature:
+``(source_node_id, skills_config) -> list[entry]``."""
+
+_MASTER_SKILL_EXPANDER: Optional[MasterSkillExpander] = None
+
+
+def register_master_skill_expander(fn: MasterSkillExpander) -> None:
+    """Publish the Master-Skill expander callback.
+
+    Idempotent on equality. The :mod:`nodes.skill` plugin package
+    registers its expander from ``__init__.py`` on package import.
+    Edge-walking code calls :func:`get_master_skill_expander` and runs
+    whatever's registered; the framework has no skill_loader coupling.
+    """
+    global _MASTER_SKILL_EXPANDER
+    if _MASTER_SKILL_EXPANDER is not None and _MASTER_SKILL_EXPANDER != fn:
+        raise ValueError("register_master_skill_expander: callback already registered " "by a different callable; refusing to overwrite")
+    _MASTER_SKILL_EXPANDER = fn
+
+
+def get_master_skill_expander() -> Optional[MasterSkillExpander]:
+    """Return the registered expander callback, or None when no skill
+    plugin has wired it (in which case Master-Skill nodes silently
+    expand to no entries -- the agent still runs without skills)."""
+    return _MASTER_SKILL_EXPANDER
+
+
 async def collect_agent_connections(
     node_id: str,
     context: Dict[str, Any],
     database: "Database",
     log_prefix: str = "[Agent]",
 ) -> Tuple[
-    Optional[Dict[str, Any]],     # memory_data
-    List[Dict[str, Any]],          # skill_data
-    List[Dict[str, Any]],          # tool_data
-    Optional[Dict[str, Any]],     # input_data
-    Optional[Dict[str, Any]],     # task_data
+    Optional[Dict[str, Any]],  # memory_data
+    List[Dict[str, Any]],  # skill_data
+    List[Dict[str, Any]],  # tool_data
+    Optional[Dict[str, Any]],  # input_data
+    Optional[Dict[str, Any]],  # task_data
 ]:
     """Walk edges targeting ``node_id`` and collect everything an agent
     needs from its connected nodes.
@@ -80,10 +123,7 @@ async def collect_agent_connections(
         edge_targets = set(e.get("target") for e in edges)
         logger.debug(f"{log_prefix} All edge targets in graph: {edge_targets}")
     for e in incoming_edges:
-        logger.debug(
-            f"{log_prefix} Edge: source={e.get('source')}, "
-            f"targetHandle={e.get('targetHandle')}"
-        )
+        logger.debug(f"{log_prefix} Edge: source={e.get('source')}, " f"targetHandle={e.get('targetHandle')}")
 
     tool_incoming = [e for e in incoming_edges if e.get("targetHandle") == "input-tools"]
     logger.info(f"{log_prefix} Tool edges (input-tools handle): {len(tool_incoming)}")
@@ -101,18 +141,30 @@ async def collect_agent_connections(
         if target_handle == "input-memory":
             if source_node.get("type") == "simpleMemory":
                 memory_data = await _build_memory_entry(
-                    node_id, source_node_id, database, log_prefix,
+                    node_id,
+                    source_node_id,
+                    database,
+                    log_prefix,
                 )
 
         elif target_handle == "input-skill":
             await _append_skill_entries(
-                source_node, source_node_id, database, skill_data, log_prefix,
+                source_node,
+                source_node_id,
+                database,
+                skill_data,
+                log_prefix,
             )
 
         elif target_handle == "input-tools":
             await _append_tool_entry(
-                source_node, source_node_id, edges, nodes, database,
-                tool_data, log_prefix,
+                source_node,
+                source_node_id,
+                edges,
+                nodes,
+                database,
+                tool_data,
+                log_prefix,
             )
 
         elif target_handle in ("input-main", "input-chat") or target_handle is None:
@@ -126,7 +178,10 @@ async def collect_agent_connections(
 
         elif target_handle == "input-task":
             task_data = await _resolve_task_payload(
-                source_node_id, source_node, context, log_prefix,
+                source_node_id,
+                source_node,
+                context,
+                log_prefix,
             )
 
     logger.info(
@@ -164,7 +219,8 @@ async def _build_memory_entry(
         "session_id": session_id,
         "window_size": int(memory_params.get("window_size", 10)),
         "memory_content": memory_params.get(
-            "memory_content", "# Conversation History\n\n*No messages yet.*\n",
+            "memory_content",
+            "# Conversation History\n\n*No messages yet.*\n",
         ),
         "long_term_enabled": memory_params.get("long_term_enabled", False),
         "retrieval_count": int(memory_params.get("retrieval_count", 3)),
@@ -175,9 +231,10 @@ async def _build_memory_entry(
         "last_session_id": memory_params.get("last_session_id"),
     }
     logger.info(
-        "%s Connected memory node: node=%s session=%s (auto=%s) "
-        "content_length=%d last_session_id=%s",
-        log_prefix, memory_node_id, session_id,
+        "%s Connected memory node: node=%s session=%s (auto=%s) " "content_length=%d last_session_id=%s",
+        log_prefix,
+        memory_node_id,
+        session_id,
         not configured_session or configured_session == "default",
         len(entry["memory_content"]),
         entry["last_session_id"],
@@ -196,45 +253,31 @@ async def _append_skill_entries(
     skill_params = await database.get_node_parameters(source_node_id) or {}
 
     if skill_type == "masterSkill":
-        from services.skill_loader import get_skill_loader
+        expander = get_master_skill_expander()
+        if expander is None:
+            logger.warning(
+                f"{log_prefix} Master Skill node found but no expander "
+                "registered. Skipping expansion -- ensure nodes.skill "
+                "is on the import path."
+            )
+            return
 
         skills_config = skill_params.get("skills_config", {})
         logger.debug(f"{log_prefix} Master Skill found with {len(skills_config)} configured skills")
-        skill_loader = get_skill_loader()
-
-        for skill_key, skill_cfg in skills_config.items():
-            if not skill_cfg.get("enabled", False):
-                continue
-            instructions = skill_cfg.get("instructions", "")
-            if instructions:
-                logger.debug(f"{log_prefix} Using DB instructions for {skill_key}")
-            else:
-                try:
-                    skill = skill_loader.load_skill(skill_key)
-                    if skill:
-                        instructions = skill.instructions
-                        logger.debug(
-                            f"{log_prefix} Fallback: loaded instructions from skill folder for {skill_key}"
-                        )
-                except Exception as e:
-                    logger.warning(f"{log_prefix} Failed to load skill {skill_key}: {e}")
-
-            skill_data.append({
-                "node_id": f"{source_node_id}_{skill_key}",
-                "node_type": "masterSkill",
-                "skill_name": skill_key,
-                "parameters": {"instructions": instructions, "skillName": skill_key},
-                "label": skill_key,
-            })
-            logger.debug(f"{log_prefix} Master Skill enabled: {skill_key}")
+        entries = await expander(source_node_id, skills_config)
+        skill_data.extend(entries)
+        for entry in entries:
+            logger.debug(f"{log_prefix} Master Skill enabled: {entry['skill_name']}")
     else:
-        skill_data.append({
-            "node_id": source_node_id,
-            "node_type": skill_type,
-            "skill_name": skill_params.get("skill_name", skill_type),
-            "parameters": skill_params,
-            "label": source_node.get("data", {}).get("label", skill_type),
-        })
+        skill_data.append(
+            {
+                "node_id": source_node_id,
+                "node_type": skill_type,
+                "skill_name": skill_params.get("skill_name", skill_type),
+                "parameters": skill_params,
+                "label": source_node.get("data", {}).get("label", skill_type),
+            }
+        )
         logger.debug(f"{log_prefix} Connected skill: {skill_type}")
 
 
@@ -265,27 +308,23 @@ async def _append_tool_entry(
                 continue
             service_target_handle = service_edge.get("targetHandle")
             if service_target_handle is not None and service_target_handle != "input-main":
-                logger.debug(
-                    f"{log_prefix} Android Toolkit: Skipping edge with "
-                    f"targetHandle: {service_target_handle}"
-                )
+                logger.debug(f"{log_prefix} Android Toolkit: Skipping edge with " f"targetHandle: {service_target_handle}")
                 continue
             android_node_id = service_edge.get("source")
             android_node = next((n for n in nodes if n.get("id") == android_node_id), None)
             if android_node and android_node.get("type") in ANDROID_SERVICE_NODE_TYPES:
                 android_params = await database.get_node_parameters(android_node_id) or {}
-                connected_services.append({
-                    "node_id": android_node_id,
-                    "node_type": android_node.get("type"),
-                    "service_id": android_params.get("service_id"),
-                    "action": android_params.get("action"),
-                    "parameters": android_params,
-                    "label": android_node.get("data", {}).get("label", android_node.get("type")),
-                })
-                logger.debug(
-                    f"{log_prefix} Android toolkit connected service: "
-                    f"{android_params.get('service_id')}"
+                connected_services.append(
+                    {
+                        "node_id": android_node_id,
+                        "node_type": android_node.get("type"),
+                        "service_id": android_params.get("service_id"),
+                        "action": android_params.get("action"),
+                        "parameters": android_params,
+                        "label": android_node.get("data", {}).get("label", android_node.get("type")),
+                    }
                 )
+                logger.debug(f"{log_prefix} Android toolkit connected service: " f"{android_params.get('service_id')}")
         tool_entry["connected_services"] = connected_services
         logger.debug(f"{log_prefix} Android toolkit has {len(connected_services)} connected services")
 
@@ -309,8 +348,7 @@ async def _append_tool_entry(
             child_tool_id = child_edge.get("source")
             child_tool_node = next((n for n in nodes if n.get("id") == child_tool_id), None)
             logger.debug(
-                f"{log_prefix} Child agent {source_node_id}: "
-                f"tool edge from {child_tool_id}, node found: {child_tool_node is not None}"
+                f"{log_prefix} Child agent {source_node_id}: " f"tool edge from {child_tool_id}, node found: {child_tool_node is not None}"
             )
             if child_tool_node:
                 child_tool_type = child_tool_node.get("type", "")
@@ -318,10 +356,7 @@ async def _append_tool_entry(
                 child_tools.append({"node_type": child_tool_type, "label": child_tool_label})
         if child_tools:
             tool_entry["child_tools"] = child_tools
-            logger.debug(
-                f"{log_prefix} Child agent {source_node_id} has tools: "
-                f"{[t['label'] for t in child_tools]}"
-            )
+            logger.debug(f"{log_prefix} Child agent {source_node_id} has tools: " f"{[t['label'] for t in child_tools]}")
 
     tool_data.append(tool_entry)
     logger.debug(f"{log_prefix} Connected tool: {tool_type}")
@@ -336,9 +371,7 @@ async def _resolve_task_payload(
     logger.info(f"{log_prefix} Found input-task edge from {source_node_id} (type={source_node.get('type')})")
 
     source_output = context.get("outputs", {}).get(source_node_id)
-    logger.info(
-        f"{log_prefix} Context outputs check for {source_node_id}: {source_output is not None}"
-    )
+    logger.info(f"{log_prefix} Context outputs check for {source_node_id}: {source_output is not None}")
 
     if not source_output:
         get_output_fn = context.get("get_output_fn")
@@ -350,9 +383,7 @@ async def _resolve_task_payload(
             except Exception as e:
                 logger.warning(f"{log_prefix} Failed to get output from DB: {e}")
         else:
-            logger.warning(
-                f"{log_prefix} No get_output_fn in context, cannot retrieve task output"
-            )
+            logger.warning(f"{log_prefix} No get_output_fn in context, cannot retrieve task output")
 
     logger.info(
         f"{log_prefix} Source output for {source_node_id}: {source_output is not None}, "
@@ -361,11 +392,7 @@ async def _resolve_task_payload(
     if not source_output:
         return None
 
-    if (
-        isinstance(source_output, dict)
-        and "result" in source_output
-        and isinstance(source_output.get("result"), dict)
-    ):
+    if isinstance(source_output, dict) and "result" in source_output and isinstance(source_output.get("result"), dict):
         task_data = source_output.get("result")
         logger.info(f"{log_prefix} Extracted nested task_data from result key")
     else:
@@ -385,7 +412,7 @@ async def collect_teammate_connections(
 ) -> List[Dict[str, Any]]:
     """Walk ``input-teammates`` edges and return connected agents.
 
-    Used by ``orchestrator_agent`` / ``ai_employee`` / ``deep_agent``.
+    Used by ``orchestrator_agent`` / ``ai_employee``.
     """
     nodes = context.get("nodes", [])
     edges = context.get("edges", [])
@@ -402,12 +429,14 @@ async def collect_teammate_connections(
         if node_type not in AI_AGENT_TYPES:
             continue
         params = await database.get_node_parameters(source_id) or {}
-        teammates.append({
-            "node_id": source_id,
-            "node_type": node_type,
-            "label": source_node.get("data", {}).get("label", node_type),
-            "parameters": params,
-        })
+        teammates.append(
+            {
+                "node_id": source_id,
+                "node_type": node_type,
+                "label": source_node.get("data", {}).get("label", node_type),
+                "parameters": params,
+            }
+        )
         logger.debug(f"[Teams] Found teammate: {node_type} ({source_id})")
 
     return teammates
@@ -447,10 +476,4 @@ def format_task_context(task_data: Dict[str, Any]) -> str:
             "Report this error to the user and suggest next steps if appropriate."
         )
 
-    return (
-        f"Task update received:\n"
-        f"- Agent: {agent_name}\n"
-        f"- Task ID: {task_id}\n"
-        f"- Status: {status}\n"
-        f"- Data: {task_data}"
-    )
+    return f"Task update received:\n" f"- Agent: {agent_name}\n" f"- Task ID: {task_id}\n" f"- Status: {status}\n" f"- Data: {task_data}"

package/server/services/plugin/identifiers.py

@@ -0,0 +1,48 @@
+"""Shape validation for plugin identifiers used in URL routes + lookups.
+
+Plugin node types (and credential provider ids) follow Python-identifier
+rules: a letter or underscore followed by word characters. URL-facing
+routes (``GET /api/schemas/nodes/{node_type}/icon`` etc.) and internal
+helpers (``nodes._visuals.get_plugin_icon_path`` etc.) both validate
+against this constraint to reject path-traversal injections at the
+boundary.
+
+Why this lives here (not inline at each callsite):
+
+- One source of truth for the regex pattern. FastAPI consumes the raw
+  pattern string via ``Path(pattern=...)``; Python code consumes the
+  pre-compiled validator via :func:`is_valid_node_type`. Keeping the
+  pattern in one module guarantees the route-level and function-level
+  checks stay in lockstep.
+- Recognised by CodeQL's ``py/path-injection`` taint analysis as a
+  sanitizer — the canonical "regex fullmatch on user input" pattern
+  (see https://codeql.github.com/codeql-query-help/python/py-path-injection/).
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Final
+
+
+# Letter/underscore then word chars — the shape every registered
+# ``BaseNode.type`` and ``Credential.id`` follows. Exposed as a raw
+# string so FastAPI's ``Path(pattern=...)`` / ``Query(pattern=...)``
+# can consume it directly.
+NODE_TYPE_PATTERN: Final[str] = r"^[A-Za-z_][A-Za-z0-9_]*$"
+
+_NODE_TYPE_RE: Final[re.Pattern[str]] = re.compile(NODE_TYPE_PATTERN)
+
+
+def is_valid_node_type(value: str) -> bool:
+    """True if ``value`` matches :data:`NODE_TYPE_PATTERN`.
+
+    Treats ``None`` / non-string input as invalid (defensive — the
+    type hint is ``str`` but callers may forward URL params verbatim).
+    """
+    if not isinstance(value, str):
+        return False
+    return bool(_NODE_TYPE_RE.fullmatch(value))
+
+
+__all__ = ["NODE_TYPE_PATTERN", "is_valid_node_type"]

package/server/services/plugin/interceptor.py

@@ -22,7 +22,7 @@ class InterceptorInput:
     node_id: str
     node_type: str
     parameters: Dict[str, Any]
-    context: Any   # NodeContext (avoid cycle in type hint)
+    context: Any  # NodeContext (avoid cycle in type hint)
 
 
 class Interceptor(ABC):