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

autobyteus/agent_team/bootstrap_steps/coordinator_prompt_preparation_step.py

@@ -0,0 +1,85 @@
+# file: autobyteus/autobyteus/agent_team/bootstrap_steps/coordinator_prompt_preparation_step.py
+import logging
+from typing import TYPE_CHECKING, List
+
+from autobyteus.agent_team.bootstrap_steps.base_agent_team_bootstrap_step import BaseAgentTeamBootstrapStep
+from autobyteus.agent.context import AgentConfig
+from autobyteus.agent_team.context import AgentTeamConfig
+
+if TYPE_CHECKING:
+    from autobyteus.agent_team.context.agent_team_context import AgentTeamContext
+    from autobyteus.agent_team.phases.agent_team_phase_manager import AgentTeamPhaseManager
+
+logger = logging.getLogger(__name__)
+
+class CoordinatorPromptPreparationStep(BaseAgentTeamBootstrapStep):
+    """
+    Bootstrap step to finalize the coordinator's system prompt by injecting a
+    dynamically generated team manifest into a user-defined prompt template.
+    The user is expected to provide a `system_prompt` in the coordinator's
+    AgentConfig with a `{{team}}` placeholder.
+    """
+    async def execute(self, context: 'AgentTeamContext', phase_manager: 'AgentTeamPhaseManager') -> bool:
+        team_id = context.team_id
+        logger.info(f"Team '{team_id}': Executing CoordinatorPromptPreparationStep.")
+        try:
+            coordinator_node_config_wrapper = context.config.coordinator_node
+            
+            # The coordinator must be an agent with a defined config.
+            if not isinstance(coordinator_node_config_wrapper.node_definition, AgentConfig):
+                logger.error(f"Team '{team_id}': Coordinator node '{coordinator_node_config_wrapper.name}' is not defined by an AgentConfig. Cannot prepare prompt.")
+                return False
+            
+            coordinator_agent_config: AgentConfig = coordinator_node_config_wrapper.node_definition
+            
+            # Start with the user's provided prompt template.
+            prompt_template = coordinator_agent_config.system_prompt
+            if not prompt_template:
+                logger.warning(f"Team '{team_id}': Coordinator '{coordinator_agent_config.name}' has no system_prompt defined. No prompt will be applied.")
+                context.state.prepared_coordinator_prompt = ""
+                return True
+
+            team_manifest = self._generate_team_manifest(context)
+            
+            # Inject the manifest into the template.
+            if "{{team}}" in prompt_template:
+                final_prompt = prompt_template.replace("{{team}}", team_manifest)
+                logger.debug(f"Team '{team_id}': Injected team manifest into coordinator's system prompt.")
+            else:
+                final_prompt = prompt_template
+                logger.warning(f"Team '{team_id}': The coordinator's system prompt does not contain a '{{team}}' placeholder. The team manifest will not be injected.")
+            
+            # Store the finalized prompt in the state for the AgentToolInjectionStep to use.
+            context.state.prepared_coordinator_prompt = final_prompt
+
+            logger.info(f"Team '{team_id}': Coordinator prompt prepared successfully and stored in state.")
+            return True
+        except Exception as e:
+            logger.error(f"Team '{team_id}': Failed to prepare coordinator prompt: {e}", exc_info=True)
+            return False
+
+    def _generate_team_manifest(self, context: 'AgentTeamContext') -> str:
+        """Generates a string manifest of all non-coordinator team members."""
+        prompt_parts: List[str] = []
+        coordinator_node = context.config.coordinator_node
+        member_nodes = {node for node in context.config.nodes if node != coordinator_node}
+
+        if not member_nodes:
+            return "You are working alone. You have no team members to delegate to."
+
+        # Sort for deterministic prompt generation
+        for node in sorted(list(member_nodes), key=lambda n: n.name):
+            node_def = node.node_definition
+            description = "No description available."
+            
+            # --- THE FIX ---
+            # Use the 'description' for an AgentConfig and the 'role' for an AgentTeamConfig (sub-team).
+            if isinstance(node_def, AgentConfig):
+                description = node_def.description
+            elif isinstance(node_def, AgentTeamConfig):
+                # A sub-team's role is its most concise and relevant description for a parent coordinator.
+                description = node_def.role or node_def.description
+            
+            prompt_parts.append(f"- name: {node.name}\n  description: {description}")
+        
+        return "\n".join(prompt_parts)

