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

autobyteus/agent_team/events/agent_team_events.py

@@ -0,0 +1,53 @@
+# file: autobyteus/autobyteus/agent_team/events/agent_team_events.py
+from dataclasses import dataclass
+from typing import Dict, Any, Optional
+
+from autobyteus.agent.message.agent_input_user_message import AgentInputUserMessage
+
+@dataclass
+class BaseAgentTeamEvent:
+    """Base class for all agent team events."""
+
+@dataclass
+class LifecycleAgentTeamEvent(BaseAgentTeamEvent):
+    """Base class for events related to the agent team's lifecycle."""
+
+@dataclass
+class OperationalAgentTeamEvent(BaseAgentTeamEvent):
+    """Base class for events related to the agent team's operational logic."""
+
+# Specific Events
+@dataclass
+class AgentTeamReadyEvent(LifecycleAgentTeamEvent):
+    """Indicates the agent team has completed bootstrapping and is ready for tasks."""
+
+@dataclass
+class AgentTeamErrorEvent(LifecycleAgentTeamEvent):
+    """Indicates a significant error occurred within the agent team."""
+    error_message: str
+    exception_details: Optional[str] = None
+
+@dataclass
+class ProcessUserMessageEvent(OperationalAgentTeamEvent):
+    """Carries a user's message to be processed by a specific agent in the team."""
+    user_message: AgentInputUserMessage
+    target_agent_name: str
+
+@dataclass
+class InterAgentMessageRequestEvent(OperationalAgentTeamEvent):
+    """
+    An internal request within the agent team 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 ToolApprovalTeamEvent(OperationalAgentTeamEvent):
+    """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/agent_team/events/agent_team_input_event_queue_manager.py

