autobyteus 1.1.3__py3-none-any.whl → 1.1.4__py3-none-any.whl

autobyteus/workflow/bootstrap_steps/workflow_bootstrapper.py

@@ -0,0 +1,50 @@
+# file: autobyteus/autobyteus/workflow/bootstrap_steps/workflow_bootstrapper.py
+import logging
+from typing import TYPE_CHECKING, List, Optional
+
+from autobyteus.workflow.bootstrap_steps.base_workflow_bootstrap_step import BaseWorkflowBootstrapStep
+from autobyteus.workflow.bootstrap_steps.workflow_runtime_queue_initialization_step import WorkflowRuntimeQueueInitializationStep
+from autobyteus.workflow.bootstrap_steps.coordinator_prompt_preparation_step import CoordinatorPromptPreparationStep
+from autobyteus.workflow.bootstrap_steps.agent_tool_injection_step import AgentToolInjectionStep
+from autobyteus.workflow.bootstrap_steps.coordinator_initialization_step import CoordinatorInitializationStep
+from autobyteus.workflow.events.workflow_events import WorkflowReadyEvent
+
+if TYPE_CHECKING:
+    from autobyteus.workflow.context.workflow_context import WorkflowContext
+    from autobyteus.workflow.phases.workflow_phase_manager import WorkflowPhaseManager
+
+logger = logging.getLogger(__name__)
+
+class WorkflowBootstrapper:
+    """Orchestrates the workflow's bootstrapping process."""
+    def __init__(self, steps: Optional[List[BaseWorkflowBootstrapStep]] = None):
+        self.bootstrap_steps = steps or [
+            WorkflowRuntimeQueueInitializationStep(),
+            CoordinatorPromptPreparationStep(),
+            AgentToolInjectionStep(),
+            CoordinatorInitializationStep(),
+        ]
+
+    async def run(self, context: 'WorkflowContext', phase_manager: 'WorkflowPhaseManager') -> bool:
+        workflow_id = context.workflow_id
+        await phase_manager.notify_bootstrapping_started()
+        logger.info(f"Workflow '{workflow_id}': Bootstrapper starting.")
+
+        for step in self.bootstrap_steps:
+            step_name = step.__class__.__name__
+            logger.debug(f"Workflow '{workflow_id}': Executing bootstrap step: {step_name}")
+            if not await step.execute(context, phase_manager):
+                error_message = f"Bootstrap step {step_name} failed."
+                logger.error(f"Workflow '{workflow_id}': {error_message}")
+                await phase_manager.notify_error_occurred(error_message, f"Failed during bootstrap step '{step_name}'.")
+                return False
+        
+        logger.info(f"Workflow '{workflow_id}': All bootstrap steps completed successfully.")
+        if context.state.input_event_queues:
+            await context.state.input_event_queues.enqueue_internal_system_event(WorkflowReadyEvent())
+        else:
+            logger.critical(f"Workflow '{workflow_id}': Bootstrap succeeded but queues not available.")
+            await phase_manager.notify_error_occurred("Queues unavailable after bootstrap.", "")
+            return False
+            
+        return True

autobyteus/workflow/bootstrap_steps/workflow_runtime_queue_initialization_step.py

@@ -0,0 +1,25 @@
+# file: autobyteus/autobyteus/workflow/bootstrap_steps/workflow_runtime_queue_initialization_step.py
+import logging
+from typing import TYPE_CHECKING
+
+from autobyteus.workflow.bootstrap_steps.base_workflow_bootstrap_step import BaseWorkflowBootstrapStep
+from autobyteus.workflow.events.workflow_input_event_queue_manager import WorkflowInputEventQueueManager
+
+if TYPE_CHECKING:
+    from autobyteus.workflow.context.workflow_context import WorkflowContext
+    from autobyteus.workflow.phases.workflow_phase_manager import WorkflowPhaseManager
+
+logger = logging.getLogger(__name__)
+
+class WorkflowRuntimeQueueInitializationStep(BaseWorkflowBootstrapStep):
+    """Bootstrap step for initializing the workflow's runtime event queues."""
+    async def execute(self, context: 'WorkflowContext', phase_manager: 'WorkflowPhaseManager') -> bool:
+        workflow_id = context.workflow_id
+        logger.info(f"Workflow '{workflow_id}': Executing WorkflowRuntimeQueueInitializationStep.")
+        try:
+            context.state.input_event_queues = WorkflowInputEventQueueManager()
+            logger.info(f"Workflow '{workflow_id}': WorkflowInputEventQueueManager initialized.")
+            return True
+        except Exception as e:
+            logger.error(f"Workflow '{workflow_id}': Critical failure during queue initialization: {e}", exc_info=True)
+            return False

