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

autobyteus/agent_team/shutdown_steps/__init__.py

@@ -0,0 +1,17 @@
+# file: autobyteus/autobyteus/agent_team/shutdown_steps/__init__.py
+"""
+Defines individual, self-contained steps for the agent team shutdown process.
+"""
+from autobyteus.agent_team.shutdown_steps.base_agent_team_shutdown_step import BaseAgentTeamShutdownStep
+from autobyteus.agent_team.shutdown_steps.agent_team_shutdown_step import AgentTeamShutdownStep
+from autobyteus.agent_team.shutdown_steps.sub_team_shutdown_step import SubTeamShutdownStep
+from autobyteus.agent_team.shutdown_steps.bridge_cleanup_step import BridgeCleanupStep
+from autobyteus.agent_team.shutdown_steps.agent_team_shutdown_orchestrator import AgentTeamShutdownOrchestrator
+
+__all__ = [
+    "BaseAgentTeamShutdownStep",
+    "AgentTeamShutdownStep",
+    "SubTeamShutdownStep",
+    "BridgeCleanupStep",
+    "AgentTeamShutdownOrchestrator",
+]

autobyteus/agent_team/shutdown_steps/agent_team_shutdown_orchestrator.py

@@ -0,0 +1,35 @@
+# file: autobyteus/autobyteus/agent_team/shutdown_steps/agent_team_shutdown_orchestrator.py
+import logging
+from typing import TYPE_CHECKING, List, Optional
+
+from autobyteus.agent_team.shutdown_steps.base_agent_team_shutdown_step import BaseAgentTeamShutdownStep
+from autobyteus.agent_team.shutdown_steps.bridge_cleanup_step import BridgeCleanupStep
+from autobyteus.agent_team.shutdown_steps.sub_team_shutdown_step import SubTeamShutdownStep
+from autobyteus.agent_team.shutdown_steps.agent_team_shutdown_step import AgentTeamShutdownStep
+
+if TYPE_CHECKING:
+    from autobyteus.agent_team.context.agent_team_context import AgentTeamContext
+
+logger = logging.getLogger(__name__)
+
+class AgentTeamShutdownOrchestrator:
+    """Orchestrates the agent team's shutdown process."""
+    def __init__(self, steps: Optional[List[BaseAgentTeamShutdownStep]] = None):
+        self.shutdown_steps = steps or [
+            BridgeCleanupStep(),
+            SubTeamShutdownStep(),
+            AgentTeamShutdownStep(),
+        ]
+
+    async def run(self, context: 'AgentTeamContext') -> bool:
+        team_id = context.team_id
+        logger.info(f"Team '{team_id}': Shutdown orchestrator starting.")
+        
+        all_successful = True
+        for step in self.shutdown_steps:
+            if not await step.execute(context):
+                logger.error(f"Team '{team_id}': Shutdown step {step.__class__.__name__} failed.")
+                all_successful = False
+        
+        logger.info(f"Team '{team_id}': Shutdown orchestration completed.")
+        return all_successful

autobyteus/agent_team/shutdown_steps/agent_team_shutdown_step.py

@@ -0,0 +1,42 @@
+# file: autobyteus/autobyteus/agent_team/shutdown_steps/agent_team_shutdown_step.py
+import asyncio
+import logging
+from typing import TYPE_CHECKING
+
+from autobyteus.agent_team.shutdown_steps.base_agent_team_shutdown_step import BaseAgentTeamShutdownStep
+
+if TYPE_CHECKING:
+    from autobyteus.agent_team.context.agent_team_context import AgentTeamContext
+
+logger = logging.getLogger(__name__)
+
+class AgentTeamShutdownStep(BaseAgentTeamShutdownStep):
+    """Shutdown step to gracefully stop all running agents in the team."""
+    async def execute(self, context: 'AgentTeamContext') -> bool:
+        team_id = context.team_id
+        logger.info(f"Team '{team_id}': Executing AgentTeamShutdownStep.")
+        
+        team_manager = context.team_manager
+        if not team_manager:
+            logger.warning(f"Team '{team_id}': No TeamManager found, cannot shut down agents.")
+            return True
+
+        # Get the list of all created agents from the single source of truth.
+        all_agents = team_manager.get_all_agents()
+        running_agents = [agent for agent in all_agents if agent.is_running]
+        
+        if not running_agents:
+            logger.info(f"Team '{team_id}': No running agents to shut down.")
+            return True
+        
+        logger.info(f"Team '{team_id}': Shutting down {len(running_agents)} running agents.")
+        stop_tasks = [agent.stop(timeout=10.0) for agent in running_agents]
+        results = await asyncio.gather(*stop_tasks, return_exceptions=True)
+        
+        all_successful = True
+        for agent, result in zip(running_agents, results):
+            if isinstance(result, Exception):
+                logger.error(f"Team '{team_id}': Error stopping agent '{agent.agent_id}': {result}", exc_info=result)
+                all_successful = False
+        
+        return all_successful