autobyteus/agent_team/bootstrap_steps/task_notifier_initialization_step.py

@@ -0,0 +1,51 @@
+# file: autobyteus/autobyteus/agent_team/bootstrap_steps/task_notifier_initialization_step.py
+import logging
+from typing import TYPE_CHECKING
+
+from autobyteus.agent_team.bootstrap_steps.base_agent_team_bootstrap_step import BaseAgentTeamBootstrapStep
+from autobyteus.agent_team.task_notification.task_notification_mode import TaskNotificationMode
+from autobyteus.agent_team.task_notification.system_event_driven_agent_task_notifier import SystemEventDrivenAgentTaskNotifier
+
+if TYPE_CHECKING:
+    from autobyteus.agent_team.context.agent_team_context import AgentTeamContext
+    from autobyteus.agent_team.phases.agent_team_phase_manager import AgentTeamPhaseManager
+
+logger = logging.getLogger(__name__)
+
+class TaskNotifierInitializationStep(BaseAgentTeamBootstrapStep):
+    """
+    Bootstrap step to initialize the SystemEventDrivenAgentTaskNotifier if the
+    team is configured for event-driven notifications.
+    """
+    async def execute(self, context: 'AgentTeamContext', phase_manager: 'AgentTeamPhaseManager') -> bool:
+        team_id = context.team_id
+        logger.info(f"Team '{team_id}': Executing TaskNotifierInitializationStep.")
+        
+        if context.config.task_notification_mode != TaskNotificationMode.SYSTEM_EVENT_DRIVEN:
+            logger.info(f"Team '{team_id}': Task notification mode is '{context.config.task_notification_mode.value}'. Skipping event-driven notifier setup.")
+            return True
+
+        logger.info(f"Team '{team_id}': Mode is SYSTEM_EVENT_DRIVEN. Initializing and activating task notifier.")
+        try:
+            task_board = context.state.task_board
+            if not task_board:
+                logger.error(f"Team '{team_id}': TaskBoard not found. Cannot initialize task notifier. This step should run after TeamContextInitializationStep.")
+                return False
+
+            team_manager = context.team_manager
+            if not team_manager:
+                logger.error(f"Team '{team_id}': TeamManager not found. Cannot initialize task notifier.")
+                return False
+
+            notifier = SystemEventDrivenAgentTaskNotifier(
+                task_board=task_board, 
+                team_manager=team_manager
+            )
+            notifier.start_monitoring()
+            
+            context.state.task_notifier = notifier
+            logger.info(f"Team '{team_id}': SystemEventDrivenAgentTaskNotifier initialized and monitoring started.")
+            return True
+        except Exception as e:
+            logger.error(f"Team '{team_id}': Critical failure during task notifier initialization: {e}", exc_info=True)
+            return False

autobyteus/agent_team/bootstrap_steps/team_context_initialization_step.py

@@ -0,0 +1,45 @@
+# file: autobyteus/autobyteus/agent_team/bootstrap_steps/team_context_initialization_step.py
+import logging
+from typing import TYPE_CHECKING
+
+from autobyteus.agent_team.bootstrap_steps.base_agent_team_bootstrap_step import BaseAgentTeamBootstrapStep
+from autobyteus.task_management import TaskBoard
+from autobyteus.events.event_types import EventType
+
+if TYPE_CHECKING:
+    from autobyteus.agent_team.context.agent_team_context import AgentTeamContext
+    from autobyteus.agent_team.phases.agent_team_phase_manager import AgentTeamPhaseManager
+
+logger = logging.getLogger(__name__)
+
+class TeamContextInitializationStep(BaseAgentTeamBootstrapStep):
+    """
+    Bootstrap step to initialize shared team context components, such as the
+    TaskBoard, and bridges its events to the team's notifier.
+    """
+    async def execute(self, context: 'AgentTeamContext', phase_manager: 'AgentTeamPhaseManager') -> bool:
+        team_id = context.team_id
+        logger.info(f"Team '{team_id}': Executing TeamContextInitializationStep.")
+        try:
+            if context.state.task_board is None:
+                task_board = TaskBoard(team_id=team_id)
+                context.state.task_board = task_board
+                logger.info(f"Team '{team_id}': TaskBoard initialized and attached to team state.")
+
+                notifier = phase_manager.notifier
+                if notifier:
+                    # The notifier, a long-lived component, subscribes to events
+                    # from the task_board, another long-lived component.
+                    notifier.subscribe_from(sender=task_board, event=EventType.TASK_BOARD_PLAN_PUBLISHED, listener=notifier.handle_and_publish_task_board_event)
+                    notifier.subscribe_from(sender=task_board, event=EventType.TASK_BOARD_STATUS_UPDATED, listener=notifier.handle_and_publish_task_board_event)
+                    logger.info(f"Team '{team_id}': Successfully bridged TaskBoard events to the team notifier.")
+                else:
+                    logger.warning(f"Team '{team_id}': Notifier not found in PhaseManager. Cannot bridge TaskBoard events.")
+
+            else:
+                logger.warning(f"Team '{team_id}': TaskBoard already exists. Skipping initialization.")
+
+            return True
+        except Exception as e:
+            logger.error(f"Team '{team_id}': Critical failure during team context initialization: {e}", exc_info=True)
+            return False

autobyteus/agent_team/context/__init__.py

@@ -0,0 +1,17 @@
+# file: autobyteus/autobyteus/agent_team/context/__init__.py
+"""
+Components related to the agent team's runtime context, state, and configuration.
+"""
+from autobyteus.agent_team.context.team_manager import TeamManager
+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.team_node_config import TeamNodeConfig
+from autobyteus.agent_team.context.agent_team_runtime_state import AgentTeamRuntimeState
+
+__all__ = [
+    "TeamManager",
+    "AgentTeamConfig",
+    "AgentTeamContext",
+    "TeamNodeConfig",
+    "AgentTeamRuntimeState",
+]

autobyteus/agent_team/context/agent_team_config.py

@@ -0,0 +1,33 @@
+# file: autobyteus/autobyteus/agent_team/context/agent_team_config.py
+import logging
+from dataclasses import dataclass, field
+from typing import List, Optional, Tuple
+
+from autobyteus.agent_team.context.team_node_config import TeamNodeConfig
+from autobyteus.agent_team.task_notification.task_notification_mode import TaskNotificationMode
+
+logger = logging.getLogger(__name__)
+
+@dataclass(frozen=True)
+class AgentTeamConfig:
+    """
+    Represents the complete, static configuration for an AgentTeam instance.
+    This is the user's primary input for defining an agent team.
+    """
+    name: str
+    description: str
+    nodes: Tuple[TeamNodeConfig, ...]
+    coordinator_node: TeamNodeConfig
+    role: Optional[str] = None
+    task_notification_mode: TaskNotificationMode = TaskNotificationMode.AGENT_MANUAL_NOTIFICATION
+
+    def __post_init__(self):
+        if not self.name or not isinstance(self.name, str):
+            raise ValueError("The 'name' in AgentTeamConfig must be a non-empty string.")
+        if not self.nodes:
+            raise ValueError("The 'nodes' collection in AgentTeamConfig cannot be empty.")
+        if self.coordinator_node not in self.nodes:
+            raise ValueError("The 'coordinator_node' must be one of the nodes in the 'nodes' collection.")
+        if not isinstance(self.task_notification_mode, TaskNotificationMode):
+            raise TypeError("The 'task_notification_mode' must be an instance of TaskNotificationMode enum.")
+        logger.debug(f"AgentTeamConfig validated for team: '{self.name}'.")

autobyteus/agent_team/context/agent_team_context.py

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

autobyteus/agent_team/context/agent_team_runtime_state.py

@@ -0,0 +1,56 @@
+# file: autobyteus/autobyteus/agent_team/context/agent_team_runtime_state.py
+import logging
+from typing import List, Optional, TYPE_CHECKING, Dict
+from dataclasses import dataclass, field
+
+from autobyteus.agent_team.phases.agent_team_operational_phase import AgentTeamOperationalPhase
+from autobyteus.agent.context import AgentConfig
+
+if TYPE_CHECKING:
+    from autobyteus.agent.agent import Agent
+    from autobyteus.agent_team.events.agent_team_input_event_queue_manager import AgentTeamInputEventQueueManager
+    from autobyteus.agent_team.phases.agent_team_phase_manager import AgentTeamPhaseManager
+    from autobyteus.agent_team.context.team_node_config import TeamNodeConfig
+    from autobyteus.agent_team.context.team_manager import TeamManager
+    from autobyteus.agent_team.streaming.agent_event_multiplexer import AgentEventMultiplexer
+    from autobyteus.task_management.base_task_board import BaseTaskBoard
+    from autobyteus.task_management.artifacts.artifact_manifest import ArtifactManifest
+    from autobyteus.agent_team.task_notification.system_event_driven_agent_task_notifier import SystemEventDrivenAgentTaskNotifier
+
+logger = logging.getLogger(__name__)
+
+@dataclass
+class AgentTeamRuntimeState:
+    """Encapsulates the dynamic, stateful data of a running agent team instance."""
+    team_id: str
+    current_phase: AgentTeamOperationalPhase = AgentTeamOperationalPhase.UNINITIALIZED
+    
+    # State populated by bootstrap steps
+    prepared_coordinator_prompt: Optional[str] = None
+    final_agent_configs: Dict[str, 'AgentConfig'] = field(default_factory=dict)
+
+    # Core services
+    team_manager: Optional['TeamManager'] = None
+    task_notifier: Optional['SystemEventDrivenAgentTaskNotifier'] = None
+
+    # Runtime components and references
+    input_event_queues: Optional['AgentTeamInputEventQueueManager'] = None
+    phase_manager_ref: Optional['AgentTeamPhaseManager'] = None
+    multiplexer_ref: Optional['AgentEventMultiplexer'] = None
+    
+    # Dynamic planning and artifact state
+    task_board: Optional['BaseTaskBoard'] = None
+    artifact_registry: Dict[str, 'ArtifactManifest'] = field(default_factory=dict)
+
+    def __post_init__(self):
+        if not self.team_id or not isinstance(self.team_id, str):
+            raise ValueError("AgentTeamRuntimeState requires a non-empty string 'team_id'.")
+        logger.info(f"AgentTeamRuntimeState initialized for team_id '{self.team_id}'.")
+
+    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"<AgentTeamRuntimeState id='{self.team_id}', phase='{self.current_phase.value}', "
+                f"agents_count={agents_count}, coordinator_set={coordinator_set}, "
+                f"final_configs_count={len(self.final_agent_configs)}, "
+                f"team_manager_set={self.team_manager is not None}>")

autobyteus/agent_team/context/team_manager.py

@@ -0,0 +1,147 @@
+# file: autobyteus/autobyteus/agent_team/context/team_manager.py
+import asyncio
+import logging
+from typing import List, Dict, Optional, TYPE_CHECKING, Union
+
+from autobyteus.agent.factory import AgentFactory
+from autobyteus.agent.utils.wait_for_idle import wait_for_agent_to_be_idle
+from autobyteus.agent_team.utils.wait_for_idle import wait_for_team_to_be_idle
+from autobyteus.agent_team.exceptions import TeamNodeNotFoundException
+
+if TYPE_CHECKING:
+    from autobyteus.agent.agent import Agent
+    from autobyteus.agent_team.agent_team import AgentTeam
+    from autobyteus.agent_team.events.agent_team_events import InterAgentMessageRequestEvent, ProcessUserMessageEvent
+    from autobyteus.agent_team.runtime.agent_team_runtime import AgentTeamRuntime
+    from autobyteus.agent_team.streaming.agent_event_multiplexer import AgentEventMultiplexer
+    from autobyteus.agent_team.context.agent_team_config import AgentTeamConfig
+
+ManagedNode = Union['Agent', 'AgentTeam']
+
+logger = logging.getLogger(__name__)
+
+class TeamManager:
+    """
+    Manages all nodes (agents and sub-teams) within an agent team. It handles
+    lazy creation, on-demand startup, and provides access to managed instances.
+    It assumes all node names are unique within the team.
+    """
+    def __init__(self, team_id: str, runtime: 'AgentTeamRuntime', multiplexer: 'AgentEventMultiplexer'):
+        self.team_id = team_id
+        self._runtime = runtime
+        self._multiplexer = multiplexer
+        self._agent_factory = AgentFactory()
+        self._nodes_cache: Dict[str, ManagedNode] = {}
+        self._agent_id_to_name_map: Dict[str, str] = {}
+        self._coordinator_agent: Optional['Agent'] = None
+        logger.info(f"TeamManager created for team '{self.team_id}'.")
+
+    async def dispatch_inter_agent_message_request(self, event: 'InterAgentMessageRequestEvent'):
+        await self._runtime.submit_event(event)
+
+    async def dispatch_user_message_to_agent(self, event: 'ProcessUserMessageEvent'):
+        """Submits a user message event (potentially system-generated) to the team's runtime."""
+        await self._runtime.submit_event(event)
+
+    async def ensure_node_is_ready(self, name_or_agent_id: str) -> ManagedNode:
+        """
+        Retrieves a node by its unique name or ID. If not yet created, it
+        instantiates and starts it on-demand.
+        """
+        unique_name: str
+        if name_or_agent_id in self._agent_id_to_name_map:
+            unique_name = self._agent_id_to_name_map[name_or_agent_id]
+        else:
+            unique_name = name_or_agent_id
+            
+        node_instance = self._nodes_cache.get(unique_name)
+        
+        was_created = False
+        if not node_instance:
+            logger.debug(f"Node '{unique_name}' not in cache for team '{self.team_id}'. Attempting lazy creation.")
+            
+            node_config_wrapper = self._runtime.context.get_node_config_by_name(unique_name)
+            if not node_config_wrapper:
+                raise TeamNodeNotFoundException(node_name=name_or_agent_id, team_id=self.team_id)
+
+            if node_config_wrapper.is_sub_team:
+                from autobyteus.agent_team.factory.agent_team_factory import AgentTeamFactory
+                from autobyteus.agent_team.context.agent_team_config import AgentTeamConfig
+                
+                team_factory = AgentTeamFactory()
+                node_definition = node_config_wrapper.node_definition
+                if not isinstance(node_definition, AgentTeamConfig):
+                     raise TypeError(f"Expected AgentTeamConfig for node '{unique_name}', but found {type(node_definition)}")
+                logger.info(f"Lazily creating sub-team node '{unique_name}' in team '{self.team_id}'.")
+                node_instance = team_factory.create_team(config=node_definition)
+            else:
+                # Agent creation is now simpler: just retrieve the pre-made config.
+                final_config = self._runtime.context.state.final_agent_configs.get(unique_name)
+                if not final_config:
+                    raise RuntimeError(f"No pre-prepared agent configuration found for '{unique_name}'. "
+                                     "Bootstrap step may have failed or skipped this agent.")
+                
+                logger.info(f"Lazily creating agent node '{unique_name}' using pre-prepared configuration.")
+                node_instance = self._agent_factory.create_agent(config=final_config)
+            
+            self._nodes_cache[unique_name] = node_instance
+            was_created = True
+
+            from autobyteus.agent.agent import Agent
+            if isinstance(node_instance, Agent):
+                self._agent_id_to_name_map[node_instance.agent_id] = unique_name
+
+
+        if was_created and node_instance:
+            from autobyteus.agent_team.agent_team import AgentTeam
+            from autobyteus.agent.agent import Agent
+            if isinstance(node_instance, AgentTeam):
+                self._multiplexer.start_bridging_team_events(node_instance, unique_name)
+            elif isinstance(node_instance, Agent):
+                self._multiplexer.start_bridging_agent_events(node_instance, unique_name)
+
+        # On-Demand Startup Logic
+        if not node_instance.is_running:
+            from autobyteus.agent_team.agent_team import AgentTeam
+            logger.info(f"Team '{self.team_id}': Node '{unique_name}' is not running. Starting on-demand.")
+            await self._start_node(node_instance, unique_name)
+        
+        return node_instance
+
+    async def _start_node(self, node: ManagedNode, name: str):
+        """Starts a node and waits for it to be idle."""
+        try:
+            node.start()
+            from autobyteus.agent_team.agent_team import AgentTeam
+            if isinstance(node, AgentTeam):
+                await wait_for_team_to_be_idle(node, timeout=120.0)
+            else:
+                await wait_for_agent_to_be_idle(node, timeout=60.0)
+        except Exception as e:
+            logger.error(f"Team '{self.team_id}': Failed to start node '{name}' on-demand: {e}", exc_info=True)
+            raise RuntimeError(f"Failed to start node '{name}' on-demand.") from e
+
+    def get_all_agents(self) -> List['Agent']:
+        from autobyteus.agent.agent import Agent
+        return [node for node in self._nodes_cache.values() if isinstance(node, Agent)]
+
+    def get_all_sub_teams(self) -> List['AgentTeam']:
+        from autobyteus.agent_team.agent_team import AgentTeam
+        return [node for node in self._nodes_cache.values() if isinstance(node, AgentTeam)]
+
+    @property
+    def coordinator_agent(self) -> Optional['Agent']:
+        return self._coordinator_agent
+
+    async def ensure_coordinator_is_ready(self, coordinator_name: str) -> 'Agent':
+        """
+        Ensures the coordinator agent is created, started, and ready, then
+        designates it as the coordinator.
+        """
+        from autobyteus.agent.agent import Agent
+        node = await self.ensure_node_is_ready(name_or_agent_id=coordinator_name)
+        if not isinstance(node, Agent):
+            raise TypeError(f"Coordinator node '{coordinator_name}' resolved to a non-agent type: {type(node).__name__}")
+
+        self._coordinator_agent = node
+        return node

autobyteus/agent_team/context/team_node_config.py

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

autobyteus/agent_team/events/__init__.py

@@ -0,0 +1,29 @@
+# file: autobyteus/autobyteus/agent_team/events/__init__.py
+"""
+This package contains event definitions and dispatchers for the agent team runtime.
+"""
+from autobyteus.agent_team.events.agent_team_events import (
+    BaseAgentTeamEvent,
+    LifecycleAgentTeamEvent,
+    OperationalAgentTeamEvent,
+    AgentTeamReadyEvent,
+    AgentTeamErrorEvent,
+    ProcessUserMessageEvent,
+    InterAgentMessageRequestEvent,
+    ToolApprovalTeamEvent,
+)
+from autobyteus.agent_team.events.agent_team_event_dispatcher import AgentTeamEventDispatcher
+from autobyteus.agent_team.events.agent_team_input_event_queue_manager import AgentTeamInputEventQueueManager
+
+__all__ = [
+    "BaseAgentTeamEvent",
+    "LifecycleAgentTeamEvent",
+    "OperationalAgentTeamEvent",
+    "AgentTeamReadyEvent",
+    "AgentTeamErrorEvent",
+    "ProcessUserMessageEvent",
+    "InterAgentMessageRequestEvent",
+    "ToolApprovalTeamEvent",
+    "AgentTeamEventDispatcher",
+    "AgentTeamInputEventQueueManager",
+]

autobyteus/agent_team/events/agent_team_event_dispatcher.py

@@ -0,0 +1,39 @@
+# file: autobyteus/autobyteus/agent_team/events/agent_team_event_dispatcher.py
+import logging
+import traceback
+from typing import TYPE_CHECKING
+
+from autobyteus.agent_team.events.agent_team_events import BaseAgentTeamEvent, AgentTeamReadyEvent, ProcessUserMessageEvent
+
+if TYPE_CHECKING:
+    from autobyteus.agent_team.context.agent_team_context import AgentTeamContext
+    from autobyteus.agent_team.handlers.agent_team_event_handler_registry import AgentTeamEventHandlerRegistry
+    from autobyteus.agent_team.phases.agent_team_phase_manager import AgentTeamPhaseManager
+
+logger = logging.getLogger(__name__)
+
+class AgentTeamEventDispatcher:
+    """Dispatches agent team events to their appropriate handlers."""
+
+    def __init__(self,
+                 event_handler_registry: 'AgentTeamEventHandlerRegistry',
+                 phase_manager: 'AgentTeamPhaseManager'):
+        self.registry = event_handler_registry
+        self.phase_manager = phase_manager
+
+    async def dispatch(self, event: BaseAgentTeamEvent, context: 'AgentTeamContext'):
+        handler = self.registry.get_handler(type(event))
+        team_id = context.team_id
+
+        if not handler:
+            logger.warning(f"Team '{team_id}': No handler for event '{type(event).__name__}'.")
+            return
+
+        try:
+            await handler.handle(event, context)
+            if isinstance(event, AgentTeamReadyEvent):
+                await self.phase_manager.notify_initialization_complete()
+        except Exception as e:
+            error_msg = f"Error handling '{type(event).__name__}' in team '{team_id}': {e}"
+            logger.error(error_msg, exc_info=True)
+            await self.phase_manager.notify_error_occurred(error_msg, traceback.format_exc())