autobyteus/workflow/context/__init__.py

@@ -0,0 +1,17 @@
+# file: autobyteus/autobyteus/workflow/context/__init__.py
+"""
+Components related to the workflow's runtime context, state, and configuration.
+"""
+from autobyteus.workflow.context.team_manager import TeamManager
+from autobyteus.workflow.context.workflow_config import WorkflowConfig
+from autobyteus.workflow.context.workflow_context import WorkflowContext
+from autobyteus.workflow.context.workflow_node_config import WorkflowNodeConfig
+from autobyteus.workflow.context.workflow_runtime_state import WorkflowRuntimeState
+
+__all__ = [
+    "TeamManager",
+    "WorkflowConfig",
+    "WorkflowContext",
+    "WorkflowNodeConfig",
+    "WorkflowRuntimeState",
+]

autobyteus/workflow/context/team_manager.py

@@ -0,0 +1,147 @@
+# file: autobyteus/autobyteus/workflow/context/team_manager.py
+import asyncio
+import logging
+from typing import List, Dict, Optional, TYPE_CHECKING, Union
+
+from autobyteus.agent.factory import AgentFactory
+from autobyteus.agent.utils.wait_for_idle import wait_for_agent_to_be_idle
+from autobyteus.workflow.utils.wait_for_idle import wait_for_workflow_to_be_idle
+from autobyteus.workflow.exceptions import WorkflowNodeNotFoundException
+from autobyteus.agent.message.send_message_to import SendMessageTo
+from autobyteus.tools.registry import default_tool_registry
+
+if TYPE_CHECKING:
+    from autobyteus.agent.agent import Agent
+    from autobyteus.workflow.agentic_workflow import AgenticWorkflow
+    from autobyteus.workflow.events.workflow_events import InterAgentMessageRequestEvent
+    from autobyteus.workflow.runtime.workflow_runtime import WorkflowRuntime
+    from autobyteus.workflow.streaming.agent_event_multiplexer import AgentEventMultiplexer
+    from autobyteus.agent.context.agent_config import AgentConfig
+    from autobyteus.workflow.context.workflow_config import WorkflowConfig
+
+ManagedNode = Union['Agent', 'AgenticWorkflow']
+
+logger = logging.getLogger(__name__)
+
+class TeamManager:
+    """
+    Manages all nodes (agents and sub-workflows) within a workflow. It handles
+    lazy creation, on-demand startup, and provides access to managed instances.
+    """
+    def __init__(self, workflow_id: str, runtime: 'WorkflowRuntime', multiplexer: 'AgentEventMultiplexer'):
+        self.workflow_id = workflow_id
+        self._runtime = runtime
+        self._multiplexer = multiplexer
+        self._agent_factory = AgentFactory()
+        self._nodes_cache: Dict[str, ManagedNode] = {}
+        self._coordinator_agent: Optional['Agent'] = None
+        logger.info(f"TeamManager created for workflow '{self.workflow_id}'.")
+
+    async def dispatch_inter_agent_message_request(self, event: 'InterAgentMessageRequestEvent'):
+        await self._runtime.submit_event(event)
+
+    async def ensure_node_is_ready(self, name: str) -> ManagedNode:
+        """
+        Retrieves a node (agent or sub-workflow) by its unique friendly name.
+        If the node has not been created yet, it is instantiated. If it is not
+        running, it is started and awaited until idle.
+        Returns a fully ready node instance or raises an exception.
+        """
+        node_instance = self._nodes_cache.get(name)
+        
+        was_created = False
+        if not node_instance:
+            logger.debug(f"Node '{name}' not in cache for workflow '{self.workflow_id}'. Attempting lazy creation.")
+            
+            node_config_wrapper = self._runtime.context.get_node_config_by_name(name)
+            if not node_config_wrapper:
+                raise WorkflowNodeNotFoundException(node_name=name, workflow_id=self.workflow_id)
+
+            node_definition = node_config_wrapper.node_definition
+
+            if node_config_wrapper.is_subworkflow:
+                from autobyteus.workflow.factory.workflow_factory import WorkflowFactory
+                from autobyteus.workflow.context.workflow_config import WorkflowConfig
+                
+                workflow_factory = WorkflowFactory() # Get singleton instance
+                if not isinstance(node_definition, WorkflowConfig):
+                     raise TypeError(f"Expected WorkflowConfig for node '{name}', but found {type(node_definition)}")
+                logger.info(f"Lazily creating sub-workflow node '{name}' in workflow '{self.workflow_id}'.")
+                node_instance = workflow_factory.create_workflow(config=node_definition)
+            else:
+                from autobyteus.agent.context.agent_config import AgentConfig
+                if not isinstance(node_definition, AgentConfig):
+                     raise TypeError(f"Expected AgentConfig for node '{name}', but found {type(node_definition)}")
+                
+                # --- Apply Deferred Logic from Bootstrap Step ---
+                final_config = node_definition.copy()
+
+                # 1. Inject SendMessageTo tool
+                send_message_tool = default_tool_registry.create_tool(SendMessageTo.get_name())
+                if isinstance(send_message_tool, SendMessageTo):
+                    send_message_tool.set_team_manager(self)
+                final_config.tools = [t for t in final_config.tools if not isinstance(t, SendMessageTo)]
+                final_config.tools.append(send_message_tool)
+
+                # 2. Apply coordinator prompt if this is the coordinator
+                coordinator_node_name = self._runtime.context.config.coordinator_node.name
+                if name == coordinator_node_name:
+                    coordinator_prompt = self._runtime.context.state.prepared_coordinator_prompt
+                    if coordinator_prompt:
+                        final_config.system_prompt = coordinator_prompt
+                        logger.info(f"Applied dynamic prompt to coordinator '{name}'.")
+                
+                logger.info(f"Lazily creating agent node '{name}' in workflow '{self.workflow_id}'.")
+                node_instance = self._agent_factory.create_agent(config=final_config)
+            
+            self._nodes_cache[name] = node_instance
+            was_created = True
+
+        if was_created and node_instance:
+            from autobyteus.workflow.agentic_workflow import AgenticWorkflow
+            from autobyteus.agent.agent import Agent
+            if isinstance(node_instance, AgenticWorkflow):
+                self._multiplexer.start_bridging_workflow_events(node_instance, name)
+            elif isinstance(node_instance, Agent):
+                self._multiplexer.start_bridging_agent_events(node_instance, name)
+
+        # On-Demand Startup Logic
+        if not node_instance.is_running:
+            from autobyteus.workflow.agentic_workflow import AgenticWorkflow
+            logger.info(f"Workflow '{self.workflow_id}': Node '{name}' is not running. Starting on-demand.")
+            try:
+                node_instance.start()
+                if isinstance(node_instance, AgenticWorkflow):
+                    await wait_for_workflow_to_be_idle(node_instance, timeout=120.0)
+                else:
+                    await wait_for_agent_to_be_idle(node_instance, timeout=60.0)
+            except Exception as e:
+                logger.error(f"Workflow '{self.workflow_id}': Failed to start node '{name}' on-demand: {e}", exc_info=True)
+                raise RuntimeError(f"Failed to start node '{name}' on-demand.") from e
+        
+        return node_instance
+
+    def get_all_agents(self) -> List['Agent']:
+        from autobyteus.agent.agent import Agent
+        return [node for node in self._nodes_cache.values() if isinstance(node, Agent)]
+
+    def get_all_sub_workflows(self) -> List['AgenticWorkflow']:
+        from autobyteus.workflow.agentic_workflow import AgenticWorkflow
+        return [node for node in self._nodes_cache.values() if isinstance(node, AgenticWorkflow)]
+
+    @property
+    def coordinator_agent(self) -> Optional['Agent']:
+        return self._coordinator_agent
+
+    async def ensure_coordinator_is_ready(self, coordinator_name: str) -> 'Agent':
+        """
+        Ensures the coordinator agent is created, started, and ready, then
+        designates it as the coordinator.
+        """
+        from autobyteus.agent.agent import Agent
+        node = await self.ensure_node_is_ready(coordinator_name)
+        if not isinstance(node, Agent):
+            raise TypeError(f"Coordinator node '{coordinator_name}' resolved to a non-agent type: {type(node).__name__}")
+
+        self._coordinator_agent = node
+        return node

