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

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",
+]

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",
+]