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

autobyteus/workflow/factory/workflow_factory.py

@@ -0,0 +1,99 @@
+# file: autobyteus/autobyteus/workflow/factory/workflow_factory.py
+import logging
+import uuid
+from typing import Optional, Dict, List
+
+from autobyteus.utils.singleton import SingletonMeta
+from autobyteus.workflow.agentic_workflow import AgenticWorkflow
+from autobyteus.workflow.context.workflow_config import WorkflowConfig
+from autobyteus.workflow.context.workflow_context import WorkflowContext
+from autobyteus.workflow.context.workflow_runtime_state import WorkflowRuntimeState
+from autobyteus.workflow.context.team_manager import TeamManager
+from autobyteus.workflow.runtime.workflow_runtime import WorkflowRuntime
+from autobyteus.workflow.handlers.workflow_event_handler_registry import WorkflowEventHandlerRegistry
+from autobyteus.workflow.handlers.process_user_message_event_handler import ProcessUserMessageEventHandler
+from autobyteus.workflow.handlers.lifecycle_workflow_event_handler import LifecycleWorkflowEventHandler
+from autobyteus.workflow.handlers.inter_agent_message_request_event_handler import InterAgentMessageRequestEventHandler
+from autobyteus.workflow.handlers.tool_approval_workflow_event_handler import ToolApprovalWorkflowEventHandler
+from autobyteus.workflow.events.workflow_events import (
+    ProcessUserMessageEvent,
+    WorkflowReadyEvent,
+    WorkflowErrorEvent,
+    InterAgentMessageRequestEvent,
+    ToolApprovalWorkflowEvent
+)
+
+logger = logging.getLogger(__name__)
+
+class WorkflowFactory(metaclass=SingletonMeta):
+    """
+    A singleton factory for creating and managing AgenticWorkflow instances.
+    It orchestrates the assembly of all core workflow components.
+    """
+    def __init__(self):
+        self._active_workflows: Dict[str, AgenticWorkflow] = {}
+        logger.info("WorkflowFactory (Singleton) initialized.")
+
+    def _get_default_event_handler_registry(self) -> WorkflowEventHandlerRegistry:
+        """Returns a registry with default handlers for a new workflow."""
+        registry = WorkflowEventHandlerRegistry()
+        registry.register(ProcessUserMessageEvent, ProcessUserMessageEventHandler())
+        registry.register(InterAgentMessageRequestEvent, InterAgentMessageRequestEventHandler())
+        registry.register(ToolApprovalWorkflowEvent, ToolApprovalWorkflowEventHandler())
+        lifecycle_handler = LifecycleWorkflowEventHandler()
+        registry.register(WorkflowReadyEvent, lifecycle_handler)
+        registry.register(WorkflowErrorEvent, lifecycle_handler)
+        return registry
+
+    def create_workflow(self, config: WorkflowConfig) -> AgenticWorkflow:
+        """
+        Creates a new workflow based on the provided WorkflowConfig, stores it,
+        and returns its facade (AgenticWorkflow).
+        """
+        if not isinstance(config, WorkflowConfig):
+            raise TypeError(f"Expected WorkflowConfig instance, got {type(config).__name__}.")
+
+        workflow_id = f"workflow_{uuid.uuid4().hex[:8]}"
+        while workflow_id in self._active_workflows:
+            workflow_id = f"workflow_{uuid.uuid4().hex[:8]}"
+
+        # --- Component Assembly as per new architecture ---
+        state = WorkflowRuntimeState(workflow_id=workflow_id)
+        context = WorkflowContext(workflow_id=workflow_id, config=config, state=state)
+        
+        handler_registry = self._get_default_event_handler_registry()
+        runtime = WorkflowRuntime(context=context, event_handler_registry=handler_registry)
+        
+        team_manager = TeamManager(
+            workflow_id=workflow_id,
+            runtime=runtime,
+            multiplexer=runtime.multiplexer # Pass multiplexer created in runtime
+        )
+        
+        context.state.team_manager = team_manager
+        
+        workflow = AgenticWorkflow(runtime=runtime)
+        
+        self._active_workflows[workflow_id] = workflow
+        logger.info(f"Workflow '{workflow_id}' created and stored successfully.")
+        return workflow
+
+    def get_workflow(self, workflow_id: str) -> Optional[AgenticWorkflow]:
+        """Retrieves an active workflow instance by its ID."""
+        return self._active_workflows.get(workflow_id)
+
+    async def remove_workflow(self, workflow_id: str, shutdown_timeout: float = 10.0) -> bool:
+        """
+        Removes a workflow from the factory's management and gracefully stops it.
+        """
+        workflow = self._active_workflows.pop(workflow_id, None)
+        if workflow:
+            logger.info(f"Removing workflow '{workflow_id}'. Attempting graceful shutdown.")
+            await workflow.stop(timeout=shutdown_timeout)
+            return True
+        logger.warning(f"Workflow with ID '{workflow_id}' not found for removal.")
+        return False
+
+    def list_active_workflow_ids(self) -> List[str]:
+        """Returns a list of IDs of all active workflows managed by this factory."""
+        return list(self._active_workflows.keys())