autobyteus/workflow/context/workflow_config.py

@@ -0,0 +1,30 @@
+# file: autobyteus/autobyteus/workflow/context/workflow_config.py
+import logging
+from dataclasses import dataclass, field
+from typing import List, Optional, Tuple
+
+from autobyteus.workflow.context.workflow_node_config import WorkflowNodeConfig
+
+logger = logging.getLogger(__name__)
+
+@dataclass(frozen=True)
+class WorkflowConfig:
+    """
+    Represents the complete, static configuration for an AgenticWorkflow instance.
+    This is the user's primary input for defining a workflow.
+    """
+    name: str
+    description: str
+    nodes: Tuple[WorkflowNodeConfig, ...]
+    coordinator_node: WorkflowNodeConfig
+    role: Optional[str] = None
+
+    def __post_init__(self):
+        if not self.name or not isinstance(self.name, str):
+            raise ValueError("The 'name' in WorkflowConfig must be a non-empty string.")
+        if not self.nodes:
+            raise ValueError("The 'nodes' collection in WorkflowConfig cannot be empty.")
+        if self.coordinator_node not in self.nodes:
+            raise ValueError("The 'coordinator_node' must be one of the nodes in the 'nodes' collection.")
+        logger.debug(f"WorkflowConfig validated for workflow: '{self.name}'.")
+

