Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
"""Node Executor - Single node execution with handler dispatch.
Uses a registry pattern for clean handler dispatch without if-else chains.
"""
import asyncio
import time
import uuid
from dataclasses import dataclass
from datetime import datetime
from typing import Dict, Any, Optional, Callable, Tuple, TYPE_CHECKING
from core.logging import get_logger
from constants import (
AI_MODEL_TYPES,
GOOGLE_MAPS_TYPES,
detect_ai_provider,
)
from pydantic import ValidationError
from services.node_registry import get_node_class
from services.parameter_resolver import template_view
from services.plugin.base import NodeUserError, locked_tool_fields, restore_locked_fields, saved_settings
from services.workflow_sanitizer import restore_dropped
# Wave 11.D.13 sunset: every handler that was imported here is now
# either (a) called lazily from a plugin's execute_op / execute method,
# or (b) retired entirely. The dispatcher itself only needs the
# plugin-class registry populated via register_node side effects.
# Triggering that population is what ``import nodes`` does at server
# startup (see main.py lifespan).
if TYPE_CHECKING:
from core.config import Settings
from core.database import Database
from services.ai import AIService
from nodes.location._service import MapsService
from services.text import TextService
from nodes.android._dispatcher import AndroidService
logger = get_logger(__name__)
@dataclass
class ExecutionResult:
"""Standardized execution result."""
success: bool
node_id: str
node_type: str
result: Optional[Dict] = None
error: Optional[str] = None
execution_id: str = ""
execution_time: float = 0.0
timestamp: str = ""
def to_dict(self) -> Dict[str, Any]:
d = {
"success": self.success,
"node_id": self.node_id,
"node_type": self.node_type,
"execution_id": self.execution_id,
"execution_time": self.execution_time,
"timestamp": self.timestamp or datetime.now().isoformat(),
}
if self.success:
d["result"] = self.result or {}
else:
d["error"] = self.error
return d
class NodeExecutor:
"""Executes individual workflow nodes using registry-based dispatch."""
def __init__(
self,
database: "Database",
ai_service: "AIService",
maps_service: "MapsService",
text_service: "TextService",
android_service: "AndroidService",
settings: "Settings",
output_store: Optional[Callable] = None,
):
self.database = database
self.ai_service = ai_service
self.maps_service = maps_service
self.text_service = text_service
self.android_service = android_service
self.settings = settings
self._output_store = output_store
self._handlers = self._build_handler_registry()
def _build_handler_registry(self) -> Dict[str, Callable]:
"""Build handler registry with service dependencies bound via partial.
Plugin handlers registered via ``services.node_registry.register_node``
win over the legacy hardcoded entries below; this lets per-node
plugin modules in ``server/nodes/*.py`` override the dispatcher
without touching this file. Plugin handlers are closed over their
own dependencies at module import time, so no ``partial`` wiring
is needed here.
"""
from services.node_registry import _HANDLER_REGISTRY as _PLUGIN_HANDLERS
registry = {
# Workflow control
# start / cronScheduler / timer — migrated to nodes/{workflow,scheduler}/*.py (Wave 11.C).
# AI agents — all migrated to nodes/agent/*.py (Wave 11.C).
# Plugin handlers win via registry.update(_PLUGIN_HANDLERS) merge below.
# simpleMemory + masterSkill: migrated to nodes/skill/*.py (Wave 11.C).
# Maps — all 3 migrated to nodes/location/*.py (Wave 11.C).
# All other node types migrated to plugin classes under nodes/*/.
# Plugin handlers register themselves into _PLUGIN_HANDLERS via
# BaseNode.__init_subclass__ at import time. The merge below is
# now the sole population of the registry.
}
# AI chat models — all 9 migrated to nodes/model/*.py (Wave 11.C).
# Plugin handlers register themselves via _PLUGIN_HANDLERS merge below.
# Android services — all 16 migrated to nodes/android/*.py (Wave 11.C).
# Plugin handlers register themselves via _PLUGIN_HANDLERS merge.
# Plugin handlers last: they win over the legacy entries above,
# enabling incremental migration (Wave 10.C strangler fig).
registry.update(_PLUGIN_HANDLERS)
return registry
async def execute(
self,
node_id: str,
node_type: str,
parameters: Dict[str, Any],
context: Dict[str, Any],
resolve_params_fn: Optional[Callable] = None,
) -> Dict[str, Any]:
"""Execute a single workflow node."""
start_time = time.time()
session_id = context.get("session_id", "default")
execution_id = context.get("execution_id") or str(uuid.uuid4())[:8]
try:
if context.get("workflow_id"):
from services.employees.permissions import assert_runtime_access
await assert_runtime_access(self.database, str(context["workflow_id"]), node_id, node_type, context)
params, context = await self.prepare_parameters(node_id, node_type, parameters, context, resolve_params_fn)
# Build handler context
handler_ctx = {
**context,
"start_time": start_time,
"execution_id": execution_id,
}
logger.info("NodeExecutor context", node_id=node_id, workflow_id=context.get("workflow_id"))
# Execute via registry or special handlers
result = await self._dispatch(node_id, node_type, params, handler_ctx)
result["execution_id"] = execution_id
# Store output if successful
if result.get("success") and self._output_store:
output_data = result.get("result", {})
# Android service outputs promote their nested 'data' field so
# {{batterymonitor.battery_level}} works (template_view owns the rule).
output_data = template_view(node_type, output_data)
# For socialReceive, store 4 outputs for different handle connections
# - output_message: Text for LLM input
# - output_media: Media data
# - output_contact: Sender/contact info
# - output_metadata: Message metadata
if node_type == "socialReceive" and isinstance(output_data, dict):
await self._output_store(session_id, node_id, "output_message", output_data.get("message", ""))
await self._output_store(session_id, node_id, "output_media", output_data.get("media", {}))
await self._output_store(session_id, node_id, "output_contact", output_data.get("contact", {}))
await self._output_store(session_id, node_id, "output_metadata", output_data.get("metadata", {}))
# Store with multiple keys for different handle IDs used by frontend components:
# - output_main: SquareNode, GenericNode, TriggerNode, StartNode
# - output_top: AIAgentNode (agents use top output handle)
# - output_0: backward compatibility
await self._output_store(session_id, node_id, "output_main", output_data)
await self._output_store(session_id, node_id, "output_top", output_data)
await self._output_store(session_id, node_id, "output_0", output_data)
return result
except asyncio.CancelledError:
# Inside an activity Temporal must observe the cancellation, not
# an ordinary failure envelope that can be mistaken for
# completion: the activity wrapper reports a call that may have
# happened (BaseNode.as_activity). Workspace engines own
# subprocesses/device leases, so they re-raise after their
# finally blocks wherever they run.
from temporalio import activity
if activity.in_activity() or getattr(get_node_class(node_type), "workspace_task", False):
raise
return ExecutionResult(
False, node_id, node_type, error="Cancelled", execution_id=execution_id, execution_time=time.time() - start_time
).to_dict()
except Exception as e:
logger.error("Node execution error", node_id=node_id, error=str(e))
return ExecutionResult(
False, node_id, node_type, error=str(e), execution_id=execution_id, execution_time=time.time() - start_time
).to_dict()
async def prepare_parameters(
self,
node_id: str,
node_type: str,
parameters: Dict[str, Any],
context: Dict[str, Any],
resolve_params_fn: Optional[Callable] = None,
*,
inject_keys: bool = True,
) -> Tuple[Dict[str, Any], Dict[str, Any]]:
"""What a node runs with, and the context its handler sees: its saved
settings with ``parameters`` over them, locked fields put back,
validated, API keys added (unless ``inject_keys`` is off), then its
templates resolved. :meth:`execute` starts with it; a card that keeps
what a graph node sent rebuilds it here
(services/approvals/tool_calls.py)."""
session_id = context.get("session_id", "default")
# An LLM tool call carries the model's own arguments in
# ``tool_args``; ``parameters`` already has them merged on top of
# the node's settings (the agent workflow builds
# ``{**tool params, **call args}``).
tool_args = context.get("tool_args")
if isinstance(tool_args, dict):
locked = locked_tool_fields(get_node_class(node_type))
if locked:
context = {
**context,
"tool_args": {k: v for k, v in tool_args.items() if k not in locked},
}
else:
tool_args = None
# Load, validate, enhance parameters
params = await self._prepare_parameters(node_id, node_type, parameters, session_id, tool_args=tool_args,
parameter_snapshot=context.get("parameter_snapshot"), principal=str(context.get("user_id") or "owner"),
context=context, resolve_params_fn=resolve_params_fn, inject_keys=inject_keys)
email_templates_resolved = context.pop("_employee_email_templates_resolved", None) == node_id
# Resolve templates if resolver provided
nodes = context.get("nodes")
edges = context.get("edges")
logger.debug(
f"[NodeExecutor] Template resolution check: resolve_fn={resolve_params_fn is not None}, nodes={len(nodes) if nodes else 'None'}, edges={len(edges) if edges else 'None'}"
)
if resolve_params_fn and nodes is not None and edges is not None and not email_templates_resolved:
logger.debug(f"[NodeExecutor] Before resolution: params={list(params.keys())}")
# ``context["outputs"]`` holds what this run's upstream nodes
# produced. Resolving from it rather than only from the shared
# session store keeps concurrent firings from reading each
# other's trigger data.
params = await resolve_params_fn(
params,
node_id,
nodes,
edges,
session_id,
run_outputs=context.get("outputs") or None,
)
logger.debug(f"[NodeExecutor] After resolution: params keys={list(params.keys())}")
return params, context
async def _prepare_parameters(
self,
node_id: str,
node_type: str,
params: Dict,
session_id: str,
tool_args: Optional[Dict[str, Any]] = None,
parameter_snapshot: Optional[Dict[str, Dict[str, Any]]] = None,
principal: str = "owner",
context: Optional[Dict[str, Any]] = None,
resolve_params_fn: Optional[Callable] = None,
*,
inject_keys: bool = True,
) -> Dict:
"""Load from DB, validate, inject API keys (``inject_keys``)."""
# Merge with DB parameters (DB provides defaults, frontend can override)
db_params = await saved_settings(self.database, node_id, parameter_snapshot)
# A map the run carries (its headers, without secrets) gets the saved
# secrets back, unless the model supplied that map itself.
merged = restore_dropped({**db_params, **params}, db_params, keep=tool_args or ()) if params else db_params
# On an LLM tool call the model never chooses a node's locked fields
# (``server_controlled_fields``: the sending account, the browser
# profile, data mounts...). The saved setting wins; with none saved,
# the field falls back to its default rather than to the model's value.
if tool_args:
merged = restore_locked_fields(get_node_class(node_type), merged, tool_args, db_params)
# Managed Gmail intake must shrink its body substitutions before the
# employeeJob Params boundary, using one frozen set of template values.
# The complete original stays in trusted handler context for job capture.
if node_type == "employeeJob" and context is not None:
from services.employees.email_input import project_managed_gmail_parameters
merged, projected_context, handled = await project_managed_gmail_parameters(
self.database, node_id, merged, {**context, "node_type": node_type}, resolve_params_fn)
if handled:
context.update(projected_context)
context["_employee_email_templates_resolved"] = node_id
# Validate via plugin Params (snake_case, plugin-only path).
node_cls = get_node_class(node_type)
params_model = getattr(node_cls, "Params", None) if node_cls else None
if params_model is not None:
try:
validated = params_model.model_validate(merged)
merged = {**merged, **validated.model_dump(exclude_unset=True)}
except ValidationError as e:
logger.warning("Validation warning", node_type=node_type, errors=str(e))
# Inject API keys
if not inject_keys:
return merged
return await self._inject_api_keys(node_type, merged, principal=principal)
async def _inject_api_keys(self, node_type: str, params: Dict, *, principal: str = "owner") -> Dict:
"""Auto-inject API keys for AI and Maps nodes."""
result = params.copy()
if getattr(self.settings, "distributed_mode", False) and result.get("api_key"):
from services.plugin import NodeUserError
raise NodeUserError("Distributed execution requires a saved 1Password credential.")
if node_type in AI_MODEL_TYPES:
provider = detect_ai_provider(node_type, params)
if not result.get("api_key"):
key = await self.ai_service.auth.resolve_api_key(provider, "default", principal=principal)
if key:
result["api_key"] = key
if not result.get("model"):
models = await self.ai_service.auth.get_stored_models(provider, "default")
if models:
result["model"] = models[0]
elif node_type in GOOGLE_MAPS_TYPES:
if not result.get("api_key"):
# Try database first, then fall back to environment variable
key = await self.ai_service.auth.resolve_api_key("google_maps", "default", principal=principal)
if key:
result["api_key"] = key
elif not getattr(self.settings, "distributed_mode", False) and self.settings.google_maps_api_key:
result["api_key"] = self.settings.google_maps_api_key
return result
# Node types that need outputs from connected upstream nodes.
# Computed once so plugin handlers (registered via @register_node)
# can read context['connected_outputs'] / context['source_nodes']
# without re-implementing the graph walk.
_NEEDS_CONNECTED_OUTPUTS = frozenset(
{
"pythonExecutor",
"montyExecutor",
"javascriptExecutor",
"typescriptExecutor",
"webhookResponse",
"console",
"socialReceive",
"canvas",
"chatReply",
}
)
async def _dispatch(self, node_id: str, node_type: str, params: Dict, context: Dict) -> Dict:
"""Dispatch to handler from registry or special handlers."""
# Pre-enrich context for nodes that consume upstream outputs.
# Both plugin handlers and legacy handlers can read these keys.
if node_type in self._NEEDS_CONNECTED_OUTPUTS:
outputs, source_nodes = await self._get_connected_outputs_with_info(context, node_id)
context = {**context, "connected_outputs": outputs, "source_nodes": source_nodes}
# Check registry first (plugin handlers win — they were merged in
# via _build_handler_registry's registry.update(_PLUGIN_HANDLERS)).
handler = self._handlers.get(node_type)
if handler:
return await handler(node_id, node_type, params, context)
# All trigger + special node types are now plugin classes
# (Wave 11.C). Trigger nodes live in _handlers via their
# plugin's register_node side effect and have already been
# handled above. Anything that falls through here is a
# workflow node type the backend genuinely doesn't know about.
error = NodeUserError(
f"Node type '{node_type}' is not installed. Remove or replace this node before running the workflow.",
requires_user_action=True,
)
return {
**ExecutionResult(
False,
node_id,
node_type,
error=str(error),
execution_time=time.time() - context.get("start_time", time.time()),
).to_dict(),
**error.as_dict(),
}
async def _get_connected_outputs(self, context: Dict, node_id: str) -> Dict[str, Any]:
"""Get outputs from connected upstream nodes with handle-aware routing."""
get_output = context.get("get_output_fn")
if not get_output:
return {}
nodes = context.get("nodes", [])
edges = context.get("edges", [])
session_id = context.get("session_id", "default")
result = {}
for edge in edges:
if edge.get("target") == node_id:
source_id = edge.get("source")
source_handle = edge.get("sourceHandle")
# Map sourceHandle to output key
if source_handle and source_handle.startswith("output-"):
handle_name = source_handle.replace("output-", "")
output_key = f"output_{handle_name}"
else:
output_key = "output_0"
output = await get_output(session_id, source_id, output_key)
# Fallback to output_0 if specific handle output not found
if output is None and output_key != "output_0":
output = await get_output(session_id, source_id, "output_0")
if output:
source = next((n for n in nodes if n.get("id") == source_id), {})
result[source.get("type", "unknown")] = output
return result
def _get_source_nodes_info(self, context: Dict, node_id: str) -> list:
"""Get source node info (id, type, label) for edges targeting this node.
This is used for display purposes (e.g., showing source in Console panel).
Does NOT filter by output availability - just returns edge source info.
"""
nodes = context.get("nodes", [])
edges = context.get("edges", [])
source_nodes = []
for edge in edges:
if edge.get("target") == node_id:
source_id = edge.get("source")
source = next((n for n in nodes if n.get("id") == source_id), {})
source_type = source.get("type", "unknown")
source_data = source.get("data", {})
source_label = source_data.get("label") or source_type
source_nodes.append({"id": source_id, "type": source_type, "label": source_label})
return source_nodes
async def _get_connected_outputs_with_info(self, context: Dict, node_id: str) -> tuple:
"""Get outputs from connected upstream nodes with source node info.
Returns:
Tuple of (outputs dict, source_nodes list with id/type/label info)
"""
get_output = context.get("get_output_fn")
if not get_output:
logger.warning(f"[_get_connected_outputs_with_info] No get_output_fn in context for {node_id}")
return {}, []
nodes = context.get("nodes", [])
edges = context.get("edges", [])
session_id = context.get("session_id", "default")
outputs = {}
source_nodes = []
logger.debug(f"[_get_connected_outputs_with_info] node_id={node_id}, edges={len(edges)}, session={session_id}")
for edge in edges:
logger.debug(
f"[_get_connected_outputs_with_info] Checking edge: source={edge.get('source')}, target={edge.get('target')}, sourceHandle={edge.get('sourceHandle')}, targetHandle={edge.get('targetHandle')}"
)
if edge.get("target") == node_id:
source_id = edge.get("source")
source_handle = edge.get("sourceHandle")
# Map sourceHandle to output key
# Frontend uses "output-<name>", backend stores as "output_<name>"
if source_handle and source_handle.startswith("output-"):
handle_name = source_handle.replace("output-", "")
output_key = f"output_{handle_name}"
else:
output_key = "output_0"
logger.debug(
f"[_get_connected_outputs_with_info] Found edge from {source_id} to {node_id}, sourceHandle={source_handle}, using output_key={output_key}"
)
output = await get_output(session_id, source_id, output_key)
logger.debug(f"[_get_connected_outputs_with_info] First lookup (key={output_key}): {'FOUND' if output else 'NOT_FOUND'}")
# Fallback to output_0 if specific handle output not found
if output is None and output_key != "output_0":
logger.debug(f"[_get_connected_outputs_with_info] output_key {output_key} not found, falling back to output_0")
output = await get_output(session_id, source_id, "output_0")
logger.debug(f"[_get_connected_outputs_with_info] Fallback lookup (output_0): {'FOUND' if output else 'NOT_FOUND'}")
logger.debug(f"[_get_connected_outputs_with_info] Final output from {source_id}: {'FOUND' if output else 'NOT FOUND'}")
if output:
source = next((n for n in nodes if n.get("id") == source_id), {})
source_type = source.get("type", "unknown")
outputs[source_type] = output
# Get label from node data if available
source_data = source.get("data", {})
source_label = source_data.get("label") or source_type
source_nodes.append({"id": source_id, "type": source_type, "label": source_label})
logger.debug(f"[_get_connected_outputs_with_info] Returning {len(outputs)} outputs, {len(source_nodes)} source_nodes")
return outputs, source_nodes