autobyteus/workflow/handlers/__init__.py

@@ -0,0 +1,19 @@
+# file: autobyteus/autobyteus/workflow/handlers/__init__.py
+"""
+Event handlers for the workflow runtime.
+"""
+from autobyteus.workflow.handlers.base_workflow_event_handler import BaseWorkflowEventHandler
+from autobyteus.workflow.handlers.lifecycle_workflow_event_handler import LifecycleWorkflowEventHandler
+from autobyteus.workflow.handlers.inter_agent_message_request_event_handler import InterAgentMessageRequestEventHandler
+from autobyteus.workflow.handlers.process_user_message_event_handler import ProcessUserMessageEventHandler
+from autobyteus.workflow.handlers.tool_approval_workflow_event_handler import ToolApprovalWorkflowEventHandler
+from autobyteus.workflow.handlers.workflow_event_handler_registry import WorkflowEventHandlerRegistry
+
+__all__ = [
+    "BaseWorkflowEventHandler",
+    "LifecycleWorkflowEventHandler",
+    "InterAgentMessageRequestEventHandler",
+    "ProcessUserMessageEventHandler",
+    "ToolApprovalWorkflowEventHandler",
+    "WorkflowEventHandlerRegistry",
+]

autobyteus/workflow/handlers/base_workflow_event_handler.py

@@ -0,0 +1,16 @@
+# file: autobyteus/autobyteus/workflow/handlers/base_workflow_event_handler.py
+import logging
+from abc import ABC, abstractmethod
+from typing import Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from autobyteus.workflow.context.workflow_context import WorkflowContext
+
+logger = logging.getLogger(__name__)
+
+class BaseWorkflowEventHandler(ABC):
+    """Abstract base class for workflow event handlers."""
+
+    @abstractmethod
+    async def handle(self, event: Any, context: 'WorkflowContext') -> None:
+        raise NotImplementedError("Subclasses must implement the 'handle' method.")

autobyteus/workflow/handlers/inter_agent_message_request_event_handler.py