autobyteus/workflow/context/workflow_context.py

@@ -0,0 +1,61 @@
+# file: autobyteus/autobyteus/workflow/context/workflow_context.py
+import logging
+from typing import TYPE_CHECKING, List, Optional, Dict
+
+if TYPE_CHECKING:
+    from autobyteus.workflow.context.workflow_config import WorkflowConfig
+    from autobyteus.workflow.context.workflow_runtime_state import WorkflowRuntimeState
+    from autobyteus.agent.agent import Agent
+    from autobyteus.workflow.phases.workflow_phase_manager import WorkflowPhaseManager
+    from autobyteus.workflow.context.team_manager import TeamManager
+    from autobyteus.workflow.streaming.agent_event_multiplexer import AgentEventMultiplexer
+    from autobyteus.agent.context import AgentConfig
+    from autobyteus.workflow.context.workflow_node_config import WorkflowNodeConfig
+
+logger = logging.getLogger(__name__)
+
+class WorkflowContext:
+    """Represents the complete operational context for a single workflow instance."""
+    def __init__(self, workflow_id: str, config: 'WorkflowConfig', state: 'WorkflowRuntimeState'):
+        if not workflow_id or not isinstance(workflow_id, str):
+            raise ValueError("WorkflowContext requires a non-empty string 'workflow_id'.")
+        
+        self.workflow_id: str = workflow_id
+        self.config: 'WorkflowConfig' = config
+        self.state: 'WorkflowRuntimeState' = state
+        self._node_config_map: Optional[Dict[str, 'WorkflowNodeConfig']] = None
+        
+        logger.info(f"WorkflowContext composed for workflow_id '{self.workflow_id}'.")
+
+    def get_node_config_by_name(self, name: str) -> Optional['WorkflowNodeConfig']:
+        """Efficiently retrieves a node's config by its friendly name."""
+        if self._node_config_map is None:
+            # Build cache on first access
+            self._node_config_map = {node.name: node for node in self.config.nodes}
+        return self._node_config_map.get(name)
+
+    @property
+    def agents(self) -> List['Agent']:
+        """Returns all agents managed by the TeamManager."""
+        if self.state.team_manager:
+            return self.state.team_manager.get_all_agents()
+        return []
+
+    @property
+    def coordinator_agent(self) -> Optional['Agent']:
+        """Returns the coordinator agent from the TeamManager."""
+        if self.state.team_manager:
+            return self.state.team_manager.coordinator_agent
+        return None
+
+    @property
+    def phase_manager(self) -> Optional['WorkflowPhaseManager']:
+        return self.state.phase_manager_ref
+
+    @property
+    def team_manager(self) -> Optional['TeamManager']:
+        return self.state.team_manager
+        
+    @property
+    def multiplexer(self) -> Optional['AgentEventMultiplexer']:
+        return self.state.multiplexer_ref

autobyteus/workflow/context/workflow_node_config.py