autobyteus/agent_team/shutdown_steps/base_agent_team_shutdown_step.py

@@ -0,0 +1,16 @@
+# file: autobyteus/autobyteus/agent_team/shutdown_steps/base_agent_team_shutdown_step.py
+import logging
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from autobyteus.agent_team.context.agent_team_context import AgentTeamContext
+
+logger = logging.getLogger(__name__)
+
+class BaseAgentTeamShutdownStep(ABC):
+    """Abstract base class for individual steps in the agent team shutdown process."""
+    @abstractmethod
+    async def execute(self, context: 'AgentTeamContext') -> bool:
+        """Executes the shutdown step."""
+        raise NotImplementedError("Subclasses must implement the 'execute' method.")

autobyteus/agent_team/shutdown_steps/bridge_cleanup_step.py

@@ -0,0 +1,28 @@
+# file: autobyteus/autobyteus/agent_team/shutdown_steps/bridge_cleanup_step.py
+import logging
+from typing import TYPE_CHECKING
+
+from autobyteus.agent_team.shutdown_steps.base_agent_team_shutdown_step import BaseAgentTeamShutdownStep
+
+if TYPE_CHECKING:
+    from autobyteus.agent_team.context.agent_team_context import AgentTeamContext
+
+logger = logging.getLogger(__name__)
+
+class BridgeCleanupStep(BaseAgentTeamShutdownStep):
+    """Shutdown step to gracefully stop all AgentEventBridge instances via the multiplexer."""
+    async def execute(self, context: 'AgentTeamContext') -> bool:
+        team_id = context.team_id
+        logger.info(f"Team '{team_id}': Executing BridgeCleanupStep.")
+        
+        multiplexer = context.multiplexer
+        if not multiplexer:
+            logger.warning(f"Team '{team_id}': No AgentEventMultiplexer found, cannot shut down event bridges.")
+            return True
+
+        try:
+            await multiplexer.shutdown()
+            return True
+        except Exception as e:
+            logger.error(f"Team '{team_id}': Error shutting down agent event bridges via multiplexer: {e}", exc_info=True)
+            return False

autobyteus/agent_team/shutdown_steps/sub_team_shutdown_step.py

@@ -0,0 +1,41 @@
+# file: autobyteus/autobyteus/agent_team/shutdown_steps/sub_team_shutdown_step.py
+import asyncio
+import logging
+from typing import TYPE_CHECKING
+
+from autobyteus.agent_team.shutdown_steps.base_agent_team_shutdown_step import BaseAgentTeamShutdownStep
+
+if TYPE_CHECKING:
+    from autobyteus.agent_team.context.agent_team_context import AgentTeamContext
+
+logger = logging.getLogger(__name__)
+
+class SubTeamShutdownStep(BaseAgentTeamShutdownStep):
+    """Shutdown step to gracefully stop all running sub-teams."""
+    async def execute(self, context: 'AgentTeamContext') -> bool:
+        team_id = context.team_id
+        logger.info(f"Team '{team_id}': Executing SubTeamShutdownStep.")
+        
+        team_manager = context.team_manager
+        if not team_manager:
+            logger.warning(f"Team '{team_id}': No TeamManager found, cannot shut down sub-teams.")
+            return True
+
+        all_sub_teams = team_manager.get_all_sub_teams()
+        running_sub_teams = [wf for wf in all_sub_teams if wf.is_running]
+        
+        if not running_sub_teams:
+            logger.info(f"Team '{team_id}': No running sub-teams to shut down.")
+            return True
+        
+        logger.info(f"Team '{team_id}': Shutting down {len(running_sub_teams)} running sub-teams.")
+        stop_tasks = [team.stop(timeout=20.0) for team in running_sub_teams]
+        results = await asyncio.gather(*stop_tasks, return_exceptions=True)
+        
+        all_successful = True
+        for team, result in zip(running_sub_teams, results):
+            if isinstance(result, Exception):
+                logger.error(f"Team '{team_id}': Error stopping sub-team '{team.name}': {result}", exc_info=result)
+                all_successful = False
+        
+        return all_successful