@@ -0,0 +1,61 @@
+# file: autobyteus/autobyteus/workflow/handlers/inter_agent_message_request_event_handler.py
+import logging
+from typing import TYPE_CHECKING
+
+from autobyteus.workflow.handlers.base_workflow_event_handler import BaseWorkflowEventHandler
+from autobyteus.workflow.events.workflow_events import InterAgentMessageRequestEvent
+from autobyteus.agent.message.inter_agent_message import InterAgentMessage
+from autobyteus.agent.message.agent_input_user_message import AgentInputUserMessage
+from autobyteus.workflow.agentic_workflow import AgenticWorkflow
+from autobyteus.agent.agent import Agent
+
+if TYPE_CHECKING:
+    from autobyteus.workflow.context.workflow_context import WorkflowContext
+
+logger = logging.getLogger(__name__)
+
+class InterAgentMessageRequestEventHandler(BaseWorkflowEventHandler):
+    """
+    Handles requests to send messages between nodes (agents or sub-workflows).
+    It relies on the TeamManager to handle on-demand startup of the recipient.
+    """
+    async def handle(self, event: InterAgentMessageRequestEvent, context: 'WorkflowContext') -> None:
+        workflow_id = context.workflow_id
+        team_manager = context.team_manager
+        
+        if not team_manager:
+            logger.error(f"Workflow '{workflow_id}': TeamManager not found. Cannot route message from '{event.sender_agent_id}' to '{event.recipient_name}'.")
+            return
+
+        try:
+            target_node = await team_manager.ensure_node_is_ready(event.recipient_name)
+        except Exception as e:
+            msg = f"Recipient node '{event.recipient_name}' not found or failed to start for message from '{event.sender_agent_id}'. Error: {e}"
+            logger.error(f"Workflow '{workflow_id}': {msg}", exc_info=True)
+            return
+
+        try:
+            if isinstance(target_node, AgenticWorkflow):
+                # If target is a sub-workflow, post a user message to it.
+                # The sub-workflow will route it to its own coordinator.
+                message_for_workflow = AgentInputUserMessage(content=event.content)
+                await target_node.post_message(message_for_workflow)
+                logger.info(f"Workflow '{workflow_id}': Successfully posted message from '{event.sender_agent_id}' to sub-workflow '{event.recipient_name}'.")
+            
+            elif isinstance(target_node, Agent):
+                # If target is a regular agent, create and post an InterAgentMessage.
+                message_for_agent = InterAgentMessage.create_with_dynamic_message_type(
+                    recipient_role_name=target_node.context.config.role,
+                    recipient_agent_id=target_node.agent_id,
+                    content=event.content,
+                    message_type=event.message_type,
+                    sender_agent_id=event.sender_agent_id
+                )
+                await target_node.post_inter_agent_message(message_for_agent)
+                logger.info(f"Workflow '{workflow_id}': Successfully posted message from '{event.sender_agent_id}' to agent '{event.recipient_name}'.")
+            else:
+                raise TypeError(f"Target node '{event.recipient_name}' is of an unsupported type: {type(target_node).__name__}")
+        
+        except Exception as e:
+            msg = f"Error posting message to node '{event.recipient_name}': {e}"
+            logger.error(f"Workflow '{workflow_id}': {msg}", exc_info=True)

autobyteus/workflow/handlers/lifecycle_workflow_event_handler.py

@@ -0,0 +1,27 @@
+# file: autobyteus/autobyteus/workflow/handlers/lifecycle_workflow_event_handler.py
+import logging
+from typing import TYPE_CHECKING
+
+from autobyteus.workflow.handlers.base_workflow_event_handler import BaseWorkflowEventHandler
+from autobyteus.workflow.events.workflow_events import BaseWorkflowEvent, WorkflowReadyEvent, WorkflowErrorEvent
+
+if TYPE_CHECKING:
+    from autobyteus.workflow.context.workflow_context import WorkflowContext
+
+logger = logging.getLogger(__name__)
+
+class LifecycleWorkflowEventHandler(BaseWorkflowEventHandler):
+    """Logs various lifecycle events for a workflow."""
+    async def handle(self, event: BaseWorkflowEvent, context: 'WorkflowContext') -> None:
+        workflow_id = context.workflow_id
+        current_phase = context.state.current_phase.value
+
+        if isinstance(event, WorkflowReadyEvent):
+            logger.info(f"Workflow '{workflow_id}' Logged WorkflowReadyEvent. Current phase: {current_phase}")
+        elif isinstance(event, WorkflowErrorEvent):
+            logger.error(
+                f"Workflow '{workflow_id}' Logged WorkflowErrorEvent: {event.error_message}. "
+                f"Details: {event.exception_details}. Current phase: {current_phase}"
+            )
+        else:
+            logger.warning(f"LifecycleWorkflowEventHandler received unhandled event type: {type(event).__name__}")

autobyteus/workflow/handlers/process_user_message_event_handler.py

@@ -0,0 +1,46 @@
+# file: autobyteus/autobyteus/workflow/handlers/process_user_message_event_handler.py
+import logging
+from typing import TYPE_CHECKING
+from autobyteus.workflow.handlers.base_workflow_event_handler import BaseWorkflowEventHandler
+from autobyteus.workflow.events.workflow_events import ProcessUserMessageEvent
+from autobyteus.agent.agent import Agent
+from autobyteus.workflow.agentic_workflow import AgenticWorkflow
+from autobyteus.agent.message.agent_input_user_message import AgentInputUserMessage
+
+if TYPE_CHECKING:
+    from autobyteus.workflow.context.workflow_context import WorkflowContext
+
+logger = logging.getLogger(__name__)
+
+class ProcessUserMessageEventHandler(BaseWorkflowEventHandler):
+    """Handles user messages by routing them to the specified target agent or sub-workflow."""
+    async def handle(self, event: ProcessUserMessageEvent, context: 'WorkflowContext') -> None:
+        await context.phase_manager.notify_processing_started()
+        
+        team_manager = context.team_manager
+        if not team_manager:
+            msg = f"Workflow '{context.workflow_id}': TeamManager not found. Cannot route message."
+            logger.error(msg)
+            await context.phase_manager.notify_error_occurred(msg, "TeamManager is not initialized.")
+            return
+
+        try:
+            target_node = await team_manager.ensure_node_is_ready(event.target_agent_name)
+        except Exception as e:
+            msg = f"Workflow '{context.workflow_id}': Node '{event.target_agent_name}' not found or failed to start. Cannot route message. Error: {e}"
+            logger.error(msg, exc_info=True)
+            await context.phase_manager.notify_error_occurred(msg, f"Node '{event.target_agent_name}' not found or failed to start.")
+            return
+
+        if isinstance(target_node, Agent):
+            await target_node.post_user_message(event.user_message)
+            logger.info(f"Workflow '{context.workflow_id}': Routed user message to agent node '{event.target_agent_name}'.")
+        elif isinstance(target_node, AgenticWorkflow):
+            await target_node.post_message(event.user_message)
+            logger.info(f"Workflow '{context.workflow_id}': Routed user message to sub-workflow node '{event.target_agent_name}'.")
+        else:
+            msg = f"Target node '{event.target_agent_name}' is of an unsupported type: {type(target_node).__name__}"
+            logger.error(f"Workflow '{context.workflow_id}': {msg}")
+            await context.phase_manager.notify_error_occurred(msg, "")
+
+        await context.phase_manager.notify_processing_complete_and_idle()

autobyteus/workflow/handlers/tool_approval_workflow_event_handler.py

@@ -0,0 +1,39 @@
+# file: autobyteus/autobyteus/workflow/handlers/tool_approval_workflow_event_handler.py
+import logging
+from typing import TYPE_CHECKING
+
+from autobyteus.workflow.handlers.base_workflow_event_handler import BaseWorkflowEventHandler
+from autobyteus.workflow.events.workflow_events import ToolApprovalWorkflowEvent
+
+if TYPE_CHECKING:
+    from autobyteus.workflow.context.workflow_context import WorkflowContext
+
+logger = logging.getLogger(__name__)
+
+class ToolApprovalWorkflowEventHandler(BaseWorkflowEventHandler):
+    """
+    Handles tool approval events by routing them to the correct agent.
+    """
+    async def handle(self, event: ToolApprovalWorkflowEvent, context: 'WorkflowContext') -> None:
+        workflow_id = context.workflow_id
+        team_manager = context.team_manager
+
+        if not team_manager:
+            msg = f"Workflow '{workflow_id}': TeamManager not found. Cannot route approval for agent '{event.agent_name}'."
+            logger.error(msg)
+            await context.phase_manager.notify_error_occurred(msg, "TeamManager is not initialized.")
+            return
+
+        target_agent = await team_manager.ensure_agent_is_ready(event.agent_name)
+        if not target_agent:
+            msg = f"Workflow '{workflow_id}': Target agent '{event.agent_name}' for approval not found or failed to start."
+            logger.error(msg)
+            await context.phase_manager.notify_error_occurred(msg, f"Agent '{event.agent_name}' not found or failed to start.")
+            return
+
+        logger.info(f"Workflow '{workflow_id}': Posting tool approval (Approved: {event.is_approved}) to agent '{event.agent_name}' for invocation '{event.tool_invocation_id}'.")
+        await target_agent.post_tool_execution_approval(
+            tool_invocation_id=event.tool_invocation_id,
+            is_approved=event.is_approved,
+            reason=event.reason
+        )

autobyteus/workflow/handlers/workflow_event_handler_registry.py

@@ -0,0 +1,23 @@
+# file: autobyteus/autobyteus/workflow/handlers/workflow_event_handler_registry.py
+import logging
+from typing import Dict, Type, Optional
+
+from autobyteus.workflow.handlers.base_workflow_event_handler import BaseWorkflowEventHandler
+from autobyteus.workflow.events.workflow_events import BaseWorkflowEvent
+
+logger = logging.getLogger(__name__)
+
+class WorkflowEventHandlerRegistry:
+    """Manages registration and retrieval of workflow event handlers."""
+    def __init__(self):
+        self._handlers: Dict[Type[BaseWorkflowEvent], BaseWorkflowEventHandler] = {}
+        logger.info("WorkflowEventHandlerRegistry initialized.")
+
+    def register(self, event_class: Type[BaseWorkflowEvent], handler_instance: BaseWorkflowEventHandler):
+        if not issubclass(event_class, BaseWorkflowEvent):
+            raise TypeError("Can only register handlers for BaseWorkflowEvent subclasses.")
+        self._handlers[event_class] = handler_instance
+        logger.info(f"Handler '{type(handler_instance).__name__}' registered for event '{event_class.__name__}'.")
+
+    def get_handler(self, event_class: Type[BaseWorkflowEvent]) -> Optional[BaseWorkflowEventHandler]:
+        return self._handlers.get(event_class)

autobyteus/workflow/phases/__init__.py

@@ -0,0 +1,11 @@
+# file: autobyteus/autobyteus/workflow/phases/__init__.py
+"""
+This package contains components for defining and managing workflow operational phases.
+"""
+from autobyteus.workflow.phases.workflow_operational_phase import WorkflowOperationalPhase
+from autobyteus.workflow.phases.workflow_phase_manager import WorkflowPhaseManager
+
+__all__ = [
+    "WorkflowOperationalPhase",
+    "WorkflowPhaseManager",
+]

autobyteus/workflow/phases/workflow_operational_phase.py

@@ -0,0 +1,19 @@
+# file: autobyteus/autobyteus/workflow/phases/workflow_operational_phase.py
+from enum import Enum
+
+class WorkflowOperationalPhase(str, Enum):
+    """Defines the operational phases of an AgenticWorkflow."""
+    UNINITIALIZED = "uninitialized"
+    BOOTSTRAPPING = "bootstrapping"
+    IDLE = "idle"
+    PROCESSING = "processing"
+    SHUTTING_DOWN = "shutting_down"
+    SHUTDOWN_COMPLETE = "shutdown_complete"
+    ERROR = "error"
+
+    def is_terminal(self) -> bool:
+        """Checks if the phase is a terminal state."""
+        return self in [WorkflowOperationalPhase.SHUTDOWN_COMPLETE, WorkflowOperationalPhase.ERROR]
+
+    def __str__(self) -> str:
+        return self.value

autobyteus/workflow/phases/workflow_phase_manager.py