@@ -0,0 +1,76 @@
+# file: autobyteus/autobyteus/workflow/context/workflow_node_config.py
+from __future__ import annotations
+import logging
+import uuid
+from dataclasses import dataclass, field
+from typing import List, TYPE_CHECKING, Union, Tuple
+
+# The import is moved into the TYPE_CHECKING block to break the circular dependency at module load time.
+if TYPE_CHECKING:
+    from autobyteus.agent.context import AgentConfig
+    from autobyteus.workflow.context.workflow_config import WorkflowConfig
+
+logger = logging.getLogger(__name__)
+
+@dataclass
+class WorkflowNodeConfig:
+    """
+    Represents a node in an agentic workflow graph.
+
+    This is the core building block for defining workflows. A node can be either
+    a single agent (defined by an AgentConfig) or an entire sub-workflow
+    (defined by a WorkflowConfig).
+
+    Attributes:
+        node_definition: The configuration for the agent or sub-workflow at this node.
+        dependencies: A tuple of other WorkflowNodeConfig objects that must be
+                      successfully executed before this node can be executed.
+        node_id: A unique identifier for this node instance.
+    """
+    node_definition: Union["AgentConfig", "WorkflowConfig"]
+    dependencies: Tuple[WorkflowNodeConfig, ...] = field(default_factory=tuple)
+    node_id: str = field(default_factory=lambda: f"node_{uuid.uuid4().hex}", init=False, repr=False)
+
+    def __post_init__(self):
+        """Validates the node configuration."""
+        from autobyteus.agent.context import AgentConfig
+        from autobyteus.workflow.context.workflow_config import WorkflowConfig
+        
+        if not isinstance(self.node_definition, (AgentConfig, WorkflowConfig)):
+            raise TypeError("The 'node_definition' attribute must be an instance of AgentConfig or WorkflowConfig.")
+        
+        if not all(isinstance(dep, WorkflowNodeConfig) for dep in self.dependencies):
+            raise TypeError("All items in 'dependencies' must be instances of WorkflowNodeConfig.")
+
+        logger.debug(f"WorkflowNodeConfig created for: '{self.name}' (NodeID: {self.node_id}). Dependencies: {[dep.name for dep in self.dependencies]}")
+
+    @property
+    def name(self) -> str:
+        """A convenience property to get the node's name from its definition."""
+        return self.node_definition.name
+
+    @property
+    def effective_config(self) -> Union["AgentConfig", "WorkflowConfig"]:
+        """Returns the underlying AgentConfig or WorkflowConfig."""
+        return self.node_definition
+
+    @property
+    def is_subworkflow(self) -> bool:
+        """Returns True if this node represents a sub-workflow."""
+        from autobyteus.workflow.context.workflow_config import WorkflowConfig
+        return isinstance(self.node_definition, WorkflowConfig)
+    
+    def __hash__(self):
+        """
+        Makes the node hashable based on its unique node_id, allowing it to be
+        used in sets and as dictionary keys.
+        """
+        return hash(self.node_id)
+    
+    def __eq__(self, other):
+        """
+        Compares two nodes based on their unique node_id.
+        """
+        if isinstance(other, WorkflowNodeConfig):
+            return self.node_id == other.node_id
+        return False

autobyteus/workflow/context/workflow_runtime_state.py

@@ -0,0 +1,53 @@
+# file: autobyteus/autobyteus/workflow/context/workflow_runtime_state.py
+import logging
+from typing import List, Optional, TYPE_CHECKING, Dict
+
+from autobyteus.workflow.phases.workflow_operational_phase import WorkflowOperationalPhase
+from autobyteus.agent.context import AgentConfig
+
+if TYPE_CHECKING:
+    from autobyteus.agent.agent import Agent
+    from autobyteus.workflow.events.workflow_input_event_queue_manager import WorkflowInputEventQueueManager
+    from autobyteus.workflow.phases.workflow_phase_manager import WorkflowPhaseManager
+    from autobyteus.workflow.context.workflow_node_config import WorkflowNodeConfig
+    from autobyteus.workflow.context.team_manager import TeamManager
+    from autobyteus.workflow.streaming.agent_event_multiplexer import AgentEventMultiplexer
+
+logger = logging.getLogger(__name__)
+
+class WorkflowRuntimeState:
+    """Encapsulates the dynamic, stateful data of a running workflow instance."""
+    def __init__(self, workflow_id: str):
+        if not workflow_id or not isinstance(workflow_id, str):
+            raise ValueError("WorkflowRuntimeState requires a non-empty string 'workflow_id'.")
+
+        self.workflow_id: str = workflow_id
+        self.current_phase: WorkflowOperationalPhase = WorkflowOperationalPhase.UNINITIALIZED
+        
+        # State populated by bootstrap steps
+        self.prepared_coordinator_prompt: Optional[str] = None
+        # This is now deprecated in favor of just-in-time resolution by TeamManager
+        # self.resolved_agent_configs: Optional[Dict[str, 'AgentConfig']] = None
+
+        # Core services
+        self.team_manager: Optional['TeamManager'] = None
+
+        # Runtime components and references
+        self.input_event_queues: Optional['WorkflowInputEventQueueManager'] = None
+        self.phase_manager_ref: Optional['WorkflowPhaseManager'] = None
+        self.multiplexer_ref: Optional['AgentEventMultiplexer'] = None
+
+        logger.info(f"WorkflowRuntimeState initialized for workflow_id '{self.workflow_id}'.")
+
+    @property
+    def resolved_agent_configs(self) -> Optional[Dict[str, 'AgentConfig']]:
+        """This property is now DEPRECATED as configs are resolved just-in-time."""
+        logger.warning("'resolved_agent_configs' is deprecated. Node configs are resolved by TeamManager as needed.")
+        return None
+
+    def __repr__(self) -> str:
+        agents_count = len(self.team_manager.get_all_agents()) if self.team_manager else 0
+        coordinator_set = self.team_manager.coordinator_agent is not None if self.team_manager else False
+        return (f"<WorkflowRuntimeState id='{self.workflow_id}', phase='{self.current_phase.value}', "
+                f"agents_count={agents_count}, coordinator_set={coordinator_set}, "
+                f"team_manager_set={self.team_manager is not None}>")

autobyteus/workflow/events/__init__.py

@@ -0,0 +1,29 @@
+# file: autobyteus/autobyteus/workflow/events/__init__.py
+"""
+This package contains event definitions and dispatchers for the workflow runtime.
+"""
+from autobyteus.workflow.events.workflow_events import (
+    BaseWorkflowEvent,
+    LifecycleWorkflowEvent,
+    OperationalWorkflowEvent,
+    WorkflowReadyEvent,
+    WorkflowErrorEvent,
+    ProcessUserMessageEvent,
+    InterAgentMessageRequestEvent,
+    ToolApprovalWorkflowEvent,
+)
+from autobyteus.workflow.events.workflow_event_dispatcher import WorkflowEventDispatcher
+from autobyteus.workflow.events.workflow_input_event_queue_manager import WorkflowInputEventQueueManager
+
+__all__ = [
+    "BaseWorkflowEvent",
+    "LifecycleWorkflowEvent",
+    "OperationalWorkflowEvent",
+    "WorkflowReadyEvent",
+    "WorkflowErrorEvent",
+    "ProcessUserMessageEvent",
+    "InterAgentMessageRequestEvent",
+    "ToolApprovalWorkflowEvent",
+    "WorkflowEventDispatcher",
+    "WorkflowInputEventQueueManager",
+]

autobyteus/workflow/events/workflow_event_dispatcher.py

@@ -0,0 +1,39 @@
+# file: autobyteus/autobyteus/workflow/events/workflow_event_dispatcher.py
+import logging
+import traceback
+from typing import TYPE_CHECKING
+
+from autobyteus.workflow.events.workflow_events import BaseWorkflowEvent, WorkflowReadyEvent, ProcessUserMessageEvent
+
+if TYPE_CHECKING:
+    from autobyteus.workflow.context.workflow_context import WorkflowContext
+    from autobyteus.workflow.handlers.workflow_event_handler_registry import WorkflowEventHandlerRegistry
+    from autobyteus.workflow.phases.workflow_phase_manager import WorkflowPhaseManager
+
+logger = logging.getLogger(__name__)
+
+class WorkflowEventDispatcher:
+    """Dispatches workflow events to their appropriate handlers."""
+
+    def __init__(self,
+                 event_handler_registry: 'WorkflowEventHandlerRegistry',
+                 phase_manager: 'WorkflowPhaseManager'):
+        self.registry = event_handler_registry
+        self.phase_manager = phase_manager
+
+    async def dispatch(self, event: BaseWorkflowEvent, context: 'WorkflowContext'):
+        handler = self.registry.get_handler(type(event))
+        workflow_id = context.workflow_id
+
+        if not handler:
+            logger.warning(f"Workflow '{workflow_id}': No handler for event '{type(event).__name__}'.")
+            return
+
+        try:
+            await handler.handle(event, context)
+            if isinstance(event, WorkflowReadyEvent):
+                await self.phase_manager.notify_initialization_complete()
+        except Exception as e:
+            error_msg = f"Error handling '{type(event).__name__}' in workflow '{workflow_id}': {e}"
+            logger.error(error_msg, exc_info=True)
+            await self.phase_manager.notify_error_occurred(error_msg, traceback.format_exc())

autobyteus/workflow/events/workflow_events.py

@@ -0,0 +1,53 @@
+# file: autobyteus/autobyteus/workflow/events/workflow_events.py
+from dataclasses import dataclass
+from typing import Dict, Any, Optional
+
+from autobyteus.agent.message.agent_input_user_message import AgentInputUserMessage
+
+@dataclass
+class BaseWorkflowEvent:
+    """Base class for all workflow events."""
+
+@dataclass
+class LifecycleWorkflowEvent(BaseWorkflowEvent):
+    """Base class for events related to the workflow's lifecycle."""
+
+@dataclass
+class OperationalWorkflowEvent(BaseWorkflowEvent):
+    """Base class for events related to the workflow's operational logic."""
+
+# Specific Events
+@dataclass
+class WorkflowReadyEvent(LifecycleWorkflowEvent):
+    """Indicates the workflow has completed bootstrapping and is ready for tasks."""
+
+@dataclass
+class WorkflowErrorEvent(LifecycleWorkflowEvent):
+    """Indicates a significant error occurred within the workflow."""
+    error_message: str
+    exception_details: Optional[str] = None
+
+@dataclass
+class ProcessUserMessageEvent(OperationalWorkflowEvent):
+    """Carries a user's message to be processed by a specific agent in the workflow."""
+    user_message: AgentInputUserMessage
+    target_agent_name: str
+
+@dataclass
+class InterAgentMessageRequestEvent(OperationalWorkflowEvent):
+    """
+    An internal request within the workflow to post a message from one agent to another.
+    This triggers on-demand startup logic if needed.
+    """
+    sender_agent_id: str
+    recipient_name: str
+    content: str
+    message_type: str
+
+@dataclass
+class ToolApprovalWorkflowEvent(OperationalWorkflowEvent):
+    """Carries a user's approval/denial for a tool execution to a specific agent."""
+    agent_name: str
+    tool_invocation_id: str
+    is_approved: bool
+    reason: Optional[str] = None

autobyteus/workflow/events/workflow_input_event_queue_manager.py

@@ -0,0 +1,21 @@
+# file: autobyteus/autobyteus/workflow/events/workflow_input_event_queue_manager.py
+import asyncio
+import logging
+from typing import Any
+
+from autobyteus.workflow.events.workflow_events import ProcessUserMessageEvent
+
+logger = logging.getLogger(__name__)
+
+class WorkflowInputEventQueueManager:
+    """Manages asyncio.Queue instances for events consumed by the WorkflowWorker."""
+    def __init__(self, queue_size: int = 0):
+        self.user_message_queue: asyncio.Queue[ProcessUserMessageEvent] = asyncio.Queue(maxsize=queue_size)
+        self.internal_system_event_queue: asyncio.Queue[Any] = asyncio.Queue(maxsize=queue_size)
+        logger.info("WorkflowInputEventQueueManager initialized.")
+
+    async def enqueue_user_message(self, event: ProcessUserMessageEvent):
+        await self.user_message_queue.put(event)
+
+    async def enqueue_internal_system_event(self, event: Any):
+        await self.internal_system_event_queue.put(event)

autobyteus/workflow/exceptions.py

@@ -0,0 +1,8 @@
+# file: autobyteus/autobyteus/workflow/exceptions.py
+
+class WorkflowNodeNotFoundException(Exception):
+    """Raised when a node (agent or sub-workflow) cannot be found in the workflow."""
+    def __init__(self, node_name: str, workflow_id: str):
+        super().__init__(f"Node '{node_name}' not found in workflow '{workflow_id}'.")
+        self.node_name = node_name
+        self.workflow_id = workflow_id

autobyteus/workflow/factory/__init__.py

@@ -0,0 +1,9 @@
+# file: autobyteus/autobyteus/workflow/factory/__init__.py
+"""
+Workflow factory for creating AgenticWorkflow instances.
+"""
+from autobyteus.workflow.factory.workflow_factory import WorkflowFactory
+
+__all__ = [
+    "WorkflowFactory",
+]