autobyteus/agent_team/streaming/__init__.py

@@ -0,0 +1,26 @@
+# file: autobyteus/autobyteus/agent_team/streaming/__init__.py
+"""
+Components related to agent team output streaming.
+"""
+from .agent_team_event_notifier import AgentTeamExternalEventNotifier
+from .agent_team_event_stream import AgentTeamEventStream
+from .agent_team_stream_events import AgentTeamStreamEvent, AgentTeamStreamDataPayload
+from .agent_team_stream_event_payloads import (
+    BaseTeamSpecificPayload,
+    AgentTeamPhaseTransitionData,
+    AgentEventRebroadcastPayload,
+)
+from .agent_event_bridge import AgentEventBridge
+from .agent_event_multiplexer import AgentEventMultiplexer
+
+__all__ = [
+    "AgentTeamExternalEventNotifier",
+    "AgentTeamEventStream",
+    "AgentTeamStreamEvent",
+    "AgentTeamStreamDataPayload",
+    "BaseTeamSpecificPayload",
+    "AgentTeamPhaseTransitionData",
+    "AgentEventRebroadcastPayload",
+    "AgentEventBridge",
+    "AgentEventMultiplexer",
+]

autobyteus/agent_team/streaming/agent_event_bridge.py

@@ -0,0 +1,48 @@
+# file: autobyteus/autobyteus/agent_team/streaming/agent_event_bridge.py
+import asyncio
+import logging
+from typing import TYPE_CHECKING
+
+from autobyteus.agent.streaming.agent_event_stream import AgentEventStream
+
+if TYPE_CHECKING:
+    from autobyteus.agent.agent import Agent
+    from autobyteus.agent_team.streaming.agent_team_event_notifier import AgentTeamExternalEventNotifier
+
+logger = logging.getLogger(__name__)
+
+class AgentEventBridge:
+    """
+    A dedicated component that bridges events from a single agent's event stream
+    to the main team notifier. This is the core of the multiplexing pattern.
+    """
+    def __init__(self, agent: 'Agent', agent_name: str, notifier: 'AgentTeamExternalEventNotifier', loop: asyncio.AbstractEventLoop):
+        self._agent_name = agent_name
+        self._notifier = notifier
+        self._stream = AgentEventStream(agent)
+        self._task: asyncio.Task = loop.create_task(self._run())
+        logger.info(f"AgentEventBridge created and task started for agent '{agent_name}'.")
+
+    async def _run(self):
+        """The background task that consumes from the stream and publishes to the notifier."""
+        try:
+            async for event in self._stream.all_events():
+                self._notifier.publish_agent_event(self._agent_name, event)
+        except asyncio.CancelledError:
+            logger.info(f"AgentEventBridge task for '{self._agent_name}' was cancelled.")
+        except Exception as e:
+            logger.error(f"Error in AgentEventBridge for '{self._agent_name}': {e}", exc_info=True)
+        finally:
+            logger.debug(f"AgentEventBridge task for '{self._agent_name}' is finishing.")
+
+    async def cancel(self):
+        """Gracefully stops the bridge."""
+        logger.info(f"Cancelling AgentEventBridge for '{self._agent_name}'.")
+        if not self._task.done():
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass # Expected
+        await self._stream.close()
+        logger.info(f"AgentEventBridge for '{self._agent_name}' cancelled successfully.")

autobyteus/agent_team/streaming/agent_event_multiplexer.py

