flowent 0.0.4 → 0.0.5

package/backend/src/flowent/graph_service.py

@@ -1,7 +1,13 @@
 from __future__ import annotations
 
+import ast
+import json
+import shutil
+import subprocess
 import uuid
 from copy import deepcopy
+from dataclasses import dataclass
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
 
 from flowent import settings as settings_module
 from flowent.events import event_bus
@@ -16,12 +22,17 @@ from flowent.models import (
     NodeConfig,
     NodeType,
     PortDirection,
+    PortInboundEntry,
+    PortType,
     ReceivedMessage,
     Tab,
+    WorkflowActivationState,
     WorkflowDefinition,
     WorkflowNodeDefinition,
     WorkflowNodeKind,
     WorkflowPort,
+    content_parts_to_text,
+    deserialize_content_parts,
 )
 from flowent.registry import registry
 from flowent.runtime import SYSTEM_NODE_TIMEOUT
@@ -33,20 +44,56 @@ from flowent.settings import (
     STEWARD_ROLE_INCLUDED_TOOLS,
     STEWARD_ROLE_NAME,
     build_assistant_write_dirs,
+    find_provider,
     find_role,
+    resolve_model_info,
     resolve_path,
 )
-from flowent.tools import MINIMUM_TOOLS
+from flowent.tools import (
+    MINIMUM_TOOLS,
+    is_assistant_only_mcp_tool_name,
+    is_assistant_only_tool_name,
+)
 from flowent.workspace_store import workspace_store
 
 LEADER_NODE_NAME = "Leader"
 
 
+@dataclass(frozen=True)
+class ContactPath:
+    target_id: str
+    target_node_type: str
+    target_role_name: str | None
+    target_name: str | None
+    target_state: str | None
+    is_leader: bool
+    from_output_port_key: str
+    to_input_port_key: str
+    port_type: str
+    edge_id: str
+
+    def serialize(self) -> dict[str, object]:
+        return {
+            "id": self.target_id,
+            "target_id": self.target_id,
+            "node_type": self.target_node_type,
+            "role_name": self.target_role_name,
+            "name": self.target_name,
+            "state": self.target_state,
+            "is_leader": self.is_leader,
+            "from_output_port_key": self.from_output_port_key,
+            "to_input_port_key": self.to_input_port_key,
+            "port_type": self.port_type,
+            "edge_id": self.edge_id,
+        }
+
+
 def build_tools_for_role(
     role_name: str,
     *,
     requested_tools: list[str] | None = None,
     settings=None,
+    assistant_boundary: bool = False,
 ) -> list[str]:
     current_settings = settings or settings_module.get_settings()
     normalized_role_name = role_name.strip()
@@ -70,6 +117,11 @@ def build_tools_for_role(
     for tool_name in [*MINIMUM_TOOLS, *included_tools, *(requested_tools or [])]:
         if tool_name in seen_tools:
             continue
+        if not assistant_boundary and (
+            is_assistant_only_tool_name(tool_name)
+            or is_assistant_only_mcp_tool_name(tool_name)
+        ):
+            continue
         if tool_name in excluded_tools and tool_name not in MINIMUM_TOOLS:
             continue
         final_tools.append(tool_name)
@@ -82,6 +134,7 @@ def build_assistant_tools(*, settings=None) -> list[str]:
     assistant_tools = build_tools_for_role(
         current_settings.assistant.role_name,
         settings=current_settings,
+        assistant_boundary=True,
     )
     final_tools: list[str] = []
     seen_tools: set[str] = set()
@@ -126,87 +179,160 @@ def is_tab_leader(*, node_id: str, tab_id: str | None = None) -> bool:
     return get_tab_leader_id(resolved_tab_id) == node_id
 
 
+def _coerce_port_type(raw_value: object, default: PortType) -> PortType:
+    try:
+        return PortType(str(raw_value))
+    except ValueError:
+        return default
+
+
+def _port_from_code_config(
+    raw_port: object,
+    *,
+    direction: PortDirection,
+) -> WorkflowPort | None:
+    if not isinstance(raw_port, dict):
+        return None
+    key = raw_port.get("key")
+    if not isinstance(key, str) or not key.strip():
+        return None
+    try:
+        port_type = PortType(str(raw_port.get("type")))
+    except ValueError:
+        return None
+    return WorkflowPort(
+        key=key.strip(),
+        direction=direction,
+        type=port_type,
+        required=bool(raw_port.get("required", direction == PortDirection.INPUT)),
+        multiple=bool(raw_port.get("multiple", False)),
+    )
+
+
+def _build_code_ports(
+    config: dict[str, object],
+) -> tuple[list[WorkflowPort], list[WorkflowPort]]:
+    raw_inputs = config.get("inputs")
+    raw_outputs = config.get("outputs")
+    inputs = [
+        port
+        for port in (
+            _port_from_code_config(item, direction=PortDirection.INPUT)
+            for item in (raw_inputs if isinstance(raw_inputs, list) else [])
+        )
+        if port is not None
+    ]
+    outputs = [
+        port
+        for port in (
+            _port_from_code_config(item, direction=PortDirection.OUTPUT)
+            for item in (raw_outputs if isinstance(raw_outputs, list) else [])
+        )
+        if port is not None
+    ]
+    if not inputs:
+        inputs = [
+            WorkflowPort(
+                key="in",
+                direction=PortDirection.INPUT,
+                type=PortType.PARTS,
+                required=True,
+            )
+        ]
+    if not outputs:
+        outputs = [
+            WorkflowPort(
+                key="out",
+                direction=PortDirection.OUTPUT,
+                type=PortType.PARTS,
+                multiple=True,
+            )
+        ]
+    return inputs, outputs
+
+
 def _default_ports(
     node_kind: WorkflowNodeKind,
+    config: dict[str, object] | None = None,
 ) -> tuple[list[WorkflowPort], list[WorkflowPort]]:
+    node_config = config or {}
     if node_kind == WorkflowNodeKind.TRIGGER:
+        output_type = _coerce_port_type(node_config.get("output_type"), PortType.PARTS)
         return (
             [],
             [
                 WorkflowPort(
                     key="out",
                     direction=PortDirection.OUTPUT,
-                    kind=EdgeKind.CONTROL,
+                    type=output_type,
                     multiple=True,
                 )
             ],
         )
-    if node_kind == WorkflowNodeKind.CODE:
+    if node_kind == WorkflowNodeKind.LLM:
+        input_type = _coerce_port_type(node_config.get("input_type"), PortType.PARTS)
+        output_type = _coerce_port_type(node_config.get("output_type"), PortType.PARTS)
         return (
             [
                 WorkflowPort(
                     key="in",
                     direction=PortDirection.INPUT,
-                    kind=EdgeKind.CONTROL,
-                ),
-                WorkflowPort(
-                    key="input",
-                    direction=PortDirection.INPUT,
-                    kind=EdgeKind.DATA,
-                    multiple=True,
-                ),
+                    type=input_type,
+                    required=True,
+                )
             ],
             [
                 WorkflowPort(
                     key="out",
                     direction=PortDirection.OUTPUT,
-                    kind=EdgeKind.CONTROL,
+                    type=output_type,
                     multiple=True,
-                ),
-                WorkflowPort(
-                    key="output",
-                    direction=PortDirection.OUTPUT,
-                    kind=EdgeKind.DATA,
-                    multiple=True,
-                ),
+                )
             ],
         )
+    if node_kind == WorkflowNodeKind.CODE:
+        return _build_code_ports(node_config)
     if node_kind == WorkflowNodeKind.IF:
+        input_type = _coerce_port_type(node_config.get("input_type"), PortType.PARTS)
         return (
             [
                 WorkflowPort(
                     key="in",
                     direction=PortDirection.INPUT,
-                    kind=EdgeKind.CONTROL,
-                ),
-                WorkflowPort(
-                    key="condition",
-                    direction=PortDirection.INPUT,
-                    kind=EdgeKind.DATA,
+                    type=input_type,
+                    required=True,
                 ),
             ],
             [
                 WorkflowPort(
-                    key="true",
+                    key="then",
                     direction=PortDirection.OUTPUT,
-                    kind=EdgeKind.CONTROL,
+                    type=input_type,
                     multiple=True,
                 ),
                 WorkflowPort(
-                    key="false",
+                    key="else",
                     direction=PortDirection.OUTPUT,
-                    kind=EdgeKind.CONTROL,
+                    type=input_type,
                     multiple=True,
                 ),
             ],
         )
     if node_kind == WorkflowNodeKind.MERGE:
+        input_type = _coerce_port_type(node_config.get("input_type"), PortType.PARTS)
+        strategy = node_config.get("strategy")
+        output_type = (
+            input_type
+            if strategy == "first_completed"
+            else _coerce_port_type(node_config.get("output_type"), PortType.JSON)
+        )
         return (
             [
                 WorkflowPort(
                     key="in",
                     direction=PortDirection.INPUT,
-                    kind=EdgeKind.CONTROL,
+                    type=input_type,
+                    required=True,
                     multiple=True,
                 )
             ],
@@ -214,7 +340,26 @@ def _default_ports(
                 WorkflowPort(
                     key="out",
                     direction=PortDirection.OUTPUT,
-                    kind=EdgeKind.CONTROL,
+                    type=output_type,
+                    multiple=True,
+                )
+            ],
+        )
+    if node_kind == WorkflowNodeKind.AGENT:
+        return (
+            [
+                WorkflowPort(
+                    key="in",
+                    direction=PortDirection.INPUT,
+                    type=PortType.PARTS,
+                    required=False,
+                )
+            ],
+            [
+                WorkflowPort(
+                    key="out",
+                    direction=PortDirection.OUTPUT,
+                    type=PortType.PARTS,
                     multiple=True,
                 )
             ],
@@ -224,14 +369,15 @@ def _default_ports(
             WorkflowPort(
                 key="in",
                 direction=PortDirection.INPUT,
-                kind=EdgeKind.CONTROL,
+                type=PortType.PARTS,
+                required=True,
             )
         ],
         [
             WorkflowPort(
                 key="out",
                 direction=PortDirection.OUTPUT,
-                kind=EdgeKind.CONTROL,
+                type=PortType.PARTS,
                 multiple=True,
             )
         ],
@@ -244,7 +390,7 @@ def build_workflow_node_definition(
     node_kind: WorkflowNodeKind,
     config: dict[str, object] | None = None,
 ) -> WorkflowNodeDefinition:
-    inputs, outputs = _default_ports(node_kind)
+    inputs, outputs = _default_ports(node_kind, config)
     return WorkflowNodeDefinition(
         id=node_id,
         type=node_kind,
@@ -268,6 +414,376 @@ def get_workflow_node(tab_id: str, node_id: str) -> WorkflowNodeDefinition | Non
     return tab.definition.get_node(node_id)
 
 
+def get_workflow_node_definition(node_id: str) -> WorkflowNodeDefinition | None:
+    record = workspace_store.get_node_record(node_id)
+    if record is not None and record.config.tab_id:
+        return get_workflow_node(record.config.tab_id, node_id)
+    live_node = registry.get(node_id)
+    if live_node is not None and live_node.config.tab_id:
+        return get_workflow_node(live_node.config.tab_id, node_id)
+    for tab in workspace_store.list_tabs():
+        node = tab.definition.get_node(node_id)
+        if node is not None:
+            return node
+    return None
+
+
+def resolve_workflow_node_ref(*, tab_id: str, node_ref: str) -> str | None:
+    target = registry.get(node_ref)
+    if target is not None and target.config.tab_id == tab_id:
+        return target.uuid
+
+    tab = workspace_store.get_tab(tab_id)
+    if tab is None:
+        return None
+
+    definition_nodes = list(tab.definition.nodes)
+    exact_match = next((node for node in definition_nodes if node.id == node_ref), None)
+    if exact_match is not None:
+        return exact_match.id
+
+    named_matches = [
+        node
+        for node in definition_nodes
+        if isinstance(node.config.get("name"), str) and node.config["name"] == node_ref
+    ]
+    if len(named_matches) == 1:
+        return named_matches[0].id
+
+    role_matches = [
+        node
+        for node in definition_nodes
+        if node.type == WorkflowNodeKind.AGENT
+        and isinstance(node.config.get("role_name"), str)
+        and node.config["role_name"] == node_ref
+    ]
+    if len(role_matches) == 1:
+        return role_matches[0].id
+
+    if 4 <= len(node_ref) < 36:
+        prefix_matches = [
+            node for node in definition_nodes if node.id.startswith(node_ref)
+        ]
+        if len(prefix_matches) == 1:
+            return prefix_matches[0].id
+    return None
+
+
+def _resolve_contact_target_metadata(
+    *,
+    tab_id: str,
+    node_id: str,
+) -> tuple[str, str | None, str | None, str | None, bool]:
+    live_node = registry.get(node_id)
+    if live_node is not None:
+        return (
+            live_node.config.node_type.value,
+            live_node.config.role_name,
+            live_node.config.name,
+            live_node.state.value,
+            is_tab_leader(node_id=node_id, tab_id=tab_id),
+        )
+
+    record = workspace_store.get_node_record(node_id)
+    if record is not None:
+        return (
+            record.config.node_type.value,
+            record.config.role_name,
+            record.config.name,
+            record.state.value,
+            is_tab_leader(node_id=node_id, tab_id=tab_id),
+        )
+
+    definition = get_workflow_node(tab_id, node_id)
+    if definition is None:
+        return ("agent", None, None, None, False)
+    return (
+        definition.type.value,
+        str(definition.config["role_name"])
+        if isinstance(definition.config.get("role_name"), str)
+        else None,
+        str(definition.config["name"])
+        if isinstance(definition.config.get("name"), str)
+        else None,
+        None,
+        False,
+    )
+
+
+def list_agent_contact_paths(*, tab_id: str, node_id: str) -> list[ContactPath]:
+    if is_tab_leader(node_id=node_id, tab_id=tab_id):
+        return []
+    tab = workspace_store.get_tab(tab_id)
+    if tab is None:
+        return []
+
+    paths: list[ContactPath] = []
+    source_node = tab.definition.get_node(node_id)
+    if source_node is None or source_node.type != WorkflowNodeKind.AGENT:
+        return paths
+
+    for edge in sorted(
+        tab.definition.edges, key=lambda item: (item.created_at, item.id)
+    ):
+        if edge.from_node_id != node_id:
+            continue
+        source_port = _port_matches(
+            source_node.outputs,
+            port_key=edge.from_port_key,
+            direction=PortDirection.OUTPUT,
+        )
+        target_node = tab.definition.get_node(edge.to_node_id)
+        if source_port is None or target_node is None:
+            continue
+        target_port = _port_matches(
+            target_node.inputs,
+            port_key=edge.to_port_key,
+            direction=PortDirection.INPUT,
+        )
+        if target_port is None or source_port.type != target_port.type:
+            continue
+        node_type, role_name, name, state, is_leader_contact = (
+            _resolve_contact_target_metadata(tab_id=tab_id, node_id=edge.to_node_id)
+        )
+        paths.append(
+            ContactPath(
+                target_id=edge.to_node_id,
+                target_node_type=node_type,
+                target_role_name=role_name,
+                target_name=name,
+                target_state=state,
+                is_leader=is_leader_contact,
+                from_output_port_key=edge.from_port_key,
+                to_input_port_key=edge.to_port_key,
+                port_type=source_port.type.value,
+                edge_id=edge.id,
+            )
+        )
+    return paths
+
+
+def resolve_agent_contact_path(
+    *,
+    tab_id: str,
+    source_node_id: str,
+    target_node_id: str,
+    from_output_port_key: str,
+    to_input_port_key: str,
+) -> ContactPath | None:
+    return next(
+        (
+            path
+            for path in list_agent_contact_paths(tab_id=tab_id, node_id=source_node_id)
+            if path.target_id == target_node_id
+            and path.from_output_port_key == from_output_port_key
+            and path.to_input_port_key == to_input_port_key
+        ),
+        None,
+    )
+
+
+def _summarize_port_value(
+    value: object, *, port_type: PortType, limit: int = 240
+) -> str:
+    if port_type == PortType.PARTS:
+        text = content_parts_to_text(
+            deserialize_content_parts(value if isinstance(value, list) else None)
+        )
+    elif isinstance(value, str):
+        text = value
+    else:
+        try:
+            text = json.dumps(value, ensure_ascii=False, sort_keys=True)
+        except TypeError:
+            text = str(value)
+    text = " ".join(text.split())
+    if len(text) <= limit:
+        return text
+    return text[: limit - 3].rstrip() + "..."
+
+
+def _node_label_snapshot(tab_id: str, node_id: str) -> str | None:
+    _, role_name, name, _, is_leader_contact = _resolve_contact_target_metadata(
+        tab_id=tab_id,
+        node_id=node_id,
+    )
+    if name:
+        return name
+    if is_leader_contact:
+        return LEADER_NODE_NAME
+    if role_name:
+        return role_name
+    return node_id[:8]
+
+
+def dispatch_port_value(
+    *,
+    tab_id: str,
+    source_node_id: str,
+    source_output_port_key: str,
+    target_node_id: str,
+    target_input_port_key: str,
+    value: object,
+    source_is_agent_send: bool = False,
+    message_id: str | None = None,
+) -> tuple[dict[str, object] | None, str | None]:
+    tab = workspace_store.get_tab(tab_id)
+    if tab is None:
+        return None, f"Tab '{tab_id}' not found"
+    source_node = tab.definition.get_node(source_node_id)
+    target_node = tab.definition.get_node(target_node_id)
+    if source_node is None:
+        return None, f"Source node '{source_node_id}' not found"
+    if target_node is None:
+        return None, f"Target node '{target_node_id}' not found"
+    source_port = _port_matches(
+        source_node.outputs,
+        port_key=source_output_port_key,
+        direction=PortDirection.OUTPUT,
+    )
+    if source_port is None:
+        return None, f"Output port '{source_output_port_key}' is invalid"
+    target_port = _port_matches(
+        target_node.inputs,
+        port_key=target_input_port_key,
+        direction=PortDirection.INPUT,
+    )
+    if target_port is None:
+        return None, f"Input port '{target_input_port_key}' is invalid"
+    if source_port.type != target_port.type:
+        return (
+            None,
+            f"Port type mismatch: '{source_node.id}.{source_port.key}' is {source_port.type.value} "
+            f"but '{target_node.id}.{target_port.key}' is {target_port.type.value}",
+        )
+    if not _validate_typed_value(value, source_port.type):
+        return None, f"Value must match {source_port.type.value} port type"
+
+    edge = next(
+        (
+            item
+            for item in tab.definition.edges
+            if item.from_node_id == source_node_id
+            and item.to_node_id == target_node_id
+            and item.from_port_key == source_output_port_key
+            and item.to_port_key == target_input_port_key
+        ),
+        None,
+    )
+    if edge is None:
+        return None, "Send path is not connected"
+
+    value_summary = _summarize_port_value(value, port_type=source_port.type)
+    payload: dict[str, object] = {
+        "status": "sent",
+        "target_id": target_node_id,
+        "from_output_port_key": source_output_port_key,
+        "to_input_port_key": target_input_port_key,
+        "port_type": source_port.type.value,
+        "value_summary": value_summary,
+    }
+
+    target = registry.get(target_node_id)
+    if target is not None and target_node.type == WorkflowNodeKind.AGENT:
+        if source_port.type == PortType.PARTS:
+            parts = deserialize_content_parts(value)
+            if source_is_agent_send:
+                target._append_history(
+                    ReceivedMessage(
+                        from_id=source_node_id,
+                        parts=parts,
+                        message_id=message_id,
+                        from_output_port_key=source_output_port_key,
+                        to_input_port_key=target_input_port_key,
+                        value_summary=value_summary,
+                    )
+                )
+                target.enqueue_message(
+                    Message(
+                        from_id=source_node_id,
+                        to_id=target_node_id,
+                        parts=parts,
+                        message_id=message_id,
+                        history_recorded=True,
+                        from_output_port_key=source_output_port_key,
+                        to_input_port_key=target_input_port_key,
+                        port_type=source_port.type.value,
+                        value=value,
+                        value_summary=value_summary,
+                    )
+                )
+            else:
+                target._append_history(
+                    PortInboundEntry(
+                        from_id=source_node_id,
+                        from_output_port_key=source_output_port_key,
+                        to_input_port_key=target_input_port_key,
+                        port_type=source_port.type.value,
+                        value=value,
+                        source_label=_node_label_snapshot(tab_id, source_node_id),
+                        value_summary=value_summary,
+                    )
+                )
+                target.enqueue_message(
+                    Message(
+                        from_id=source_node_id,
+                        to_id=target_node_id,
+                        parts=parts,
+                        message_id=message_id,
+                        history_recorded=True,
+                        from_output_port_key=source_output_port_key,
+                        to_input_port_key=target_input_port_key,
+                        port_type=source_port.type.value,
+                        value=value,
+                        value_summary=value_summary,
+                        port_inbound_recorded=True,
+                    )
+                )
+        else:
+            target._append_history(
+                PortInboundEntry(
+                    from_id=source_node_id,
+                    from_output_port_key=source_output_port_key,
+                    to_input_port_key=target_input_port_key,
+                    port_type=source_port.type.value,
+                    value=value,
+                    source_label=_node_label_snapshot(tab_id, source_node_id),
+                    value_summary=value_summary,
+                )
+            )
+            target.enqueue_message(
+                Message(
+                    from_id=source_node_id,
+                    to_id=target_node_id,
+                    content=value_summary,
+                    message_id=message_id,
+                    history_recorded=True,
+                    from_output_port_key=source_output_port_key,
+                    to_input_port_key=target_input_port_key,
+                    port_type=source_port.type.value,
+                    value=value,
+                    value_summary=value_summary,
+                    port_inbound_recorded=True,
+                )
+            )
+
+    event_bus.emit(
+        Event(
+            type=EventType.NODE_MESSAGE,
+            agent_id=source_node_id,
+            data={
+                "to_id": target_node_id,
+                "content": value_summary,
+                "message_id": message_id,
+                "from_output_port_key": source_output_port_key,
+                "to_input_port_key": target_input_port_key,
+                "port_type": source_port.type.value,
+            },
+        ),
+    )
+    return payload, None
+
+
 def _sync_runtime_positions_into_definition(tab: Tab) -> bool:
     changed = False
     for record in workspace_store.list_node_records(tab.id):
@@ -290,6 +806,9 @@ def serialize_tab_summary(tab: Tab) -> dict[str, object]:
         "id": tab.id,
         "title": tab.title,
         "leader_id": tab.leader_id,
+        "activation_state": tab.activation_state.value,
+        "allow_network": tab.allow_network,
+        "write_dirs": list(tab.write_dirs),
         "created_at": tab.created_at,
         "updated_at": tab.updated_at,
         "definition": tab.definition.serialize(),
@@ -303,14 +822,8 @@ def _build_leader_record(
     tab_id: str,
     leader_id: str,
     settings,
-    allow_network: bool = False,
-    write_dirs: list[str] | None = None,
 ) -> GraphNodeRecord:
     role_name = resolve_leader_role_name(settings=settings)
-    normalized_write_dirs = build_assistant_write_dirs(
-        write_dirs or [],
-        field_name="write_dirs",
-    )
     return GraphNodeRecord(
         id=leader_id,
         config=NodeConfig(
@@ -319,13 +832,28 @@ def _build_leader_record(
             tab_id=tab_id,
             name=LEADER_NODE_NAME,
             tools=build_tools_for_role(role_name, settings=settings),
-            write_dirs=normalized_write_dirs,
-            allow_network=allow_network,
         ),
         state=AgentState.INITIALIZING,
     )
 
 
+def _sync_tab_permissions_from_legacy_leader(tab: Tab) -> bool:
+    if tab.permissions_initialized:
+        return False
+    tab.permissions_initialized = True
+    if not tab.leader_id:
+        workspace_store.upsert_tab(tab)
+        return False
+    record = workspace_store.get_node_record(tab.leader_id)
+    if record is None:
+        workspace_store.upsert_tab(tab)
+        return False
+    tab.allow_network = record.config.allow_network
+    tab.write_dirs = list(record.config.write_dirs)
+    workspace_store.upsert_tab(tab)
+    return True
+
+
 def _sync_leader_record(
     *,
     tab_id: str,
@@ -359,7 +887,19 @@ def _start_persisted_agent(
 ) -> tuple[GraphNodeRecord | None, str | None]:
     from flowent.agent import Agent
 
-    node = Agent(record.config, uuid=record.id)
+    allow_network, write_dirs = resolve_effective_permissions_for_node_record(record)
+    node = Agent(
+        NodeConfig(
+            node_type=record.config.node_type,
+            role_name=record.config.role_name,
+            tab_id=record.config.tab_id,
+            name=record.config.name,
+            tools=list(record.config.tools),
+            write_dirs=write_dirs,
+            allow_network=allow_network,
+        ),
+        uuid=record.id,
+    )
     registry.register(node)
     node.start()
     return workspace_store.get_node_record(record.id), None
@@ -416,6 +956,9 @@ def ensure_tab_leaders(*, start_nodes: bool = False) -> bool:
             workspace_store.upsert_tab(tab)
             changed = True
 
+        if _sync_tab_permissions_from_legacy_leader(tab):
+            changed = True
+
         if _sync_leader_record(tab_id=tab.id, record=leader_record, settings=settings):
             workspace_store.upsert_node_record(leader_record)
             changed = True
@@ -460,8 +1003,6 @@ def sync_tab_leaders(*, reason: str) -> None:
         live_node.config.role_name = record.config.role_name
         live_node.config.name = record.config.name
         live_node.config.tools = list(record.config.tools)
-        live_node.config.write_dirs = list(record.config.write_dirs)
-        live_node.config.allow_network = record.config.allow_network
         live_node._sync_system_prompt_entry()
         live_node.set_state(
             live_node.state,
@@ -514,14 +1055,18 @@ def create_tab(
         title=title.strip(),
         leader_id=leader_id,
         definition=WorkflowDefinition(),
+        allow_network=allow_network,
+        write_dirs=build_assistant_write_dirs(
+            write_dirs or [],
+            field_name="write_dirs",
+        ),
+        permissions_initialized=True,
     )
     workspace_store.upsert_tab(tab)
     leader_record = _build_leader_record(
         tab_id=tab.id,
         leader_id=leader_id,
         settings=settings,
-        allow_network=allow_network,
-        write_dirs=write_dirs,
     )
     workspace_store.upsert_node_record(leader_record)
     if registry.get_all():
@@ -544,13 +1089,7 @@ def duplicate_tab(
     if source_tab is None:
         return None, f"Tab '{tab_id}' not found"
 
-    leader_record = (
-        workspace_store.get_node_record(source_tab.leader_id)
-        if source_tab.leader_id
-        else None
-    )
-    allow_network = leader_record.config.allow_network if leader_record else False
-    write_dirs = list(leader_record.config.write_dirs) if leader_record else []
+    _sync_tab_permissions_from_legacy_leader(source_tab)
     duplicated_definition = WorkflowDefinition.from_mapping(
         source_tab.definition.serialize()
     )
@@ -589,6 +1128,9 @@ def duplicate_tab(
         id=str(uuid.uuid4()),
         title=f"{source_tab.title} Copy",
         leader_id=str(uuid.uuid4()),
+        allow_network=source_tab.allow_network,
+        write_dirs=list(source_tab.write_dirs),
+        permissions_initialized=True,
         definition=WorkflowDefinition(
             version=duplicated_definition.version,
             nodes=duplicated_nodes,
@@ -605,8 +1147,6 @@ def duplicate_tab(
             tab_id=new_tab.id,
             leader_id=new_tab.leader_id,
             settings=settings,
-            allow_network=allow_network,
-            write_dirs=write_dirs,
         )
     )
 
@@ -654,15 +1194,30 @@ def _is_path_within_boundary(path: str, boundary_dirs: list[str]) -> bool:
     )
 
 
-def _clamp_write_dirs_to_boundary(
-    write_dirs: list[str],
-    boundary_dirs: list[str],
-) -> list[str]:
-    if not boundary_dirs:
-        return []
-    return [
-        path for path in write_dirs if _is_path_within_boundary(path, boundary_dirs)
-    ]
+def resolve_effective_permissions_for_agent(agent) -> tuple[bool, list[str]]:
+    if agent.config.node_type == NodeType.ASSISTANT:
+        settings = settings_module.get_settings()
+        return settings.assistant.allow_network, list(settings.assistant.write_dirs)
+    if agent.config.tab_id:
+        tab = workspace_store.get_tab(agent.config.tab_id)
+        if tab is not None:
+            _sync_tab_permissions_from_legacy_leader(tab)
+            return tab.allow_network, list(tab.write_dirs)
+    return agent.config.allow_network, list(agent.config.write_dirs)
+
+
+def resolve_effective_permissions_for_node_record(
+    record: GraphNodeRecord,
+) -> tuple[bool, list[str]]:
+    if record.config.node_type == NodeType.ASSISTANT:
+        settings = settings_module.get_settings()
+        return settings.assistant.allow_network, list(settings.assistant.write_dirs)
+    if record.config.tab_id:
+        tab = workspace_store.get_tab(record.config.tab_id)
+        if tab is not None:
+            _sync_tab_permissions_from_legacy_leader(tab)
+            return tab.allow_network, list(tab.write_dirs)
+    return record.config.allow_network, list(record.config.write_dirs)
 
 
 def set_tab_permissions(
@@ -677,6 +1232,9 @@ def set_tab_permissions(
     tab = workspace_store.get_tab(tab_id)
     if tab is None:
         return None, f"Tab '{tab_id}' not found"
+    _sync_tab_permissions_from_legacy_leader(tab)
+    if _is_active(tab):
+        return None, _active_edit_error("permissions")
 
     leader_id = get_tab_leader_id(tab_id)
     if not leader_id:
@@ -703,64 +1261,29 @@ def set_tab_permissions(
                 "write_dirs boundary exceeded: " + ", ".join(invalid_write_dirs),
             )
 
-    next_allow_network = (
-        leader_record.config.allow_network if allow_network is None else allow_network
-    )
-    next_write_dirs = (
-        list(leader_record.config.write_dirs)
-        if write_dirs is None
-        else list(write_dirs)
-    )
+    next_allow_network = tab.allow_network if allow_network is None else allow_network
+    next_write_dirs = list(tab.write_dirs) if write_dirs is None else list(write_dirs)
 
     changed_node_ids: list[str] = []
-
-    if (
-        leader_record.config.allow_network != next_allow_network
-        or leader_record.config.write_dirs != next_write_dirs
-    ):
-        leader_record.config.allow_network = next_allow_network
-        leader_record.config.write_dirs = list(next_write_dirs)
-        workspace_store.upsert_node_record(leader_record)
-        changed_node_ids.append(leader_record.id)
-
-    for record in list_tab_nodes(tab_id):
-        if record.id == leader_id:
-            continue
-        next_node_allow_network = record.config.allow_network and next_allow_network
-        next_node_write_dirs = _clamp_write_dirs_to_boundary(
-            record.config.write_dirs,
-            next_write_dirs,
-        )
-        if (
-            record.config.allow_network == next_node_allow_network
-            and record.config.write_dirs == next_node_write_dirs
-        ):
-            continue
-        record.config.allow_network = next_node_allow_network
-        record.config.write_dirs = list(next_node_write_dirs)
-        workspace_store.upsert_node_record(record)
-        changed_node_ids.append(record.id)
-
-        live_node = registry.get(record.id)
+    if tab.allow_network != next_allow_network or tab.write_dirs != next_write_dirs:
+        tab.allow_network = next_allow_network
+        tab.write_dirs = list(next_write_dirs)
+        workspace_store.upsert_tab(tab)
+        changed_node_ids = [
+            record.id for record in list_tab_nodes(tab_id) if record.id != leader_id
+        ]
+        if leader_record.id:
+            changed_node_ids.insert(0, leader_record.id)
+
+    for node_id in changed_node_ids:
+        live_node = registry.get(node_id)
         if live_node is not None:
-            live_node.config.allow_network = next_node_allow_network
-            live_node.config.write_dirs = list(next_node_write_dirs)
             live_node.set_state(
                 live_node.state,
                 "tab_permissions_updated",
                 force_emit=True,
             )
 
-    live_leader = registry.get(leader_id)
-    if live_leader is not None:
-        live_leader.config.allow_network = next_allow_network
-        live_leader.config.write_dirs = list(next_write_dirs)
-        live_leader.set_state(
-            live_leader.state,
-            "tab_permissions_updated",
-            force_emit=True,
-        )
-
     updated_tab = workspace_store.get_tab(tab_id)
     if updated_tab is not None:
         event_bus.emit(
@@ -791,6 +1314,17 @@ def delete_tab(
     tab = workspace_store.get_tab(tab_id)
     if tab is None:
         return None, f"Tab '{tab_id}' not found"
+    if _is_active(tab):
+        _, deactivate_error = deactivate_tab(
+            tab_id=tab_id,
+            actor_id="assistant",
+            timeout=timeout,
+        )
+        if deactivate_error is not None:
+            return None, deactivate_error
+        tab = workspace_store.get_tab(tab_id)
+        if tab is None:
+            return None, f"Tab '{tab_id}' not found"
 
     stored_nodes = list_tab_nodes(tab_id)
     live_nodes = [node for node in registry.get_all() if node.config.tab_id == tab_id]
@@ -843,8 +1377,6 @@ def build_node_config(
     tab_id: str,
     name: str | None = None,
     tools: list[str] | None = None,
-    write_dirs: list[str] | None = None,
-    allow_network: bool = False,
 ) -> tuple[NodeConfig | None, str | None]:
     settings = settings_module.get_settings()
     role = find_role(settings, role_name.strip())
@@ -854,16 +1386,6 @@ def build_node_config(
     requested_tools = tools or []
     if not all(isinstance(item, str) for item in requested_tools):
         return None, "tools must be an array of strings"
-    requested_write_dirs = write_dirs or []
-    if not all(isinstance(item, str) for item in requested_write_dirs):
-        return None, "write_dirs must be an array of strings"
-    try:
-        normalized_write_dirs = build_assistant_write_dirs(
-            requested_write_dirs,
-            field_name="write_dirs",
-        )
-    except ValueError as exc:
-        return None, str(exc)
 
     return (
         NodeConfig(
@@ -876,8 +1398,6 @@ def build_node_config(
                 requested_tools=requested_tools,
                 settings=settings,
             ),
-            write_dirs=normalized_write_dirs,
-            allow_network=allow_network,
         ),
         None,
     )
@@ -889,6 +1409,14 @@ def _persist_tab(tab: Tab, *, actor_id: str) -> Tab:
     return tab
 
 
+def _is_active(tab: Tab) -> bool:
+    return tab.activation_state == WorkflowActivationState.ACTIVE
+
+
+def _active_edit_error(noun: str) -> str:
+    return f"Workflow is active; deactivate it before changing {noun}"
+
+
 def create_graph_node(
     *,
     tab_id: str,
@@ -899,6 +1427,8 @@ def create_graph_node(
     tab = workspace_store.get_tab(tab_id)
     if tab is None:
         return None, f"Tab '{tab_id}' not found"
+    if _is_active(tab):
+        return None, _active_edit_error("nodes")
     node_id = str(uuid.uuid4())
     node = build_workflow_node_definition(
         node_id=node_id,
@@ -916,8 +1446,6 @@ def create_agent_node(
     tab_id: str,
     name: str | None = None,
     tools: list[str] | None = None,
-    write_dirs: list[str] | None = None,
-    allow_network: bool = False,
     creator_node_id: str | None = None,
     connect_to_creator: bool | None = None,
 ) -> tuple[GraphNodeRecord | None, str | None]:
@@ -925,14 +1453,14 @@ def create_agent_node(
     tab = workspace_store.get_tab(tab_id)
     if tab is None:
         return None, f"Tab '{tab_id}' not found"
+    if _is_active(tab):
+        return None, _active_edit_error("nodes")
 
     config, error = build_node_config(
         role_name=role_name,
         tab_id=tab_id,
         name=name,
         tools=tools,
-        write_dirs=write_dirs,
-        allow_network=allow_network,
     )
     if error is not None or config is None:
         return None, error
@@ -980,6 +1508,10 @@ def update_tab_definition(
     edge_ids = [edge.id for edge in next_definition.edges]
     if len(edge_ids) != len(set(edge_ids)):
         return None, "Workflow definition contains duplicate edge ids"
+    if _is_active(tab) and _semantic_definition(tab.definition) != _semantic_definition(
+        next_definition
+    ):
+        return None, _active_edit_error("workflow structure")
 
     current_agent_ids = {
         node.id for node in tab.definition.nodes if node.type == WorkflowNodeKind.AGENT
@@ -1010,8 +1542,6 @@ def update_tab_definition(
             name=str(node.config["name"])
             if isinstance(node.config.get("name"), str)
             else None,
-            write_dirs=list(record.config.write_dirs),
-            allow_network=record.config.allow_network,
         )
         if error is not None or config is None:
             return None, error or f"Failed to validate agent node '{node.id}'"
@@ -1043,7 +1573,6 @@ def update_tab_definition(
             source_node.outputs,
             port_key=edge.from_port_key,
             direction=PortDirection.OUTPUT,
-            kind=edge.kind,
         )
         if source_port is None:
             return None, f"Output port '{edge.from_port_key}' is invalid"
@@ -1051,10 +1580,15 @@ def update_tab_definition(
             target_node.inputs,
             port_key=edge.to_port_key,
             direction=PortDirection.INPUT,
-            kind=edge.kind,
         )
         if target_port is None:
             return None, f"Input port '{edge.to_port_key}' is invalid"
+        if source_port.type != target_port.type:
+            return (
+                None,
+                f"Port type mismatch: '{source_node.id}.{source_port.key}' is {source_port.type.value} "
+                f"but '{target_node.id}.{target_port.key}' is {target_port.type.value}",
+            )
         target_key = (edge.to_node_id, edge.to_port_key)
         if target_key in seen_target_ports and not target_port.multiple:
             return None, f"Input port '{edge.to_port_key}' already has an incoming edge"
@@ -1070,20 +1604,640 @@ def _port_matches(
     *,
     port_key: str,
     direction: PortDirection,
-    kind: EdgeKind,
 ) -> WorkflowPort | None:
     return next(
         (
             port
             for port in ports
-            if port.key == port_key
-            and port.direction == direction
-            and port.kind == kind
+            if port.key == port_key and port.direction == direction
         ),
         None,
     )
 
 
+def _semantic_definition(definition: WorkflowDefinition) -> dict[str, object]:
+    payload = definition.serialize()
+    payload.pop("view", None)
+    return payload
+
+
+_PORT_TYPES = {item.value for item in PortType}
+_TRIGGER_KINDS = {"manual", "cron"}
+_LLM_RESPONSE_FORMAT_KINDS = {"text", "json_schema"}
+_IF_OPERATORS = {
+    "eq",
+    "neq",
+    "contains",
+    "not_contains",
+    "is_empty",
+    "is_not_empty",
+    "gt",
+    "lt",
+    "gte",
+    "lte",
+    "is_truthy",
+    "is_falsy",
+}
+_MERGE_STRATEGIES = {"collect", "named_object", "first_completed"}
+_CODE_RUNTIMES = {"javascript", "python"}
+
+
+def _validation_error(
+    errors: list[dict[str, str]],
+    *,
+    message: str,
+    node_id: str | None = None,
+    edge_id: str | None = None,
+    path: str | None = None,
+) -> None:
+    error: dict[str, str] = {"message": message}
+    if node_id is not None:
+        error["node_id"] = node_id
+    if edge_id is not None:
+        error["edge_id"] = edge_id
+    if path is not None:
+        error["path"] = path
+    errors.append(error)
+
+
+def _is_json_serializable(value: object) -> bool:
+    try:
+        json.dumps(value)
+    except (TypeError, ValueError):
+        return False
+    return True
+
+
+def _is_valid_parts_value(value: object) -> bool:
+    if not isinstance(value, list) or not value:
+        return False
+    for part in value:
+        if not isinstance(part, dict):
+            return False
+        part_type = part.get("type")
+        if part_type == "text":
+            text = part.get("text")
+            if not isinstance(text, str) or not text:
+                return False
+            continue
+        if part_type == "image":
+            asset_id = part.get("asset_id")
+            if not isinstance(asset_id, str) or not asset_id.strip():
+                return False
+            continue
+        return False
+    return True
+
+
+def _validate_typed_value(value: object, port_type: PortType) -> bool:
+    if port_type == PortType.PARTS:
+        return _is_valid_parts_value(value)
+    if port_type == PortType.STRING:
+        return isinstance(value, str) and bool(value)
+    return isinstance(value, dict) and _is_json_serializable(value)
+
+
+def _get_string_config(config: dict[str, object], key: str) -> str:
+    value = config.get(key)
+    return value.strip() if isinstance(value, str) else ""
+
+
+def _parse_response_format_kind(value: object) -> str:
+    if isinstance(value, str):
+        return value.strip()
+    if isinstance(value, dict):
+        kind = value.get("kind")
+        return kind.strip() if isinstance(kind, str) else ""
+    return ""
+
+
+def _response_format_schema(value: object) -> object:
+    if not isinstance(value, dict):
+        return None
+    return value.get("schema")
+
+
+def _validate_cron_expression(value: object) -> bool:
+    if not isinstance(value, str):
+        return False
+    fields = value.split()
+    if len(fields) not in {5, 6}:
+        return False
+    return all(field.strip() for field in fields)
+
+
+def _validate_timezone(value: object) -> bool:
+    if not isinstance(value, str) or not value.strip():
+        return False
+    try:
+        ZoneInfo(value.strip())
+    except ZoneInfoNotFoundError:
+        return False
+    return True
+
+
+def _validate_trigger_node(
+    node: WorkflowNodeDefinition,
+    errors: list[dict[str, str]],
+) -> None:
+    kind = _get_string_config(node.config, "kind")
+    if kind not in _TRIGGER_KINDS:
+        _validation_error(
+            errors,
+            node_id=node.id,
+            path="config.kind",
+            message="trigger kind must be manual or cron",
+        )
+    output_type = _coerce_port_type(node.config.get("output_type"), PortType.PARTS)
+    if str(node.config.get("output_type", output_type.value)) not in _PORT_TYPES:
+        _validation_error(
+            errors,
+            node_id=node.id,
+            path="config.output_type",
+            message="trigger output_type must be parts, string, or json",
+        )
+    if not node.outputs or any(port.type != output_type for port in node.outputs):
+        _validation_error(
+            errors,
+            node_id=node.id,
+            path="outputs",
+            message="trigger output port type must match config.output_type",
+        )
+    if "message" not in node.config or not _validate_typed_value(
+        node.config.get("message"),
+        output_type,
+    ):
+        _validation_error(
+            errors,
+            node_id=node.id,
+            path="config.message",
+            message="trigger message must match output_type",
+        )
+    if kind == "cron":
+        if not _validate_cron_expression(node.config.get("cron")):
+            _validation_error(
+                errors,
+                node_id=node.id,
+                path="config.cron",
+                message="cron trigger requires a 5-field or 6-field expression",
+            )
+        if not _validate_timezone(node.config.get("timezone")):
+            _validation_error(
+                errors,
+                node_id=node.id,
+                path="config.timezone",
+                message="cron trigger requires an IANA timezone",
+            )
+
+
+def _resolve_llm_model(
+    node: WorkflowNodeDefinition,
+) -> tuple[str, str]:
+    model_config = node.config.get("model")
+    if isinstance(model_config, dict):
+        provider_id = model_config.get("provider_id")
+        model = model_config.get("model")
+        return (
+            provider_id.strip() if isinstance(provider_id, str) else "",
+            model.strip() if isinstance(model, str) else "",
+        )
+    provider_id = node.config.get("provider_id")
+    model = node.config.get("model")
+    return (
+        provider_id.strip() if isinstance(provider_id, str) else "",
+        model.strip() if isinstance(model, str) else "",
+    )
+
+
+def _validate_llm_node(
+    node: WorkflowNodeDefinition,
+    errors: list[dict[str, str]],
+) -> None:
+    input_type = _coerce_port_type(node.config.get("input_type"), PortType.PARTS)
+    output_type = _coerce_port_type(node.config.get("output_type"), PortType.PARTS)
+    if str(node.config.get("input_type", input_type.value)) not in _PORT_TYPES:
+        _validation_error(
+            errors,
+            node_id=node.id,
+            path="config.input_type",
+            message="llm input_type must be parts, string, or json",
+        )
+    if str(node.config.get("output_type", output_type.value)) not in _PORT_TYPES:
+        _validation_error(
+            errors,
+            node_id=node.id,
+            path="config.output_type",
+            message="llm output_type must be parts, string, or json",
+        )
+    response_format = node.config.get("response_format", {"kind": "text"})
+    response_format_kind = _parse_response_format_kind(response_format)
+    if response_format_kind not in _LLM_RESPONSE_FORMAT_KINDS:
+        _validation_error(
+            errors,
+            node_id=node.id,
+            path="config.response_format",
+            message="llm response_format must be text or json_schema",
+        )
+    if response_format_kind == "json_schema":
+        schema = _response_format_schema(response_format)
+        if not isinstance(schema, dict) or not _is_json_serializable(schema):
+            _validation_error(
+                errors,
+                node_id=node.id,
+                path="config.response_format.schema",
+                message="json_schema response_format requires a JSON schema object",
+            )
+        if output_type != PortType.JSON:
+            _validation_error(
+                errors,
+                node_id=node.id,
+                path="config.output_type",
+                message="json_schema response_format requires json output_type",
+            )
+    elif output_type == PortType.JSON:
+        _validation_error(
+            errors,
+            node_id=node.id,
+            path="config.output_type",
+            message="text response_format requires parts or string output_type",
+        )
+    provider_id, model_id = _resolve_llm_model(node)
+    settings = settings_module.get_settings()
+    provider = find_provider(settings, provider_id)
+    if provider is None:
+        _validation_error(
+            errors,
+            node_id=node.id,
+            path="config.model",
+            message="llm model provider was not found",
+        )
+        return
+    if not model_id:
+        _validation_error(
+            errors,
+            node_id=node.id,
+            path="config.model",
+            message="llm model must not be empty",
+        )
+        return
+    if provider.models and all(entry.model != model_id for entry in provider.models):
+        _validation_error(
+            errors,
+            node_id=node.id,
+            path="config.model",
+            message="llm model is not in the provider model catalog",
+        )
+        return
+    model_info = resolve_model_info(provider=provider, model_id=model_id)
+    if (
+        response_format_kind == "json_schema"
+        and not model_info.capabilities.structured_output
+    ):
+        _validation_error(
+            errors,
+            node_id=node.id,
+            path="config.model",
+            message="llm model does not support structured_output",
+        )
+
+
+def _validate_if_node(
+    node: WorkflowNodeDefinition,
+    errors: list[dict[str, str]],
+) -> None:
+    expression = node.config.get("expression")
+    if not isinstance(expression, dict):
+        _validation_error(
+            errors,
+            node_id=node.id,
+            path="config.expression",
+            message="if expression must be an object",
+        )
+        return
+    field = expression.get("field")
+    operator = expression.get("operator")
+    if not isinstance(field, str) or not field.strip().startswith("{{input."):
+        _validation_error(
+            errors,
+            node_id=node.id,
+            path="config.expression.field",
+            message="if expression field must reference an input path",
+        )
+    if not isinstance(operator, str) or operator not in _IF_OPERATORS:
+        _validation_error(
+            errors,
+            node_id=node.id,
+            path="config.expression.operator",
+            message="if expression operator is not supported",
+        )
+    if (
+        operator in {"eq", "neq", "contains", "not_contains", "gt", "lt", "gte", "lte"}
+        and "value" not in expression
+    ):
+        _validation_error(
+            errors,
+            node_id=node.id,
+            path="config.expression.value",
+            message="if expression operator requires a value",
+        )
+    input_type = _coerce_port_type(node.config.get("input_type"), PortType.PARTS)
+    if any(port.type != input_type for port in node.inputs + node.outputs):
+        _validation_error(
+            errors,
+            node_id=node.id,
+            path="ports",
+            message="if node input and output port types must match",
+        )
+
+
+def _validate_merge_node(
+    node: WorkflowNodeDefinition,
+    errors: list[dict[str, str]],
+) -> None:
+    strategy = _get_string_config(node.config, "strategy") or "collect"
+    if strategy not in _MERGE_STRATEGIES:
+        _validation_error(
+            errors,
+            node_id=node.id,
+            path="config.strategy",
+            message="merge strategy must be collect, named_object, or first_completed",
+        )
+    if strategy == "named_object" and not isinstance(
+        node.config.get("named_inputs"),
+        dict,
+    ):
+        _validation_error(
+            errors,
+            node_id=node.id,
+            path="config.named_inputs",
+            message="named_object merge requires named_inputs",
+        )
+    if not node.inputs or not node.inputs[0].multiple:
+        _validation_error(
+            errors,
+            node_id=node.id,
+            path="inputs",
+            message="merge input port must allow multiple upstream values",
+        )
+
+
+def _validate_code_node(
+    node: WorkflowNodeDefinition,
+    errors: list[dict[str, str]],
+) -> None:
+    runtime = _get_string_config(node.config, "runtime")
+    source = node.config.get("source")
+    if runtime not in _CODE_RUNTIMES:
+        _validation_error(
+            errors,
+            node_id=node.id,
+            path="config.runtime",
+            message="code runtime must be javascript or python",
+        )
+    if not isinstance(source, str) or not source.strip():
+        _validation_error(
+            errors,
+            node_id=node.id,
+            path="config.source",
+            message="code source must not be empty",
+        )
+        return
+    if runtime == "python":
+        try:
+            ast.parse(source)
+        except SyntaxError as exc:
+            _validation_error(
+                errors,
+                node_id=node.id,
+                path="config.source",
+                message=f"python source is not parseable: {exc.msg}",
+            )
+    elif runtime == "javascript" and shutil.which("node"):
+        completed = subprocess.run(
+            ["node", "--check"],
+            input=source,
+            text=True,
+            capture_output=True,
+            timeout=5,
+            check=False,
+        )
+        if completed.returncode != 0:
+            _validation_error(
+                errors,
+                node_id=node.id,
+                path="config.source",
+                message="javascript source is not parseable",
+            )
+
+
+def _validate_node_config(
+    node: WorkflowNodeDefinition,
+    errors: list[dict[str, str]],
+) -> None:
+    if node.type == WorkflowNodeKind.TRIGGER:
+        _validate_trigger_node(node, errors)
+    elif node.type == WorkflowNodeKind.LLM:
+        _validate_llm_node(node, errors)
+    elif node.type == WorkflowNodeKind.IF:
+        _validate_if_node(node, errors)
+    elif node.type == WorkflowNodeKind.MERGE:
+        _validate_merge_node(node, errors)
+    elif node.type == WorkflowNodeKind.CODE:
+        _validate_code_node(node, errors)
+
+
+def _is_legacy_required_agent_input(
+    node: WorkflowNodeDefinition,
+    port: WorkflowPort,
+) -> bool:
+    return (
+        node.type == WorkflowNodeKind.AGENT
+        and port.key == "in"
+        and port.direction == PortDirection.INPUT
+        and port.type == PortType.PARTS
+        and not port.multiple
+    )
+
+
+def validate_workflow_activation(tab: Tab) -> list[dict[str, str]]:
+    errors: list[dict[str, str]] = []
+    if not tab.definition.nodes:
+        _validation_error(
+            errors,
+            message="Add at least one node before activating this workflow",
+            path="definition.nodes",
+        )
+    node_ids = [node.id for node in tab.definition.nodes]
+    if len(node_ids) != len(set(node_ids)):
+        _validation_error(
+            errors,
+            message="workflow definition contains duplicate node ids",
+            path="definition.nodes",
+        )
+    edge_ids = [edge.id for edge in tab.definition.edges]
+    if len(edge_ids) != len(set(edge_ids)):
+        _validation_error(
+            errors,
+            message="workflow definition contains duplicate edge ids",
+            path="definition.edges",
+        )
+    incoming_edges_by_port: dict[tuple[str, str], list[GraphEdge]] = {}
+    seen_edge_endpoints: set[tuple[str, str, str, str]] = set()
+    for edge in tab.definition.edges:
+        edge_endpoint = (
+            edge.from_node_id,
+            edge.from_port_key,
+            edge.to_node_id,
+            edge.to_port_key,
+        )
+        if edge_endpoint in seen_edge_endpoints:
+            _validation_error(
+                errors,
+                edge_id=edge.id,
+                message="duplicate edges are not allowed",
+            )
+        seen_edge_endpoints.add(edge_endpoint)
+        source_node = tab.definition.get_node(edge.from_node_id)
+        target_node = tab.definition.get_node(edge.to_node_id)
+        if source_node is None:
+            _validation_error(
+                errors,
+                edge_id=edge.id,
+                message=f"edge source node '{edge.from_node_id}' does not exist",
+            )
+            continue
+        if target_node is None:
+            _validation_error(
+                errors,
+                edge_id=edge.id,
+                message=f"edge target node '{edge.to_node_id}' does not exist",
+            )
+            continue
+        source_port = _port_matches(
+            source_node.outputs,
+            port_key=edge.from_port_key,
+            direction=PortDirection.OUTPUT,
+        )
+        target_port = _port_matches(
+            target_node.inputs,
+            port_key=edge.to_port_key,
+            direction=PortDirection.INPUT,
+        )
+        if source_port is None:
+            _validation_error(
+                errors,
+                edge_id=edge.id,
+                path="from_port_key",
+                message=f"output port '{edge.from_port_key}' is invalid",
+            )
+            continue
+        if target_port is None:
+            _validation_error(
+                errors,
+                edge_id=edge.id,
+                path="to_port_key",
+                message=f"input port '{edge.to_port_key}' is invalid",
+            )
+            continue
+        if source_port.type != target_port.type:
+            _validation_error(
+                errors,
+                edge_id=edge.id,
+                message=(
+                    f"port type mismatch: '{source_node.id}.{source_port.key}' is {source_port.type.value} "
+                    f"but '{target_node.id}.{target_port.key}' is {target_port.type.value}"
+                ),
+            )
+        incoming_edges_by_port.setdefault(
+            (edge.to_node_id, edge.to_port_key), []
+        ).append(edge)
+    for node in tab.definition.nodes:
+        for port in node.inputs:
+            edges = incoming_edges_by_port.get((node.id, port.key), [])
+            if (
+                port.required
+                and not edges
+                and not _is_legacy_required_agent_input(node, port)
+            ):
+                _validation_error(
+                    errors,
+                    node_id=node.id,
+                    path=f"inputs.{port.key}",
+                    message=f"required input port '{port.key}' has no upstream edge",
+                )
+            if len(edges) > 1 and not port.multiple:
+                _validation_error(
+                    errors,
+                    node_id=node.id,
+                    path=f"inputs.{port.key}",
+                    message=f"input port '{port.key}' accepts only one upstream edge",
+                )
+        _validate_node_config(node, errors)
+    return errors
+
+
+def activate_tab(
+    *,
+    tab_id: str,
+    actor_id: str = "assistant",
+) -> tuple[Tab | None, list[dict[str, str]] | None, str | None]:
+    tab = workspace_store.get_tab(tab_id)
+    if tab is None:
+        return None, None, f"Tab '{tab_id}' not found"
+    errors = validate_workflow_activation(tab)
+    if errors:
+        return None, errors, None
+    if tab.activation_state != WorkflowActivationState.ACTIVE:
+        tab.activation_state = WorkflowActivationState.ACTIVE
+        _persist_tab(tab, actor_id=actor_id)
+    return tab, None, None
+
+
+def deactivate_tab(
+    *,
+    tab_id: str,
+    actor_id: str = "assistant",
+    timeout: float = SYSTEM_NODE_TIMEOUT,
+) -> tuple[Tab | None, str | None]:
+    tab = workspace_store.get_tab(tab_id)
+    if tab is None:
+        return None, f"Tab '{tab_id}' not found"
+
+    lingering_node_ids: list[str] = []
+    ordinary_node_ids = {
+        node.id
+        for node in tab.definition.nodes
+        if node.type == WorkflowNodeKind.AGENT
+        and not is_tab_leader(node_id=node.id, tab_id=tab_id)
+    }
+    for node_id in ordinary_node_ids:
+        live_node = registry.get(node_id)
+        if live_node is not None:
+            if live_node.state in {AgentState.RUNNING, AgentState.SLEEPING}:
+                live_node.request_interrupt()
+                if not live_node.wait_until_idle(timeout=timeout):
+                    lingering_node_ids.append(live_node.uuid)
+            continue
+        record = workspace_store.get_node_record(node_id)
+        if record is None:
+            continue
+        if record.state in {AgentState.RUNNING, AgentState.SLEEPING}:
+            record.state = AgentState.IDLE
+            workspace_store.upsert_node_record(record)
+
+    if lingering_node_ids:
+        return (
+            None,
+            "Failed to deactivate workflow because some nodes did not stop: "
+            + ", ".join(node_id[:8] for node_id in lingering_node_ids),
+        )
+
+    if tab.activation_state != WorkflowActivationState.INACTIVE:
+        tab.activation_state = WorkflowActivationState.INACTIVE
+        _persist_tab(tab, actor_id=actor_id)
+    return tab, None
+
+
 def create_edge(
     *,
     tab_id: str | None = None,
@@ -1093,7 +2247,7 @@ def create_edge(
     to_port_key: str = "in",
     kind: EdgeKind | str = EdgeKind.CONTROL,
 ) -> tuple[GraphEdge | None, str | None]:
-    resolved_kind = kind if isinstance(kind, EdgeKind) else EdgeKind(str(kind))
+    del kind
     resolved_tab_id = tab_id
     if resolved_tab_id is None:
         source_record = workspace_store.get_node_record(from_node_id)
@@ -1107,6 +2261,8 @@ def create_edge(
     tab = workspace_store.get_tab(resolved_tab_id)
     if tab is None:
         return None, f"Tab '{resolved_tab_id}' not found"
+    if _is_active(tab):
+        return None, _active_edit_error("edges")
     if is_tab_leader(node_id=from_node_id, tab_id=resolved_tab_id) or is_tab_leader(
         node_id=to_node_id,
         tab_id=resolved_tab_id,
@@ -1124,7 +2280,6 @@ def create_edge(
         source_node.outputs,
         port_key=from_port_key,
         direction=PortDirection.OUTPUT,
-        kind=resolved_kind,
     )
     if source_port is None:
         return None, f"Output port '{from_port_key}' is invalid"
@@ -1132,16 +2287,20 @@ def create_edge(
         target_node.inputs,
         port_key=to_port_key,
         direction=PortDirection.INPUT,
-        kind=resolved_kind,
     )
     if target_port is None:
         return None, f"Input port '{to_port_key}' is invalid"
+    if source_port.type != target_port.type:
+        return (
+            None,
+            f"Port type mismatch: '{source_node.id}.{source_port.key}' is {source_port.type.value} "
+            f"but '{target_node.id}.{target_port.key}' is {target_port.type.value}",
+        )
     if any(
         edge.from_node_id == from_node_id
         and edge.from_port_key == from_port_key
         and edge.to_node_id == to_node_id
         and edge.to_port_key == to_port_key
-        and edge.kind == resolved_kind
         for edge in tab.definition.edges
     ):
         return None, "Duplicate edges are not allowed"
@@ -1158,7 +2317,6 @@ def create_edge(
         from_port_key=from_port_key,
         to_node_id=to_node_id,
         to_port_key=to_port_key,
-        kind=resolved_kind,
     )
     tab.definition.edges.append(edge)
     _persist_tab(tab, actor_id=from_node_id)
@@ -1177,6 +2335,8 @@ def delete_edge(
     tab = workspace_store.get_tab(tab_id)
     if tab is None:
         return None, f"Tab '{tab_id}' not found"
+    if _is_active(tab):
+        return None, _active_edit_error("edges")
 
     matched_edge: GraphEdge | None = None
     for edge in tab.definition.edges:
@@ -1212,6 +2372,8 @@ def delete_agent_node(
     tab = workspace_store.get_tab(tab_id)
     if tab is None:
         return None, f"Tab '{tab_id}' not found"
+    if _is_active(tab):
+        return None, _active_edit_error("nodes")
 
     node_definition = tab.definition.get_node(node_id)
     if node_definition is None: