flowent 0.0.1 → 0.0.5

package/backend/src/flowent/graph_service.py

@@ -0,0 +1,2508 @@
+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
+from flowent.models import (
+    AgentState,
+    EdgeKind,
+    Event,
+    EventType,
+    GraphEdge,
+    GraphNodeRecord,
+    Message,
+    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
+from flowent.settings import (
+    CONDUCTOR_ROLE_INCLUDED_TOOLS,
+    CONDUCTOR_ROLE_NAME,
+    DESIGNER_ROLE_INCLUDED_TOOLS,
+    DESIGNER_ROLE_NAME,
+    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,
+    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()
+    role = find_role(current_settings, normalized_role_name)
+    if role is None:
+        if normalized_role_name == CONDUCTOR_ROLE_NAME:
+            included_tools = list(CONDUCTOR_ROLE_INCLUDED_TOOLS)
+        elif normalized_role_name == DESIGNER_ROLE_NAME:
+            included_tools = list(DESIGNER_ROLE_INCLUDED_TOOLS)
+        elif normalized_role_name == STEWARD_ROLE_NAME:
+            included_tools = list(STEWARD_ROLE_INCLUDED_TOOLS)
+        else:
+            included_tools = []
+        excluded_tools: set[str] = set()
+    else:
+        included_tools = list(role.included_tools)
+        excluded_tools = set(role.excluded_tools)
+
+    final_tools: list[str] = []
+    seen_tools: set[str] = set()
+    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)
+        seen_tools.add(tool_name)
+    return final_tools
+
+
+def build_assistant_tools(*, settings=None) -> list[str]:
+    current_settings = settings or settings_module.get_settings()
+    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()
+    for tool_name in [
+        *MINIMUM_TOOLS,
+        *STEWARD_ROLE_INCLUDED_TOOLS,
+        *assistant_tools,
+    ]:
+        if tool_name in seen_tools:
+            continue
+        final_tools.append(tool_name)
+        seen_tools.add(tool_name)
+    return final_tools
+
+
+def resolve_leader_role_name(*, settings=None) -> str:
+    current_settings = settings or settings_module.get_settings()
+    configured_role_name = current_settings.leader.role_name.strip()
+    if configured_role_name and find_role(current_settings, configured_role_name):
+        return configured_role_name
+    return CONDUCTOR_ROLE_NAME
+
+
+def get_tab_leader_id(tab_id: str) -> str | None:
+    tab = workspace_store.get_tab(tab_id)
+    if tab is None:
+        return None
+    return tab.leader_id
+
+
+def is_tab_leader(*, node_id: str, tab_id: str | None = None) -> bool:
+    resolved_tab_id = tab_id
+    if resolved_tab_id is None:
+        record = workspace_store.get_node_record(node_id)
+        if record is not None:
+            resolved_tab_id = record.config.tab_id
+        else:
+            live_node = registry.get(node_id)
+            resolved_tab_id = live_node.config.tab_id if live_node is not None else None
+    if not resolved_tab_id:
+        return False
+    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,
+                    type=output_type,
+                    multiple=True,
+                )
+            ],
+        )
+    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,
+                    type=input_type,
+                    required=True,
+                )
+            ],
+            [
+                WorkflowPort(
+                    key="out",
+                    direction=PortDirection.OUTPUT,
+                    type=output_type,
+                    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,
+                    type=input_type,
+                    required=True,
+                ),
+            ],
+            [
+                WorkflowPort(
+                    key="then",
+                    direction=PortDirection.OUTPUT,
+                    type=input_type,
+                    multiple=True,
+                ),
+                WorkflowPort(
+                    key="else",
+                    direction=PortDirection.OUTPUT,
+                    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,
+                    type=input_type,
+                    required=True,
+                    multiple=True,
+                )
+            ],
+            [
+                WorkflowPort(
+                    key="out",
+                    direction=PortDirection.OUTPUT,
+                    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,
+                )
+            ],
+        )
+    return (
+        [
+            WorkflowPort(
+                key="in",
+                direction=PortDirection.INPUT,
+                type=PortType.PARTS,
+                required=True,
+            )
+        ],
+        [
+            WorkflowPort(
+                key="out",
+                direction=PortDirection.OUTPUT,
+                type=PortType.PARTS,
+                multiple=True,
+            )
+        ],
+    )
+
+
+def build_workflow_node_definition(
+    *,
+    node_id: str,
+    node_kind: WorkflowNodeKind,
+    config: dict[str, object] | None = None,
+) -> WorkflowNodeDefinition:
+    inputs, outputs = _default_ports(node_kind, config)
+    return WorkflowNodeDefinition(
+        id=node_id,
+        type=node_kind,
+        config=deepcopy(config or {}),
+        inputs=inputs,
+        outputs=outputs,
+    )
+
+
+def list_workflow_nodes(tab_id: str) -> list[WorkflowNodeDefinition]:
+    tab = workspace_store.get_tab(tab_id)
+    if tab is None:
+        return []
+    return list(tab.definition.nodes)
+
+
+def get_workflow_node(tab_id: str, node_id: str) -> WorkflowNodeDefinition | None:
+    tab = workspace_store.get_tab(tab_id)
+    if tab is None:
+        return None
+    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):
+        if is_tab_leader(node_id=record.id, tab_id=tab.id):
+            continue
+        if record.position is None:
+            continue
+        current = tab.definition.view.positions.get(record.id)
+        if current == record.position:
+            continue
+        tab.definition.view.positions[record.id] = record.position
+        changed = True
+    return changed
+
+
+def serialize_tab_summary(tab: Tab) -> dict[str, object]:
+    if _sync_runtime_positions_into_definition(tab):
+        workspace_store.upsert_tab(tab)
+    return {
+        "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(),
+        "node_count": len(tab.definition.nodes),
+        "edge_count": len(tab.definition.edges),
+    }
+
+
+def _build_leader_record(
+    *,
+    tab_id: str,
+    leader_id: str,
+    settings,
+) -> GraphNodeRecord:
+    role_name = resolve_leader_role_name(settings=settings)
+    return GraphNodeRecord(
+        id=leader_id,
+        config=NodeConfig(
+            node_type=NodeType.AGENT,
+            role_name=role_name,
+            tab_id=tab_id,
+            name=LEADER_NODE_NAME,
+            tools=build_tools_for_role(role_name, settings=settings),
+        ),
+        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,
+    record: GraphNodeRecord,
+    settings,
+) -> bool:
+    role_name = resolve_leader_role_name(settings=settings)
+    tools = build_tools_for_role(role_name, settings=settings)
+    changed = False
+    if record.config.node_type != NodeType.AGENT:
+        record.config.node_type = NodeType.AGENT
+        changed = True
+    if record.config.tab_id != tab_id:
+        record.config.tab_id = tab_id
+        changed = True
+    if record.config.role_name != role_name:
+        record.config.role_name = role_name
+        changed = True
+    if record.config.name != LEADER_NODE_NAME:
+        record.config.name = LEADER_NODE_NAME
+        changed = True
+    if record.config.tools != tools:
+        record.config.tools = tools
+        changed = True
+    return changed
+
+
+def _start_persisted_agent(
+    *,
+    record: GraphNodeRecord,
+) -> tuple[GraphNodeRecord | None, str | None]:
+    from flowent.agent import Agent
+
+    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
+
+
+def ensure_tab_leaders(*, start_nodes: bool = False) -> bool:
+    settings = settings_module.get_settings()
+    changed = False
+    should_start_nodes = start_nodes and bool(registry.get_all())
+
+    for tab in workspace_store.list_tabs():
+        tab_nodes = list_tab_nodes(tab.id)
+        leader_record: GraphNodeRecord | None = None
+
+        if tab.leader_id:
+            current_leader = workspace_store.get_node_record(tab.leader_id)
+            if (
+                current_leader is not None
+                and current_leader.config.tab_id == tab.id
+                and current_leader.state != AgentState.TERMINATED
+            ):
+                leader_record = current_leader
+            elif (
+                current_leader is not None
+                and current_leader.config.tab_id == tab.id
+                and current_leader.state == AgentState.TERMINATED
+            ):
+                workspace_store.delete_node_record(current_leader.id)
+                changed = True
+
+        if leader_record is None:
+            conductor_candidates = sorted(
+                (
+                    node
+                    for node in tab_nodes
+                    if node.state != AgentState.TERMINATED
+                    and node.config.role_name == CONDUCTOR_ROLE_NAME
+                ),
+                key=lambda node: (node.created_at, node.id),
+            )
+            if conductor_candidates:
+                leader_record = conductor_candidates[0]
+            else:
+                leader_record = _build_leader_record(
+                    tab_id=tab.id,
+                    leader_id=str(uuid.uuid4()),
+                    settings=settings,
+                )
+                workspace_store.upsert_node_record(leader_record)
+                changed = True
+
+        if tab.leader_id != leader_record.id:
+            tab.leader_id = leader_record.id
+            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
+
+        if should_start_nodes and registry.get(leader_record.id) is None:
+            _start_persisted_agent(record=leader_record)
+
+    return changed
+
+
+def sync_assistant_role(*, reason: str) -> None:
+    assistant = registry.get_assistant()
+    if assistant is None:
+        return
+    settings = settings_module.get_settings()
+    assistant.config.role_name = settings.assistant.role_name
+    assistant.config.tools = build_assistant_tools(settings=settings)
+    assistant.config.write_dirs = list(settings.assistant.write_dirs)
+    assistant.config.allow_network = settings.assistant.allow_network
+    assistant._sync_system_prompt_entry()
+    assistant.set_state(
+        assistant.state,
+        reason,
+        force_emit=True,
+    )
+
+
+def sync_tab_leaders(*, reason: str) -> None:
+    ensure_tab_leaders()
+    settings = settings_module.get_settings()
+    for tab in workspace_store.list_tabs():
+        if not tab.leader_id:
+            continue
+        record = workspace_store.get_node_record(tab.leader_id)
+        if record is None:
+            continue
+        if _sync_leader_record(tab_id=tab.id, record=record, settings=settings):
+            workspace_store.upsert_node_record(record)
+        live_node = registry.get(record.id)
+        if live_node is None:
+            continue
+        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._sync_system_prompt_entry()
+        live_node.set_state(
+            live_node.state,
+            reason,
+            force_emit=True,
+        )
+
+
+def _emit_tab_updated(*, tab_id: str, agent_id: str) -> None:
+    tab = workspace_store.get_tab(tab_id)
+    if tab is None:
+        return
+    event_bus.emit(
+        Event(
+            type=EventType.TAB_UPDATED,
+            agent_id=agent_id,
+            data=serialize_tab_summary(tab),
+        )
+    )
+
+
+def _start_tab_runtime(tab_id: str) -> None:
+    tab = workspace_store.get_tab(tab_id)
+    if tab is None:
+        return
+    ordered_records = sorted(
+        list_tab_nodes(tab_id),
+        key=lambda record: (
+            record.id != tab.leader_id,
+            record.created_at,
+            record.id,
+        ),
+    )
+    for record in ordered_records:
+        if registry.get(record.id) is not None:
+            continue
+        _start_persisted_agent(record=record)
+
+
+def create_tab(
+    *,
+    title: str,
+    allow_network: bool = False,
+    write_dirs: list[str] | None = None,
+) -> Tab:
+    settings = settings_module.get_settings()
+    leader_id = str(uuid.uuid4())
+    tab = Tab(
+        id=str(uuid.uuid4()),
+        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,
+    )
+    workspace_store.upsert_node_record(leader_record)
+    if registry.get_all():
+        _start_tab_runtime(tab.id)
+    event_bus.emit(
+        Event(
+            type=EventType.TAB_CREATED,
+            agent_id="assistant",
+            data=serialize_tab_summary(tab),
+        )
+    )
+    return tab
+
+
+def duplicate_tab(
+    *,
+    tab_id: str,
+) -> tuple[Tab | None, str | None]:
+    source_tab = workspace_store.get_tab(tab_id)
+    if source_tab is None:
+        return None, f"Tab '{tab_id}' not found"
+
+    _sync_tab_permissions_from_legacy_leader(source_tab)
+    duplicated_definition = WorkflowDefinition.from_mapping(
+        source_tab.definition.serialize()
+    )
+    id_map: dict[str, str] = {}
+    duplicated_nodes: list[WorkflowNodeDefinition] = []
+
+    for node in duplicated_definition.nodes:
+        new_node_id = str(uuid.uuid4())
+        id_map[node.id] = new_node_id
+        duplicated_node = build_workflow_node_definition(
+            node_id=new_node_id,
+            node_kind=node.type,
+            config=node.config,
+        )
+        duplicated_nodes.append(duplicated_node)
+
+    duplicated_edges = [
+        GraphEdge(
+            id=str(uuid.uuid4()),
+            from_node_id=id_map.get(edge.from_node_id, edge.from_node_id),
+            from_port_key=edge.from_port_key,
+            to_node_id=id_map.get(edge.to_node_id, edge.to_node_id),
+            to_port_key=edge.to_port_key,
+            kind=edge.kind,
+        )
+        for edge in duplicated_definition.edges
+    ]
+    duplicated_view_positions = {
+        id_map.get(node_id, node_id): position
+        for node_id, position in duplicated_definition.view.positions.items()
+        if id_map.get(node_id, node_id) in id_map.values()
+    }
+
+    settings = settings_module.get_settings()
+    new_tab = 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,
+            edges=duplicated_edges,
+            view=duplicated_definition.view.__class__(
+                positions=duplicated_view_positions
+            ),
+        ),
+    )
+    assert new_tab.leader_id is not None
+    workspace_store.upsert_tab(new_tab)
+    workspace_store.upsert_node_record(
+        _build_leader_record(
+            tab_id=new_tab.id,
+            leader_id=new_tab.leader_id,
+            settings=settings,
+        )
+    )
+
+    for node in source_tab.definition.nodes:
+        if node.type != WorkflowNodeKind.AGENT:
+            continue
+        duplicated_node_id = id_map.get(node.id)
+        if duplicated_node_id is None:
+            continue
+        config, error = build_node_config(
+            role_name=str(node.config.get("role_name", "")),
+            tab_id=new_tab.id,
+            name=str(node.config["name"])
+            if isinstance(node.config.get("name"), str)
+            else None,
+        )
+        if error is not None or config is None:
+            return None, error or "Failed to duplicate workflow"
+        workspace_store.upsert_node_record(
+            GraphNodeRecord(
+                id=duplicated_node_id,
+                config=config,
+                state=AgentState.INITIALIZING,
+                position=duplicated_view_positions.get(duplicated_node_id),
+            )
+        )
+
+    if registry.get_all():
+        _start_tab_runtime(new_tab.id)
+    event_bus.emit(
+        Event(
+            type=EventType.TAB_CREATED,
+            agent_id="assistant",
+            data=serialize_tab_summary(new_tab),
+        )
+    )
+    return new_tab, None
+
+
+def _is_path_within_boundary(path: str, boundary_dirs: list[str]) -> bool:
+    resolved_path = resolve_path(path)
+    return any(
+        resolved_path.is_relative_to(resolve_path(boundary_dir))
+        for boundary_dir in 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(
+    *,
+    tab_id: str,
+    allow_network: bool | None = None,
+    write_dirs: list[str] | None = None,
+    caller_allow_network: bool,
+    caller_write_dirs: list[str],
+    actor_id: str,
+) -> 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"
+    _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:
+        return None, f"Tab '{tab_id}' does not have a bound Leader"
+
+    leader_record = workspace_store.get_node_record(leader_id)
+    if leader_record is None:
+        return None, f"Leader '{leader_id}' not found"
+
+    if allow_network is not None and allow_network and not caller_allow_network:
+        return (
+            None,
+            "allow_network boundary exceeded: caller disallows network access",
+        )
+    if write_dirs is not None:
+        invalid_write_dirs = sorted(
+            path
+            for path in write_dirs
+            if not _is_path_within_boundary(path, caller_write_dirs)
+        )
+        if invalid_write_dirs:
+            return (
+                None,
+                "write_dirs boundary exceeded: " + ", ".join(invalid_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 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.set_state(
+                live_node.state,
+                "tab_permissions_updated",
+                force_emit=True,
+            )
+
+    updated_tab = workspace_store.get_tab(tab_id)
+    if updated_tab is not None:
+        event_bus.emit(
+            Event(
+                type=EventType.TAB_UPDATED,
+                agent_id=actor_id,
+                data=serialize_tab_summary(updated_tab),
+            )
+        )
+
+    return (
+        {
+            "tab_id": tab_id,
+            "leader_id": leader_id,
+            "allow_network": next_allow_network,
+            "write_dirs": list(next_write_dirs),
+            "updated_node_ids": changed_node_ids,
+        },
+        None,
+    )
+
+
+def delete_tab(
+    *,
+    tab_id: str,
+    timeout: float = SYSTEM_NODE_TIMEOUT,
+) -> 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"
+    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]
+
+    removed_node_ids = list(
+        dict.fromkeys(
+            [
+                *(node.id for node in stored_nodes),
+                *(node.uuid for node in live_nodes),
+                *(node.id for node in tab.definition.nodes),
+            ]
+        )
+    )
+    removed_edge_ids = [edge.id for edge in tab.definition.edges]
+
+    for node in live_nodes:
+        node.request_termination("tab_deleted")
+
+    lingering_node_ids: list[str] = []
+    for node in live_nodes:
+        if not node.wait_for_termination(timeout=timeout):
+            lingering_node_ids.append(node.uuid)
+
+    if lingering_node_ids:
+        return (
+            None,
+            "Failed to delete workflow because some nodes did not terminate: "
+            + ", ".join(node_id[:8] for node_id in lingering_node_ids),
+        )
+
+    workspace_store.delete_tab(tab_id)
+    payload = {
+        **tab.serialize(),
+        "removed_node_ids": removed_node_ids,
+        "removed_edge_ids": removed_edge_ids,
+    }
+    event_bus.emit(
+        Event(
+            type=EventType.TAB_DELETED,
+            agent_id="assistant",
+            data=payload,
+        )
+    )
+    return payload, None
+
+
+def build_node_config(
+    *,
+    role_name: str,
+    tab_id: str,
+    name: str | None = None,
+    tools: list[str] | None = None,
+) -> tuple[NodeConfig | None, str | None]:
+    settings = settings_module.get_settings()
+    role = find_role(settings, role_name.strip())
+    if role is None:
+        return None, f"Role '{role_name.strip()}' not found"
+
+    requested_tools = tools or []
+    if not all(isinstance(item, str) for item in requested_tools):
+        return None, "tools must be an array of strings"
+
+    return (
+        NodeConfig(
+            node_type=NodeType.AGENT,
+            role_name=role.name,
+            tab_id=tab_id,
+            name=name.strip() if isinstance(name, str) and name.strip() else None,
+            tools=build_tools_for_role(
+                role.name,
+                requested_tools=requested_tools,
+                settings=settings,
+            ),
+        ),
+        None,
+    )
+
+
+def _persist_tab(tab: Tab, *, actor_id: str) -> Tab:
+    workspace_store.upsert_tab(tab)
+    _emit_tab_updated(tab_id=tab.id, agent_id=actor_id)
+    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,
+    node_type: WorkflowNodeKind,
+    config: dict[str, object] | None = None,
+    actor_id: str,
+) -> tuple[WorkflowNodeDefinition | None, str | None]:
+    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,
+        node_kind=node_type,
+        config=config,
+    )
+    tab.definition.nodes.append(node)
+    _persist_tab(tab, actor_id=actor_id)
+    return node, None
+
+
+def create_agent_node(
+    *,
+    role_name: str,
+    tab_id: str,
+    name: str | None = None,
+    tools: list[str] | None = None,
+    creator_node_id: str | None = None,
+    connect_to_creator: bool | None = None,
+) -> tuple[GraphNodeRecord | None, str | None]:
+    del creator_node_id, connect_to_creator
+    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,
+    )
+    if error is not None or config is None:
+        return None, error
+    if config.role_name == CONDUCTOR_ROLE_NAME:
+        return None, f"Role '{CONDUCTOR_ROLE_NAME}' is reserved for a workflow Leader"
+
+    node_id = str(uuid.uuid4())
+    record = GraphNodeRecord(
+        id=node_id,
+        config=config,
+        state=AgentState.INITIALIZING,
+    )
+    workspace_store.upsert_node_record(record)
+    tab.definition.nodes.append(
+        build_workflow_node_definition(
+            node_id=node_id,
+            node_kind=WorkflowNodeKind.AGENT,
+            config={
+                "role_name": config.role_name or "",
+                **({"name": config.name} if config.name else {}),
+            },
+        )
+    )
+    workspace_store.upsert_tab(tab)
+    started_record, start_error = _start_persisted_agent(record=record)
+    if start_error is not None or started_record is None:
+        return None, start_error or "Failed to create agent"
+    _emit_tab_updated(tab_id=tab_id, agent_id=node_id)
+    return started_record, None
+
+
+def update_tab_definition(
+    *,
+    tab_id: str,
+    definition_payload: dict[str, object],
+    actor_id: str,
+) -> tuple[Tab | None, str | None]:
+    tab = workspace_store.get_tab(tab_id)
+    if tab is None:
+        return None, f"Tab '{tab_id}' not found"
+    next_definition = WorkflowDefinition.from_mapping(definition_payload)
+    node_ids = [node.id for node in next_definition.nodes]
+    if len(node_ids) != len(set(node_ids)):
+        return None, "Workflow definition contains duplicate node ids"
+    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
+    }
+    next_agent_ids = {
+        node.id for node in next_definition.nodes if node.type == WorkflowNodeKind.AGENT
+    }
+    if current_agent_ids != next_agent_ids:
+        return None, "Agent nodes must be created or deleted through workflow node APIs"
+
+    current_records = {
+        record.id: record
+        for record in list_tab_nodes(tab_id)
+        if not is_tab_leader(node_id=record.id, tab_id=tab_id)
+    }
+    for node in next_definition.nodes:
+        if node.type != WorkflowNodeKind.AGENT:
+            continue
+        role_name = node.config.get("role_name")
+        if not isinstance(role_name, str) or not role_name.strip():
+            return None, f"Agent node '{node.id}' requires role_name"
+        record = current_records.get(node.id)
+        if record is None:
+            return None, f"Runtime agent '{node.id}' was not found"
+        config, error = build_node_config(
+            role_name=role_name,
+            tab_id=tab_id,
+            name=str(node.config["name"])
+            if isinstance(node.config.get("name"), str)
+            else None,
+        )
+        if error is not None or config is None:
+            return None, error or f"Failed to validate agent node '{node.id}'"
+        record.config.role_name = config.role_name
+        record.config.name = config.name
+        record.config.tools = config.tools
+        workspace_store.upsert_node_record(record)
+        live_node = registry.get(node.id)
+        if live_node is not 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._sync_system_prompt_entry()
+            live_node.set_state(
+                live_node.state,
+                "workflow_definition_updated",
+                force_emit=True,
+            )
+
+    seen_target_ports: set[tuple[str, str]] = set()
+    for edge in next_definition.edges:
+        source_node = next_definition.get_node(edge.from_node_id)
+        target_node = next_definition.get_node(edge.to_node_id)
+        if source_node is None:
+            return None, f"Edge source node '{edge.from_node_id}' does not exist"
+        if target_node is None:
+            return None, f"Edge target node '{edge.to_node_id}' does not exist"
+        source_port = _port_matches(
+            source_node.outputs,
+            port_key=edge.from_port_key,
+            direction=PortDirection.OUTPUT,
+        )
+        if source_port is None:
+            return None, f"Output port '{edge.from_port_key}' is invalid"
+        target_port = _port_matches(
+            target_node.inputs,
+            port_key=edge.to_port_key,
+            direction=PortDirection.INPUT,
+        )
+        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"
+        seen_target_ports.add(target_key)
+
+    tab.definition = next_definition
+    _persist_tab(tab, actor_id=actor_id)
+    return tab, None
+
+
+def _port_matches(
+    ports: list[WorkflowPort],
+    *,
+    port_key: str,
+    direction: PortDirection,
+) -> WorkflowPort | None:
+    return next(
+        (
+            port
+            for port in ports
+            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,
+    from_node_id: str,
+    to_node_id: str,
+    from_port_key: str = "out",
+    to_port_key: str = "in",
+    kind: EdgeKind | str = EdgeKind.CONTROL,
+) -> tuple[GraphEdge | None, str | None]:
+    del kind
+    resolved_tab_id = tab_id
+    if resolved_tab_id is None:
+        source_record = workspace_store.get_node_record(from_node_id)
+        target_record = workspace_store.get_node_record(to_node_id)
+        if source_record is not None and source_record.config.tab_id:
+            resolved_tab_id = source_record.config.tab_id
+        elif target_record is not None and target_record.config.tab_id:
+            resolved_tab_id = target_record.config.tab_id
+    if resolved_tab_id is None:
+        return None, "tab_id is required"
+    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,
+    ):
+        return None, "Workflow Leader does not participate in Workflow Graph edges"
+    if from_node_id == to_node_id:
+        return None, "Self-loop edges are not allowed"
+    source_node = tab.definition.get_node(from_node_id)
+    target_node = tab.definition.get_node(to_node_id)
+    if source_node is None:
+        return None, f"Node '{from_node_id}' not found"
+    if target_node is None:
+        return None, f"Node '{to_node_id}' not found"
+    source_port = _port_matches(
+        source_node.outputs,
+        port_key=from_port_key,
+        direction=PortDirection.OUTPUT,
+    )
+    if source_port is None:
+        return None, f"Output port '{from_port_key}' is invalid"
+    target_port = _port_matches(
+        target_node.inputs,
+        port_key=to_port_key,
+        direction=PortDirection.INPUT,
+    )
+    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
+        for edge in tab.definition.edges
+    ):
+        return None, "Duplicate edges are not allowed"
+    if not target_port.multiple and any(
+        edge.to_node_id == to_node_id and edge.to_port_key == to_port_key
+        for edge in tab.definition.edges
+    ):
+        return None, f"Input port '{to_port_key}' already has an incoming edge"
+
+    edge = GraphEdge(
+        id=str(uuid.uuid4()),
+        tab_id=resolved_tab_id,
+        from_node_id=from_node_id,
+        from_port_key=from_port_key,
+        to_node_id=to_node_id,
+        to_port_key=to_port_key,
+    )
+    tab.definition.edges.append(edge)
+    _persist_tab(tab, actor_id=from_node_id)
+    return edge, None
+
+
+def delete_edge(
+    *,
+    tab_id: str,
+    edge_id: str | None = None,
+    from_node_id: str | None = None,
+    to_node_id: str | None = None,
+    from_port_key: str | None = None,
+    to_port_key: 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"
+    if _is_active(tab):
+        return None, _active_edit_error("edges")
+
+    matched_edge: GraphEdge | None = None
+    for edge in tab.definition.edges:
+        if edge_id is not None and edge.id == edge_id:
+            matched_edge = edge
+            break
+        if (
+            from_node_id is not None
+            and to_node_id is not None
+            and edge.from_node_id == from_node_id
+            and edge.to_node_id == to_node_id
+            and (from_port_key is None or edge.from_port_key == from_port_key)
+            and (to_port_key is None or edge.to_port_key == to_port_key)
+        ):
+            matched_edge = edge
+            break
+    if matched_edge is None:
+        return None, "Edge not found"
+
+    tab.definition.edges = [
+        edge for edge in tab.definition.edges if edge.id != matched_edge.id
+    ]
+    _persist_tab(tab, actor_id=matched_edge.from_node_id)
+    return matched_edge.serialize(), None
+
+
+def delete_agent_node(
+    *,
+    tab_id: str,
+    node_id: str,
+    timeout: float = SYSTEM_NODE_TIMEOUT,
+) -> 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"
+    if _is_active(tab):
+        return None, _active_edit_error("nodes")
+
+    node_definition = tab.definition.get_node(node_id)
+    if node_definition is None:
+        return None, f"Node '{node_id}' not found"
+    if is_tab_leader(node_id=node_id, tab_id=tab_id):
+        return None, "Workflow Leader cannot be deleted from the graph"
+
+    related_edges = [
+        edge
+        for edge in tab.definition.edges
+        if edge.from_node_id == node_id or edge.to_node_id == node_id
+    ]
+    live_node = registry.get(node_id)
+    record = workspace_store.get_node_record(node_id)
+
+    if live_node is not None:
+        live_node.request_termination("graph_deleted")
+        if not live_node.wait_for_termination(timeout=timeout):
+            return (
+                None,
+                f"Failed to delete node '{node_id}' because it did not terminate",
+            )
+
+    if record is not None:
+        workspace_store.delete_node_record(node_id)
+
+    tab.definition.nodes = [node for node in tab.definition.nodes if node.id != node_id]
+    tab.definition.edges = [
+        edge
+        for edge in tab.definition.edges
+        if edge.id not in {item.id for item in related_edges}
+    ]
+    tab.definition.view.positions.pop(node_id, None)
+    workspace_store.upsert_tab(tab)
+    payload: dict[str, object] = {
+        "id": node_id,
+        "tab_id": tab_id,
+        "removed_edge_ids": [edge.id for edge in related_edges],
+    }
+    event_bus.emit(
+        Event(
+            type=EventType.NODE_DELETED,
+            agent_id=node_id,
+            data=payload,
+        )
+    )
+    _emit_tab_updated(
+        tab_id=tab_id,
+        agent_id=node_id,
+    )
+    return payload, None
+
+
+def dispatch_node_message(
+    *,
+    node_id: str,
+    content: str,
+    parts: list | None = None,
+    from_id: str = "human",
+) -> tuple[str | None, str | None]:
+    target = registry.get(node_id)
+    if target is None:
+        return f"Node '{node_id}' is not active", None
+    message_id = str(uuid.uuid4())
+    normalized_parts = list(parts or [])
+    target._append_history(
+        ReceivedMessage(
+            from_id=from_id,
+            parts=normalized_parts,
+            content=content,
+            message_id=message_id,
+        )
+    )
+    target.enqueue_message(
+        Message(
+            from_id=from_id,
+            to_id=node_id,
+            parts=normalized_parts,
+            content=content,
+            message_id=message_id,
+            history_recorded=True,
+        )
+    )
+    return None, message_id
+
+
+def list_tab_nodes(tab_id: str) -> list[GraphNodeRecord]:
+    return sorted(
+        workspace_store.list_node_records(tab_id),
+        key=lambda record: (record.created_at, record.id),
+    )
+
+
+def list_tab_edges(tab_id: str) -> list[GraphEdge]:
+    tab = workspace_store.get_tab(tab_id)
+    if tab is None:
+        return []
+    return sorted(
+        [
+            GraphEdge(
+                id=edge.id,
+                tab_id=tab_id,
+                from_node_id=edge.from_node_id,
+                from_port_key=edge.from_port_key,
+                to_node_id=edge.to_node_id,
+                to_port_key=edge.to_port_key,
+                kind=edge.kind,
+                created_at=edge.created_at,
+            )
+            for edge in tab.definition.edges
+        ],
+        key=lambda edge: (edge.created_at, edge.id),
+    )
+
+
+def list_node_connection_ids(*, tab_id: str, node_id: str) -> list[str]:
+    if is_tab_leader(node_id=node_id, tab_id=tab_id):
+        return []
+
+    connection_ids: list[str] = []
+    seen_node_ids: set[str] = set()
+    for edge in list_tab_edges(tab_id):
+        other_node_id: str | None = None
+        if edge.from_node_id == node_id:
+            other_node_id = edge.to_node_id
+        elif edge.to_node_id == node_id:
+            other_node_id = edge.from_node_id
+        if other_node_id is None or other_node_id in seen_node_ids:
+            continue
+        seen_node_ids.add(other_node_id)
+        connection_ids.append(other_node_id)
+    return connection_ids