@@ -0,0 +1,70 @@
+# file: autobyteus/autobyteus/agent_team/streaming/agent_event_multiplexer.py
+import asyncio
+import logging
+from typing import TYPE_CHECKING, Dict, Optional
+
+from autobyteus.agent_team.streaming.agent_event_bridge import AgentEventBridge
+from autobyteus.agent_team.streaming.team_event_bridge import TeamEventBridge
+
+if TYPE_CHECKING:
+    from autobyteus.agent.agent import Agent
+    from autobyteus.agent_team.agent_team import AgentTeam
+    from autobyteus.agent_team.streaming.agent_team_event_notifier import AgentTeamExternalEventNotifier
+    from autobyteus.agent_team.runtime.agent_team_worker import AgentTeamWorker
+
+logger = logging.getLogger(__name__)
+
+class AgentEventMultiplexer:
+    """
+    Manages the lifecycle of event bridges for all nodes (agents and sub-teams).
+    It creates, tracks, and shuts down the bridges that forward node events
+    to the agent team's main event stream.
+    """
+    def __init__(self, team_id: str, notifier: 'AgentTeamExternalEventNotifier', worker_ref: 'AgentTeamWorker'):
+        self._team_id = team_id
+        self._notifier = notifier
+        self._worker = worker_ref
+        self._loop: Optional[asyncio.AbstractEventLoop] = None
+        self._agent_bridges: Dict[str, AgentEventBridge] = {}
+        self._team_bridges: Dict[str, TeamEventBridge] = {}
+        logger.info(f"AgentEventMultiplexer initialized for team '{self._team_id}'.")
+
+    def _get_loop(self) -> asyncio.AbstractEventLoop:
+        """Retrieves the event loop from the worker on-demand."""
+        if self._loop is None or self._loop.is_closed():
+            self._loop = self._worker.get_worker_loop()
+            if self._loop is None:
+                raise RuntimeError(f"Agent team worker loop for team '{self._team_id}' is not available or not running.")
+        return self._loop
+
+    def start_bridging_agent_events(self, agent: 'Agent', agent_name: str):
+        """Creates and starts an AgentEventBridge for a direct agent node."""
+        if agent_name in self._agent_bridges:
+            logger.warning(f"Event bridge for agent '{agent_name}' already exists. Skipping creation.")
+            return
+
+        bridge = AgentEventBridge(agent=agent, agent_name=agent_name, notifier=self._notifier, loop=self._get_loop())
+        self._agent_bridges[agent_name] = bridge
+        logger.info(f"AgentEventMultiplexer started agent event bridge for '{agent_name}'.")
+
+    def start_bridging_team_events(self, sub_team: 'AgentTeam', node_name: str):
+        """Creates and starts a TeamEventBridge for a sub-team node."""
+        if node_name in self._team_bridges:
+            logger.warning(f"Event bridge for sub-team '{node_name}' already exists. Skipping creation.")
+            return
+            
+        bridge = TeamEventBridge(sub_team=sub_team, sub_team_node_name=node_name, parent_notifier=self._notifier, loop=self._get_loop())
+        self._team_bridges[node_name] = bridge
+        logger.info(f"AgentEventMultiplexer started team event bridge for '{node_name}'.")
+
+    async def shutdown(self):
+        """Gracefully shuts down all active event bridges."""
+        logger.info(f"AgentEventMultiplexer for '{self._team_id}' shutting down all event bridges.")
+        agent_bridge_tasks = [b.cancel() for b in self._agent_bridges.values()]
+        team_bridge_tasks = [b.cancel() for b in self._team_bridges.values()]
+        
+        await asyncio.gather(*(agent_bridge_tasks + team_bridge_tasks), return_exceptions=True)
+        
+        self._agent_bridges.clear()
+        self._team_bridges.clear()
+        logger.info(f"All event bridges for team '{self._team_id}' have been shut down by multiplexer.")

autobyteus/agent_team/streaming/agent_team_event_notifier.py

@@ -0,0 +1,64 @@
+# file: autobyteus/autobyteus/agent_team/streaming/agent_team_event_notifier.py
+import logging
+from typing import Optional, Dict, Any, TYPE_CHECKING
+
+from autobyteus.events.event_emitter import EventEmitter
+from autobyteus.events.event_types import EventType
+from autobyteus.agent_team.phases.agent_team_operational_phase import AgentTeamOperationalPhase
+from autobyteus.agent.streaming.stream_events import StreamEvent as AgentStreamEvent
+from .agent_team_stream_events import AgentTeamStreamEvent, AgentEventRebroadcastPayload, AgentTeamPhaseTransitionData, SubTeamEventRebroadcastPayload
+from autobyteus.task_management.events import BaseTaskBoardEvent
+
+if TYPE_CHECKING:
+    from autobyteus.agent_team.runtime.agent_team_runtime import AgentTeamRuntime
+    from autobyteus.agent_team.streaming.agent_team_stream_events import AgentTeamStreamEvent as AgentTeamStreamEventTypeHint
+
+logger = logging.getLogger(__name__)
+
+class AgentTeamExternalEventNotifier(EventEmitter):
+    """
+    Responsible for emitting unified AgentTeamStreamEvents for consumption by
+    external listeners (like a UI or the AgentTeamEventStream).
+    """
+    def __init__(self, team_id: str, runtime_ref: 'AgentTeamRuntime'):
+        super().__init__()
+        self.team_id = team_id
+        self.runtime_ref = runtime_ref
+        logger.debug(f"AgentTeamExternalEventNotifier initialized for team '{self.team_id}'.")
+
+    def _emit_event(self, event: 'AgentTeamStreamEventTypeHint'):
+        """
+        Emits a fully-formed AgentTeamStreamEvent.
+        """
+        self.emit(EventType.TEAM_STREAM_EVENT, payload=event)
+
+    def notify_phase_change(self, new_phase: AgentTeamOperationalPhase, old_phase: Optional[AgentTeamOperationalPhase], extra_data: Optional[Dict[str, Any]] = None):
+        """
+        Notifies of an agent team phase transition by creating and emitting a
+        'TEAM' sourced event.
+        """
+        payload_dict = { "new_phase": new_phase, "old_phase": old_phase, "error_message": extra_data.get("error_message") if extra_data else None }
+        filtered_payload_dict = {k: v for k, v in payload_dict.items() if v is not None}
+        event = AgentTeamStreamEvent(team_id=self.team_id, event_source_type="TEAM", data=AgentTeamPhaseTransitionData(**filtered_payload_dict))
+        self._emit_event(event)
+    
+    def publish_agent_event(self, agent_name: str, agent_event: AgentStreamEvent):
+        """
+        Wraps an event from a direct member agent and publishes it on the main team stream.
+        """
+        event = AgentTeamStreamEvent(team_id=self.team_id, event_source_type="AGENT", data=AgentEventRebroadcastPayload(agent_name=agent_name, agent_event=agent_event))
+        self._emit_event(event)
+        
+    def publish_sub_team_event(self, sub_team_node_name: str, sub_team_event: 'AgentTeamStreamEventTypeHint'):
+        """
+        Wraps an event from a sub-team and publishes it on the parent team stream.
+        """
+        event = AgentTeamStreamEvent(team_id=self.team_id, event_source_type="SUB_TEAM", data=SubTeamEventRebroadcastPayload(sub_team_node_name=sub_team_node_name, sub_team_event=sub_team_event))
+        self._emit_event(event)
+
+    def handle_and_publish_task_board_event(self, payload: BaseTaskBoardEvent, **kwargs):
+        """
+        Listener for TaskBoard events. It wraps the event and publishes it on the main team stream.
+        """
+        event = AgentTeamStreamEvent(team_id=self.team_id, event_source_type="TASK_BOARD", data=payload)
+        self._emit_event(event)

autobyteus/agent_team/streaming/agent_team_event_stream.py

@@ -0,0 +1,33 @@
+# file: autobyteus/autobyteus/agent_team/streaming/agent_team_event_stream.py
+import asyncio
+import queue
+from typing import AsyncIterator, TYPE_CHECKING
+
+from autobyteus.events.event_types import EventType
+from autobyteus.agent_team.streaming.agent_team_stream_events import AgentTeamStreamEvent
+from autobyteus.agent.streaming.queue_streamer import stream_queue_items
+
+if TYPE_CHECKING:
+    from autobyteus.agent_team.agent_team import AgentTeam
+
+_SENTINEL = object()
+
+class AgentTeamEventStream:
+    """Consumes events from an AgentTeamExternalEventNotifier for a specific team."""
+    def __init__(self, team: 'AgentTeam'):
+        self.team_id = team.team_id
+        self._internal_q = queue.Queue()
+        self._notifier = team._runtime.notifier
+        self._notifier.subscribe(EventType.TEAM_STREAM_EVENT, self._handle_event)
+
+    def _handle_event(self, payload: AgentTeamStreamEvent, **kwargs):
+        if isinstance(payload, AgentTeamStreamEvent) and payload.team_id == self.team_id:
+            self._internal_q.put(payload)
+
+    async def close(self):
+        self._notifier.unsubscribe(EventType.TEAM_STREAM_EVENT, self._handle_event)
+        await asyncio.get_running_loop().run_in_executor(None, self._internal_q.put, _SENTINEL)
+
+    def all_events(self) -> AsyncIterator[AgentTeamStreamEvent]:
+        """The primary method to consume all structured events from the agent team."""
+        return stream_queue_items(self._internal_q, _SENTINEL, f"team_{self.team_id}_stream")