@@ -0,0 +1,21 @@
+# file: autobyteus/autobyteus/agent_team/events/agent_team_input_event_queue_manager.py
+import asyncio
+import logging
+from typing import Any
+
+from autobyteus.agent_team.events.agent_team_events import ProcessUserMessageEvent
+
+logger = logging.getLogger(__name__)
+
+class AgentTeamInputEventQueueManager:
+    """Manages asyncio.Queue instances for events consumed by the AgentTeamWorker."""
+    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("AgentTeamInputEventQueueManager 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/agent_team/exceptions.py

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

autobyteus/agent_team/factory/__init__.py

@@ -0,0 +1,9 @@
+# file: autobyteus/autobyteus/agent_team/factory/__init__.py
+"""
+Agent team factory for creating AgentTeam instances.
+"""
+from autobyteus.agent_team.factory.agent_team_factory import AgentTeamFactory
+
+__all__ = [
+    "AgentTeamFactory",
+]

autobyteus/agent_team/factory/agent_team_factory.py

@@ -0,0 +1,99 @@
+# file: autobyteus/autobyteus/agent_team/factory/agent_team_factory.py
+import logging
+import uuid
+from typing import Optional, Dict, List
+
+from autobyteus.utils.singleton import SingletonMeta
+from autobyteus.agent_team.agent_team import AgentTeam
+from autobyteus.agent_team.context.agent_team_config import AgentTeamConfig
+from autobyteus.agent_team.context.agent_team_context import AgentTeamContext
+from autobyteus.agent_team.context.agent_team_runtime_state import AgentTeamRuntimeState
+from autobyteus.agent_team.context.team_manager import TeamManager
+from autobyteus.agent_team.runtime.agent_team_runtime import AgentTeamRuntime
+from autobyteus.agent_team.handlers.agent_team_event_handler_registry import AgentTeamEventHandlerRegistry
+from autobyteus.agent_team.handlers.process_user_message_event_handler import ProcessUserMessageEventHandler
+from autobyteus.agent_team.handlers.lifecycle_agent_team_event_handler import LifecycleAgentTeamEventHandler
+from autobyteus.agent_team.handlers.inter_agent_message_request_event_handler import InterAgentMessageRequestEventHandler
+from autobyteus.agent_team.handlers.tool_approval_team_event_handler import ToolApprovalTeamEventHandler
+from autobyteus.agent_team.events.agent_team_events import (
+    ProcessUserMessageEvent,
+    AgentTeamReadyEvent,
+    AgentTeamErrorEvent,
+    InterAgentMessageRequestEvent,
+    ToolApprovalTeamEvent
+)
+
+logger = logging.getLogger(__name__)
+
+class AgentTeamFactory(metaclass=SingletonMeta):
+    """
+    A singleton factory for creating and managing AgentTeam instances.
+    It orchestrates the assembly of all core agent team components.
+    """
+    def __init__(self):
+        self._active_teams: Dict[str, AgentTeam] = {}
+        logger.info("AgentTeamFactory (Singleton) initialized.")
+
+    def _get_default_event_handler_registry(self) -> AgentTeamEventHandlerRegistry:
+        """Returns a registry with default handlers for a new agent team."""
+        registry = AgentTeamEventHandlerRegistry()
+        registry.register(ProcessUserMessageEvent, ProcessUserMessageEventHandler())
+        registry.register(InterAgentMessageRequestEvent, InterAgentMessageRequestEventHandler())
+        registry.register(ToolApprovalTeamEvent, ToolApprovalTeamEventHandler())
+        lifecycle_handler = LifecycleAgentTeamEventHandler()
+        registry.register(AgentTeamReadyEvent, lifecycle_handler)
+        registry.register(AgentTeamErrorEvent, lifecycle_handler)
+        return registry
+
+    def create_team(self, config: AgentTeamConfig) -> AgentTeam:
+        """
+        Creates a new agent team based on the provided AgentTeamConfig, stores it,
+        and returns its facade (AgentTeam).
+        """
+        if not isinstance(config, AgentTeamConfig):
+            raise TypeError(f"Expected AgentTeamConfig instance, got {type(config).__name__}.")
+
+        team_id = f"team_{uuid.uuid4().hex[:8]}"
+        while team_id in self._active_teams:
+            team_id = f"team_{uuid.uuid4().hex[:8]}"
+
+        # --- Component Assembly as per new architecture ---
+        state = AgentTeamRuntimeState(team_id=team_id)
+        context = AgentTeamContext(team_id=team_id, config=config, state=state)
+        
+        handler_registry = self._get_default_event_handler_registry()
+        runtime = AgentTeamRuntime(context=context, event_handler_registry=handler_registry)
+        
+        team_manager = TeamManager(
+            team_id=team_id,
+            runtime=runtime,
+            multiplexer=runtime.multiplexer # Pass multiplexer created in runtime
+        )
+        
+        context.state.team_manager = team_manager
+        
+        team = AgentTeam(runtime=runtime)
+        
+        self._active_teams[team_id] = team
+        logger.info(f"Agent Team '{team_id}' created and stored successfully.")
+        return team
+
+    def get_team(self, team_id: str) -> Optional[AgentTeam]:
+        """Retrieves an active agent team instance by its ID."""
+        return self._active_teams.get(team_id)
+
+    async def remove_team(self, team_id: str, shutdown_timeout: float = 10.0) -> bool:
+        """
+        Removes an agent team from the factory's management and gracefully stops it.
+        """
+        team = self._active_teams.pop(team_id, None)
+        if team:
+            logger.info(f"Removing agent team '{team_id}'. Attempting graceful shutdown.")
+            await team.stop(timeout=shutdown_timeout)
+            return True
+        logger.warning(f"Agent team with ID '{team_id}' not found for removal.")
+        return False
+
+    def list_active_team_ids(self) -> List[str]:
+        """Returns a list of IDs of all active agent teams managed by this factory."""
+        return list(self._active_teams.keys())

autobyteus/agent_team/handlers/__init__.py

@@ -0,0 +1,19 @@
+# file: autobyteus/autobyteus/agent_team/handlers/__init__.py
+"""
+Event handlers for the agent team runtime.
+"""
+from autobyteus.agent_team.handlers.base_agent_team_event_handler import BaseAgentTeamEventHandler
+from autobyteus.agent_team.handlers.lifecycle_agent_team_event_handler import LifecycleAgentTeamEventHandler
+from autobyteus.agent_team.handlers.inter_agent_message_request_event_handler import InterAgentMessageRequestEventHandler
+from autobyteus.agent_team.handlers.process_user_message_event_handler import ProcessUserMessageEventHandler
+from autobyteus.agent_team.handlers.tool_approval_team_event_handler import ToolApprovalTeamEventHandler
+from autobyteus.agent_team.handlers.agent_team_event_handler_registry import AgentTeamEventHandlerRegistry
+
+__all__ = [
+    "BaseAgentTeamEventHandler",
+    "LifecycleAgentTeamEventHandler",
+    "InterAgentMessageRequestEventHandler",
+    "ProcessUserMessageEventHandler",
+    "ToolApprovalTeamEventHandler",
+    "AgentTeamEventHandlerRegistry",
+]

autobyteus/agent_team/handlers/agent_team_event_handler_registry.py

@@ -0,0 +1,23 @@
+# file: autobyteus/autobyteus/agent_team/handlers/agent_team_event_handler_registry.py
+import logging
+from typing import Dict, Type, Optional
+
+from autobyteus.agent_team.handlers.base_agent_team_event_handler import BaseAgentTeamEventHandler
+from autobyteus.agent_team.events.agent_team_events import BaseAgentTeamEvent
+
+logger = logging.getLogger(__name__)
+
+class AgentTeamEventHandlerRegistry:
+    """Manages registration and retrieval of agent team event handlers."""
+    def __init__(self):
+        self._handlers: Dict[Type[BaseAgentTeamEvent], BaseAgentTeamEventHandler] = {}
+        logger.info("AgentTeamEventHandlerRegistry initialized.")
+
+    def register(self, event_class: Type[BaseAgentTeamEvent], handler_instance: BaseAgentTeamEventHandler):
+        if not issubclass(event_class, BaseAgentTeamEvent):
+            raise TypeError("Can only register handlers for BaseAgentTeamEvent 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[BaseAgentTeamEvent]) -> Optional[BaseAgentTeamEventHandler]:
+        return self._handlers.get(event_class)

autobyteus/agent_team/handlers/base_agent_team_event_handler.py

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

autobyteus/agent_team/handlers/inter_agent_message_request_event_handler.py

@@ -0,0 +1,61 @@
+# file: autobyteus/autobyteus/agent_team/handlers/inter_agent_message_request_event_handler.py
+import logging
+from typing import TYPE_CHECKING
+
+from autobyteus.agent_team.handlers.base_agent_team_event_handler import BaseAgentTeamEventHandler
+from autobyteus.agent_team.events.agent_team_events import InterAgentMessageRequestEvent
+from autobyteus.agent.message.inter_agent_message import InterAgentMessage
+from autobyteus.agent.message.agent_input_user_message import AgentInputUserMessage
+from autobyteus.agent_team.agent_team import AgentTeam
+from autobyteus.agent.agent import Agent
+
+if TYPE_CHECKING:
+    from autobyteus.agent_team.context.agent_team_context import AgentTeamContext
+
+logger = logging.getLogger(__name__)
+
+class InterAgentMessageRequestEventHandler(BaseAgentTeamEventHandler):
+    """
+    Handles requests to send messages between nodes (agents or sub-teams).
+    It relies on the TeamManager to handle on-demand startup of the recipient.
+    """
+    async def handle(self, event: InterAgentMessageRequestEvent, context: 'AgentTeamContext') -> None:
+        team_id = context.team_id
+        team_manager = context.team_manager
+        
+        if not team_manager:
+            logger.error(f"Team '{team_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(name_or_agent_id=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"Team '{team_id}': {msg}", exc_info=True)
+            return
+
+        try:
+            if isinstance(target_node, AgentTeam):
+                # If target is a sub-team, post a user message to it.
+                # The sub-team will route it to its own coordinator.
+                message_for_team = AgentInputUserMessage(content=event.content)
+                await target_node.post_message(message_for_team)
+                logger.info(f"Team '{team_id}': Successfully posted message from '{event.sender_agent_id}' to sub-team '{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"Team '{team_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"Team '{team_id}': {msg}", exc_info=True)

autobyteus/agent_team/handlers/lifecycle_agent_team_event_handler.py

@@ -0,0 +1,27 @@
+# file: autobyteus/autobyteus/agent_team/handlers/lifecycle_agent_team_event_handler.py
+import logging
+from typing import TYPE_CHECKING
+
+from autobyteus.agent_team.handlers.base_agent_team_event_handler import BaseAgentTeamEventHandler
+from autobyteus.agent_team.events.agent_team_events import BaseAgentTeamEvent, AgentTeamReadyEvent, AgentTeamErrorEvent
+
+if TYPE_CHECKING:
+    from autobyteus.agent_team.context.agent_team_context import AgentTeamContext
+
+logger = logging.getLogger(__name__)
+
+class LifecycleAgentTeamEventHandler(BaseAgentTeamEventHandler):
+    """Logs various lifecycle events for an agent team."""
+    async def handle(self, event: BaseAgentTeamEvent, context: 'AgentTeamContext') -> None:
+        team_id = context.team_id
+        current_phase = context.state.current_phase.value
+
+        if isinstance(event, AgentTeamReadyEvent):
+            logger.info(f"Team '{team_id}' Logged AgentTeamReadyEvent. Current phase: {current_phase}")
+        elif isinstance(event, AgentTeamErrorEvent):
+            logger.error(
+                f"Team '{team_id}' Logged AgentTeamErrorEvent: {event.error_message}. "
+                f"Details: {event.exception_details}. Current phase: {current_phase}"
+            )
+        else:
+            logger.warning(f"LifecycleAgentTeamEventHandler received unhandled event type: {type(event).__name__}")

autobyteus/agent_team/handlers/process_user_message_event_handler.py

@@ -0,0 +1,46 @@
+# file: autobyteus/autobyteus/agent_team/handlers/process_user_message_event_handler.py
+import logging
+from typing import TYPE_CHECKING
+from autobyteus.agent_team.handlers.base_agent_team_event_handler import BaseAgentTeamEventHandler
+from autobyteus.agent_team.events.agent_team_events import ProcessUserMessageEvent
+from autobyteus.agent.agent import Agent
+from autobyteus.agent_team.agent_team import AgentTeam
+from autobyteus.agent.message.agent_input_user_message import AgentInputUserMessage
+
+if TYPE_CHECKING:
+    from autobyteus.agent_team.context.agent_team_context import AgentTeamContext
+
+logger = logging.getLogger(__name__)
+
+class ProcessUserMessageEventHandler(BaseAgentTeamEventHandler):
+    """Handles user messages by routing them to the specified target agent or sub-team."""
+    async def handle(self, event: ProcessUserMessageEvent, context: 'AgentTeamContext') -> None:
+        await context.phase_manager.notify_processing_started()
+        
+        team_manager = context.team_manager
+        if not team_manager:
+            msg = f"Team '{context.team_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(name_or_agent_id=event.target_agent_name)
+        except Exception as e:
+            msg = f"Team '{context.team_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"Team '{context.team_id}': Routed user message to agent node '{event.target_agent_name}'.")
+        elif isinstance(target_node, AgentTeam):
+            await target_node.post_message(event.user_message)
+            logger.info(f"Team '{context.team_id}': Routed user message to sub-team 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"Team '{context.team_id}': {msg}")
+            await context.phase_manager.notify_error_occurred(msg, "")
+
+        await context.phase_manager.notify_processing_complete_and_idle()

autobyteus/agent_team/handlers/tool_approval_team_event_handler.py

@@ -0,0 +1,48 @@
+# file: autobyteus/autobyteus/agent_team/handlers/tool_approval_team_event_handler.py
+import logging
+from typing import TYPE_CHECKING
+
+from autobyteus.agent_team.handlers.base_agent_team_event_handler import BaseAgentTeamEventHandler
+from autobyteus.agent_team.events.agent_team_events import ToolApprovalTeamEvent
+
+if TYPE_CHECKING:
+    from autobyteus.agent_team.context.agent_team_context import AgentTeamContext
+
+logger = logging.getLogger(__name__)
+
+class ToolApprovalTeamEventHandler(BaseAgentTeamEventHandler):
+    """
+    Handles tool approval events by routing them to the correct agent.
+    """
+    async def handle(self, event: ToolApprovalTeamEvent, context: 'AgentTeamContext') -> None:
+        team_id = context.team_id
+        team_manager = context.team_manager
+
+        if not team_manager:
+            msg = f"Team '{team_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
+
+        from autobyteus.agent.agent import Agent
+        target_node = await team_manager.ensure_node_is_ready(name_or_agent_id=event.agent_name)
+        if not isinstance(target_node, Agent):
+            msg = f"Team '{team_id}': Target node '{event.agent_name}' for approval is not an agent."
+            logger.error(msg)
+            await context.phase_manager.notify_error_occurred(msg, f"Node '{event.agent_name}' is not an agent.")
+            return
+        
+        target_agent = target_node
+
+        if not target_agent:
+            msg = f"Team '{team_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"Team '{team_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/agent_team/phases/__init__.py

@@ -0,0 +1,11 @@
+# file: autobyteus/autobyteus/agent_team/phases/__init__.py
+"""
+This package contains components for defining and managing agent team operational phases.
+"""
+from autobyteus.agent_team.phases.agent_team_operational_phase import AgentTeamOperationalPhase
+from autobyteus.agent_team.phases.agent_team_phase_manager import AgentTeamPhaseManager
+
+__all__ = [
+    "AgentTeamOperationalPhase",
+    "AgentTeamPhaseManager",
+]

autobyteus/agent_team/phases/agent_team_operational_phase.py

@@ -0,0 +1,19 @@
+# file: autobyteus/autobyteus/agent_team/phases/agent_team_operational_phase.py
+from enum import Enum
+
+class AgentTeamOperationalPhase(str, Enum):
+    """Defines the operational phases of an AgentTeam."""
+    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 [AgentTeamOperationalPhase.SHUTDOWN_COMPLETE, AgentTeamOperationalPhase.ERROR]
+
+    def __str__(self) -> str:
+        return self.value

autobyteus/agent_team/phases/agent_team_phase_manager.py

@@ -0,0 +1,48 @@
+# file: autobyteus/autobyteus/agent_team/phases/agent_team_phase_manager.py
+import logging
+from typing import TYPE_CHECKING, Optional
+
+from autobyteus.agent_team.phases.agent_team_operational_phase import AgentTeamOperationalPhase
+
+if TYPE_CHECKING:
+    from autobyteus.agent_team.context.agent_team_context import AgentTeamContext
+    from autobyteus.agent_team.streaming.agent_team_event_notifier import AgentTeamExternalEventNotifier
+
+logger = logging.getLogger(__name__)
+
+class AgentTeamPhaseManager:
+    """Manages the operational phase of an agent team."""
+    def __init__(self, context: 'AgentTeamContext', notifier: 'AgentTeamExternalEventNotifier'):
+        self.context = context
+        self.notifier = notifier
+        self.context.state.current_phase = AgentTeamOperationalPhase.UNINITIALIZED
+        logger.debug(f"AgentTeamPhaseManager initialized for team '{context.team_id}'.")
+
+    async def _transition_phase(self, new_phase: AgentTeamOperationalPhase, extra_data: Optional[dict] = None):
+        old_phase = self.context.state.current_phase
+        if old_phase == new_phase:
+            return
+        logger.info(f"Team '{self.context.team_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(AgentTeamOperationalPhase.BOOTSTRAPPING)
+
+    async def notify_initialization_complete(self):
+        await self._transition_phase(AgentTeamOperationalPhase.IDLE)
+        
+    async def notify_processing_started(self):
+        await self._transition_phase(AgentTeamOperationalPhase.PROCESSING)
+
+    async def notify_processing_complete_and_idle(self):
+        await self._transition_phase(AgentTeamOperationalPhase.IDLE)
+
+    async def notify_error_occurred(self, error_message: str, error_details: Optional[str] = None):
+        await self._transition_phase(AgentTeamOperationalPhase.ERROR, {"error_message": error_message, "error_details": error_details})
+
+    async def notify_shutdown_initiated(self):
+        await self._transition_phase(AgentTeamOperationalPhase.SHUTTING_DOWN)
+
+    async def notify_final_shutdown_complete(self):
+        await self._transition_phase(AgentTeamOperationalPhase.SHUTDOWN_COMPLETE)

autobyteus/agent_team/runtime/__init__.py

@@ -0,0 +1,13 @@
+# file: autobyteus/autobyteus/agent_team/runtime/__init__.py
+"""
+The agent team runtime contains the active execution components for a team,
+including the main AgentTeamRuntime controller and the AgentTeamWorker that runs
+in a dedicated thread.
+"""
+from autobyteus.agent_team.runtime.agent_team_runtime import AgentTeamRuntime
+from autobyteus.agent_team.runtime.agent_team_worker import AgentTeamWorker
+
+__all__ = [
+    "AgentTeamRuntime",
+    "AgentTeamWorker",
+]

autobyteus/agent_team/runtime/agent_team_runtime.py

@@ -0,0 +1,82 @@
+# file: autobyteus/autobyteus/agent_team/runtime/agent_team_runtime.py
+import asyncio
+import logging
+from typing import TYPE_CHECKING, Callable, Optional
+
+from autobyteus.agent_team.context.agent_team_context import AgentTeamContext
+from autobyteus.agent_team.phases.agent_team_phase_manager import AgentTeamPhaseManager
+from autobyteus.agent_team.runtime.agent_team_worker import AgentTeamWorker
+from autobyteus.agent_team.events.agent_team_events import BaseAgentTeamEvent
+from autobyteus.agent_team.streaming.agent_team_event_notifier import AgentTeamExternalEventNotifier
+from autobyteus.agent_team.streaming.agent_event_multiplexer import AgentEventMultiplexer
+
+if TYPE_CHECKING:
+    from autobyteus.agent_team.handlers.agent_team_event_handler_registry import AgentTeamEventHandlerRegistry
+
+logger = logging.getLogger(__name__)
+
+class AgentTeamRuntime:
+    """The active execution engine for an agent team, managing the worker."""
+    def __init__(self, context: AgentTeamContext, event_handler_registry: 'AgentTeamEventHandlerRegistry'):
+        self.context = context
+        self.notifier = AgentTeamExternalEventNotifier(team_id=self.context.team_id, runtime_ref=self)
+        self.phase_manager = AgentTeamPhaseManager(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 = AgentTeamWorker(self.context, event_handler_registry)
+        
+        self.multiplexer = AgentEventMultiplexer(
+            team_id=self.context.team_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"AgentTeamRuntime initialized for team '{self.context.team_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):
+        team_id = self.context.team_id
+        try:
+            future.result()
+            logger.info(f"AgentTeamRuntime '{team_id}': Worker thread completed.")
+        except Exception as e:
+            logger.error(f"AgentTeamRuntime '{team_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: BaseAgentTeamEvent):
+        if not self._worker.is_alive:
+            raise RuntimeError("Agent team worker is not active.")
+        def _coro_factory():
+            async def _enqueue():
+                from autobyteus.agent_team.events.agent_team_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