@@ -0,0 +1,48 @@
+# file: autobyteus/autobyteus/workflow/phases/workflow_phase_manager.py
+import logging
+from typing import TYPE_CHECKING, Optional
+
+from autobyteus.workflow.phases.workflow_operational_phase import WorkflowOperationalPhase
+
+if TYPE_CHECKING:
+    from autobyteus.workflow.context.workflow_context import WorkflowContext
+    from autobyteus.workflow.streaming.workflow_event_notifier import WorkflowExternalEventNotifier
+
+logger = logging.getLogger(__name__)
+
+class WorkflowPhaseManager:
+    """Manages the operational phase of a workflow."""
+    def __init__(self, context: 'WorkflowContext', notifier: 'WorkflowExternalEventNotifier'):
+        self.context = context
+        self.notifier = notifier
+        self.context.state.current_phase = WorkflowOperationalPhase.UNINITIALIZED
+        logger.debug(f"WorkflowPhaseManager initialized for workflow '{context.workflow_id}'.")
+
+    async def _transition_phase(self, new_phase: WorkflowOperationalPhase, extra_data: Optional[dict] = None):
+        old_phase = self.context.state.current_phase
+        if old_phase == new_phase:
+            return
+        logger.info(f"Workflow '{self.context.workflow_id}' transitioning from {old_phase.value} to {new_phase.value}.")
+        self.context.state.current_phase = new_phase
+        self.notifier.notify_phase_change(new_phase, old_phase, extra_data)
+
+    async def notify_bootstrapping_started(self):
+        await self._transition_phase(WorkflowOperationalPhase.BOOTSTRAPPING)
+
+    async def notify_initialization_complete(self):
+        await self._transition_phase(WorkflowOperationalPhase.IDLE)
+        
+    async def notify_processing_started(self):
+        await self._transition_phase(WorkflowOperationalPhase.PROCESSING)
+
+    async def notify_processing_complete_and_idle(self):
+        await self._transition_phase(WorkflowOperationalPhase.IDLE)
+
+    async def notify_error_occurred(self, error_message: str, error_details: Optional[str] = None):
+        await self._transition_phase(WorkflowOperationalPhase.ERROR, {"error_message": error_message, "error_details": error_details})
+
+    async def notify_shutdown_initiated(self):
+        await self._transition_phase(WorkflowOperationalPhase.SHUTTING_DOWN)
+
+    async def notify_final_shutdown_complete(self):
+        await self._transition_phase(WorkflowOperationalPhase.SHUTDOWN_COMPLETE)

autobyteus/workflow/runtime/__init__.py

@@ -0,0 +1,13 @@
+# file: autobyteus/autobyteus/workflow/runtime/__init__.py
+"""
+The workflow runtime contains the active execution components for a workflow,
+including the main WorkflowRuntime controller and the WorkflowWorker that runs
+in a dedicated thread.
+"""
+from autobyteus.workflow.runtime.workflow_runtime import WorkflowRuntime
+from autobyteus.workflow.runtime.workflow_worker import WorkflowWorker
+
+__all__ = [
+    "WorkflowRuntime",
+    "WorkflowWorker",
+]

autobyteus/workflow/runtime/workflow_runtime.py

@@ -0,0 +1,82 @@
+# file: autobyteus/autobyteus/workflow/runtime/workflow_runtime.py
+import asyncio
+import logging
+from typing import TYPE_CHECKING, Callable, Optional
+
+from autobyteus.workflow.context.workflow_context import WorkflowContext
+from autobyteus.workflow.phases.workflow_phase_manager import WorkflowPhaseManager
+from autobyteus.workflow.runtime.workflow_worker import WorkflowWorker
+from autobyteus.workflow.events.workflow_events import BaseWorkflowEvent
+from autobyteus.workflow.streaming.workflow_event_notifier import WorkflowExternalEventNotifier
+from autobyteus.workflow.streaming.agent_event_multiplexer import AgentEventMultiplexer
+
+if TYPE_CHECKING:
+    from autobyteus.workflow.handlers.workflow_event_handler_registry import WorkflowEventHandlerRegistry
+
+logger = logging.getLogger(__name__)
+
+class WorkflowRuntime:
+    """The active execution engine for a workflow, managing the worker."""
+    def __init__(self, context: WorkflowContext, event_handler_registry: 'WorkflowEventHandlerRegistry'):
+        self.context = context
+        self.notifier = WorkflowExternalEventNotifier(workflow_id=self.context.workflow_id, runtime_ref=self)
+        self.phase_manager = WorkflowPhaseManager(context=self.context, notifier=self.notifier)
+        
+        # --- FIX: Set the phase_manager_ref on the context's state BEFORE creating the worker ---
+        self.context.state.phase_manager_ref = self.phase_manager
+        
+        self._worker = WorkflowWorker(self.context, event_handler_registry)
+        
+        self.multiplexer = AgentEventMultiplexer(
+            workflow_id=self.context.workflow_id,
+            notifier=self.notifier,
+            worker_ref=self._worker
+        )
+        
+        # Set other references on the context's state object for access by other components
+        self.context.state.multiplexer_ref = self.multiplexer
+
+        self._worker.add_done_callback(self._handle_worker_completion)
+        logger.info(f"WorkflowRuntime initialized for workflow '{self.context.workflow_id}'.")
+
+    def get_worker_loop(self) -> Optional[asyncio.AbstractEventLoop]:
+        """Returns the worker's event loop if it's running."""
+        return self._worker.get_worker_loop()
+
+    def _handle_worker_completion(self, future: asyncio.Future):
+        workflow_id = self.context.workflow_id
+        try:
+            future.result()
+            logger.info(f"WorkflowRuntime '{workflow_id}': Worker thread completed.")
+        except Exception as e:
+            logger.error(f"WorkflowRuntime '{workflow_id}': Worker thread terminated with exception: {e}", exc_info=True)
+        if not self.context.state.current_phase.is_terminal():
+             asyncio.run(self.phase_manager.notify_final_shutdown_complete())
+        
+    def start(self):
+        if self._worker.is_alive:
+            return
+        self._worker.start()
+
+    async def stop(self, timeout: float = 10.0):
+        await self.phase_manager.notify_shutdown_initiated()
+        await self._worker.stop(timeout=timeout)
+        await self.phase_manager.notify_final_shutdown_complete()
+
+    async def submit_event(self, event: BaseWorkflowEvent):
+        if not self._worker.is_alive:
+            raise RuntimeError("Workflow worker is not active.")
+        def _coro_factory():
+            async def _enqueue():
+                from autobyteus.workflow.events.workflow_events import ProcessUserMessageEvent
+                if isinstance(event, ProcessUserMessageEvent):
+                    await self.context.state.input_event_queues.enqueue_user_message(event)
+                else:
+                    await self.context.state.input_event_queues.enqueue_internal_system_event(event)
+            return _enqueue()
+        future = self._worker.schedule_coroutine(_coro_factory)
+        await asyncio.wrap_future(future)
+
+    @property
+    def is_running(self) -> bool:
+        return self._worker.is_alive

autobyteus/workflow/runtime/workflow_worker.py

@@ -0,0 +1,117 @@
+# file: autobyteus/autobyteus/workflow/runtime/workflow_worker.py
+import asyncio
+import logging
+import concurrent.futures
+from typing import TYPE_CHECKING, Optional, Callable, Awaitable, Any
+
+from autobyteus.workflow.events.workflow_event_dispatcher import WorkflowEventDispatcher
+from autobyteus.workflow.bootstrap_steps.workflow_bootstrapper import WorkflowBootstrapper
+from autobyteus.workflow.shutdown_steps.workflow_shutdown_orchestrator import WorkflowShutdownOrchestrator
+from autobyteus.agent.runtime.agent_thread_pool_manager import AgentThreadPoolManager
+
+if TYPE_CHECKING:
+    from autobyteus.workflow.context.workflow_context import WorkflowContext
+    from autobyteus.workflow.handlers.workflow_event_handler_registry import WorkflowEventHandlerRegistry
+
+logger = logging.getLogger(__name__)
+
+class WorkflowWorker:
+    """Encapsulates the core event processing loop for a workflow."""
+    def __init__(self, context: 'WorkflowContext', event_handler_registry: 'WorkflowEventHandlerRegistry'):
+        self.context = context
+        self.phase_manager = self.context.phase_manager
+        self.event_dispatcher = WorkflowEventDispatcher(event_handler_registry, self.phase_manager)
+        
+        self._thread_pool_manager = AgentThreadPoolManager()
+        self._thread_future: Optional[concurrent.futures.Future] = None
+        self._worker_loop: Optional[asyncio.AbstractEventLoop] = None
+        self._async_stop_event: Optional[asyncio.Event] = None
+        self._is_active: bool = False
+        self._stop_initiated: bool = False
+        self._done_callbacks: list[Callable[[concurrent.futures.Future], None]] = []
+        logger.info(f"WorkflowWorker initialized for workflow '{self.context.workflow_id}'.")
+
+    def get_worker_loop(self) -> Optional[asyncio.AbstractEventLoop]:
+        """Returns the worker's event loop if it's running."""
+        return self._worker_loop if self._worker_loop and self._worker_loop.is_running() else None
+
+    def add_done_callback(self, callback: Callable):
+        if self._thread_future:
+            self._thread_future.add_done_callback(callback)
+        else:
+            self._done_callbacks.append(callback)
+
+    def schedule_coroutine(self, coro_factory: Callable[[], Awaitable[Any]]) -> concurrent.futures.Future:
+        if not self._worker_loop:
+            raise RuntimeError("WorkflowWorker loop is not available.")
+        return asyncio.run_coroutine_threadsafe(coro_factory(), self._worker_loop)
+
+    def start(self):
+        if self._is_active:
+            return
+        self._is_active = True
+        self._thread_future = self._thread_pool_manager.submit_task(self._run_managed_loop)
+        for cb in self._done_callbacks:
+            self._thread_future.add_done_callback(cb)
+        self._done_callbacks.clear()
+
+    def _run_managed_loop(self):
+        try:
+            self._worker_loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(self._worker_loop)
+            self._async_stop_event = asyncio.Event()
+            self._worker_loop.run_until_complete(self.async_run())
+        except Exception as e:
+            logger.error(f"WorkflowWorker '{self.context.workflow_id}' event loop crashed: {e}", exc_info=True)
+        finally:
+            if self._worker_loop:
+                self._worker_loop.close()
+            self._is_active = False
+
+    async def async_run(self):
+        bootstrapper = WorkflowBootstrapper()
+        if not await bootstrapper.run(self.context, self.phase_manager):
+            logger.critical(f"Workflow '{self.context.workflow_id}' failed to initialize. Shutting down.")
+            return
+
+        logger.info(f"Workflow '{self.context.workflow_id}' entering main event loop.")
+        while not self._async_stop_event.is_set():
+            try:
+                # Combine queues for a single wait point
+                user_message_task = asyncio.create_task(self.context.state.input_event_queues.user_message_queue.get())
+                system_task = asyncio.create_task(self.context.state.input_event_queues.internal_system_event_queue.get())
+                done, pending = await asyncio.wait([user_message_task, system_task], return_when=asyncio.FIRST_COMPLETED, timeout=0.2)
+                
+                for task in pending:
+                    task.cancel()
+                
+                if not done:
+                    continue
+
+                event = done.pop().result()
+                await self.event_dispatcher.dispatch(event, self.context)
+
+            except asyncio.TimeoutError:
+                continue
+        
+        logger.info(f"Workflow '{self.context.workflow_id}' shutdown signal received. Cleaning up.")
+        shutdown_orchestrator = WorkflowShutdownOrchestrator()
+        await shutdown_orchestrator.run(self.context)
+
+    async def stop(self, timeout: float = 10.0):
+        if not self._is_active or self._stop_initiated:
+            return
+        self._stop_initiated = True
+        if self._worker_loop:
+            self._worker_loop.call_soon_threadsafe(self._async_stop_event.set)
+        if self._thread_future:
+            try:
+                # FIX: Use asyncio.wait_for() to handle the timeout correctly.
+                await asyncio.wait_for(asyncio.wrap_future(self._thread_future), timeout=timeout)
+            except asyncio.TimeoutError:
+                logger.warning(f"Timeout waiting for workflow worker '{self.context.workflow_id}' to terminate.")
+        self._is_active = False
+
+    @property
+    def is_alive(self) -> bool:
+        return self._thread_future is not None and not self._thread_future.done()

autobyteus/workflow/shutdown_steps/__init__.py

@@ -0,0 +1,17 @@
+# file: autobyteus/autobyteus/workflow/shutdown_steps/__init__.py
+"""
+Defines individual, self-contained steps for the workflow shutdown process.
+"""
+from autobyteus.workflow.shutdown_steps.base_workflow_shutdown_step import BaseWorkflowShutdownStep
+from autobyteus.workflow.shutdown_steps.agent_team_shutdown_step import AgentTeamShutdownStep
+from autobyteus.workflow.shutdown_steps.sub_workflow_shutdown_step import SubWorkflowShutdownStep
+from autobyteus.workflow.shutdown_steps.bridge_cleanup_step import BridgeCleanupStep
+from autobyteus.workflow.shutdown_steps.workflow_shutdown_orchestrator import WorkflowShutdownOrchestrator
+
+__all__ = [
+    "BaseWorkflowShutdownStep",
+    "AgentTeamShutdownStep",
+    "SubWorkflowShutdownStep",
+    "BridgeCleanupStep",
+    "WorkflowShutdownOrchestrator",
+]