autobyteus/agent_team/streaming/agent_team_stream_event_payloads.py

@@ -0,0 +1,32 @@
+# file: autobyteus/autobyteus/agent_team/streaming/agent_team_stream_event_payloads.py
+from typing import Optional, Any
+from pydantic import BaseModel, Field
+from autobyteus.agent_team.phases.agent_team_operational_phase import AgentTeamOperationalPhase
+from autobyteus.agent.streaming.stream_events import StreamEvent as AgentStreamEvent
+from autobyteus.task_management.events import TaskPlanPublishedEvent, TaskStatusUpdatedEvent
+# Need to use a forward reference string to avoid circular import at runtime
+from typing import TYPE_CHECKING, Union
+if TYPE_CHECKING:
+    from autobyteus.agent_team.streaming.agent_team_stream_events import AgentTeamStreamEvent
+
+# --- Payloads for events originating from the "TEAM" source ---
+class BaseTeamSpecificPayload(BaseModel):
+    pass
+
+class AgentTeamPhaseTransitionData(BaseTeamSpecificPayload):
+    new_phase: AgentTeamOperationalPhase
+    old_phase: Optional[AgentTeamOperationalPhase] = None
+    error_message: Optional[str] = None
+
+# --- Payload for events originating from the "AGENT" source ---
+class AgentEventRebroadcastPayload(BaseModel):
+    agent_name: str # The friendly name, e.g., "Researcher_1"
+    agent_event: AgentStreamEvent # The original, unmodified event from the agent
+
+# --- Payload for events originating from the "SUB_TEAM" source ---
+class SubTeamEventRebroadcastPayload(BaseModel):
+    sub_team_node_name: str # The friendly name of the sub-team node
+    sub_team_event: "AgentTeamStreamEvent" = Field(..., description="The original, unmodified event from the sub-team's stream")
+
+# --- Payload for events originating from the "TASK_BOARD" source ---
+TaskBoardEventPayload = Union[TaskPlanPublishedEvent, TaskStatusUpdatedEvent]

autobyteus/agent_team/streaming/agent_team_stream_events.py

@@ -0,0 +1,56 @@
+# file: autobyteus/autobyteus/agent_team/streaming/agent_team_stream_events.py
+import datetime
+import uuid
+from typing import Literal, Union
+from pydantic import BaseModel, Field, model_validator
+
+from .agent_team_stream_event_payloads import (
+    AgentTeamPhaseTransitionData, AgentEventRebroadcastPayload, 
+    SubTeamEventRebroadcastPayload, TaskBoardEventPayload
+)
+from autobyteus.task_management.events import BaseTaskBoardEvent
+
+# A union of all possible payloads for a "TEAM" sourced event.
+TeamSpecificPayload = Union[AgentTeamPhaseTransitionData]
+
+# The top-level discriminated union for the main event stream's payload.
+AgentTeamStreamDataPayload = Union[TeamSpecificPayload, AgentEventRebroadcastPayload, SubTeamEventRebroadcastPayload, TaskBoardEventPayload]
+
+class AgentTeamStreamEvent(BaseModel):
+    event_id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    timestamp: datetime.datetime = Field(default_factory=datetime.datetime.utcnow)
+    team_id: str
+    event_source_type: Literal["TEAM", "AGENT", "SUB_TEAM", "TASK_BOARD"]
+    data: AgentTeamStreamDataPayload
+
+    @model_validator(mode='after')
+    def check_data_matches_source_type(self) -> 'AgentTeamStreamEvent':
+        is_agent_event = self.event_source_type == "AGENT"
+        is_agent_payload = isinstance(self.data, AgentEventRebroadcastPayload)
+
+        is_sub_team_event = self.event_source_type == "SUB_TEAM"
+        is_sub_team_payload = isinstance(self.data, SubTeamEventRebroadcastPayload)
+
+        is_team_event = self.event_source_type == "TEAM"
+        is_team_payload = isinstance(self.data, AgentTeamPhaseTransitionData)
+        
+        is_task_board_event = self.event_source_type == "TASK_BOARD"
+        is_task_board_payload = isinstance(self.data, BaseTaskBoardEvent)
+
+        if is_agent_event and not is_agent_payload:
+            raise ValueError("event_source_type is 'AGENT' but data is not an AgentEventRebroadcastPayload")
+        
+        if is_sub_team_event and not is_sub_team_payload:
+            raise ValueError("event_source_type is 'SUB_TEAM' but data is not a SubTeamEventRebroadcastPayload")
+        
+        if is_team_event and not is_team_payload:
+            raise ValueError("event_source_type is 'TEAM' but data is not a valid team-specific payload")
+
+        if is_task_board_event and not is_task_board_payload:
+            raise ValueError("event_source_type is 'TASK_BOARD' but data is not a TaskBoardEventPayload")
+
+        return self
+
+# This is necessary for Pydantic v2 to correctly handle the recursive model
+from .agent_team_stream_event_payloads import SubTeamEventRebroadcastPayload
+SubTeamEventRebroadcastPayload.model_rebuild()

autobyteus/agent_team/streaming/team_event_bridge.py

@@ -0,0 +1,50 @@
+# file: autobyteus/autobyteus/agent_team/streaming/team_event_bridge.py
+import asyncio
+import logging
+from typing import TYPE_CHECKING
+
+from autobyteus.agent_team.streaming.agent_team_event_stream import AgentTeamEventStream
+
+if TYPE_CHECKING:
+    from autobyteus.agent_team.agent_team import AgentTeam
+    from autobyteus.agent_team.streaming.agent_team_event_notifier import AgentTeamExternalEventNotifier
+
+logger = logging.getLogger(__name__)
+
+class TeamEventBridge:
+    """
+    A dedicated component that bridges events from a sub-team's event stream
+    to the parent team's notifier.
+    """
+    def __init__(self, sub_team: 'AgentTeam', sub_team_node_name: str, parent_notifier: 'AgentTeamExternalEventNotifier', loop: asyncio.AbstractEventLoop):
+        self._sub_team = sub_team
+        self._sub_team_node_name = sub_team_node_name
+        self._parent_notifier = parent_notifier
+        self._stream = AgentTeamEventStream(sub_team)
+        self._task: asyncio.Task = loop.create_task(self._run())
+        logger.info(f"TeamEventBridge created and task started for sub-team '{sub_team_node_name}'.")
+
+    async def _run(self):
+        """The background task that consumes from the sub-team stream and re-publishes."""
+        try:
+            async for event in self._stream.all_events():
+                # Re-broadcast the event to the parent, adding the sub-team context.
+                self._parent_notifier.publish_sub_team_event(self._sub_team_node_name, event)
+        except asyncio.CancelledError:
+            logger.info(f"TeamEventBridge task for '{self._sub_team_node_name}' was cancelled.")
+        except Exception as e:
+            logger.error(f"Error in TeamEventBridge for '{self._sub_team_node_name}': {e}", exc_info=True)
+        finally:
+            logger.debug(f"TeamEventBridge task for '{self._sub_team_node_name}' is finishing.")
+
+    async def cancel(self):
+        """Gracefully stops the bridge."""
+        logger.info(f"Cancelling TeamEventBridge for '{self._sub_team_node_name}'.")
+        if not self._task.done():
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass # Expected
+        await self._stream.close()
+        logger.info(f"TeamEventBridge for '{self._sub_team_node_name}' cancelled successfully.")

autobyteus/agent_team/task_notification/__init__.py

@@ -0,0 +1,11 @@
+# file: autobyteus/autobyteus/agent_team/task_notification/__init__.py
+"""
+This package contains components for automatically notifying agents of runnable tasks.
+"""
+from .system_event_driven_agent_task_notifier import SystemEventDrivenAgentTaskNotifier
+from .task_notification_mode import TaskNotificationMode
+
+__all__ = [
+    "SystemEventDrivenAgentTaskNotifier",
+    "TaskNotificationMode",
+]