autobyteus 1.0.5__py3-none-any.whl → 1.1.0__py3-none-any.whl

autobyteus/agent/runtime/agent_runtime.py

@@ -0,0 +1,139 @@
+# file: autobyteus/autobyteus/agent/runtime/agent_runtime.py
+import asyncio
+import logging
+import traceback 
+import concurrent.futures 
+from typing import Optional, Any, Callable, Awaitable, TYPE_CHECKING 
+
+from autobyteus.agent.context.agent_context import AgentContext 
+from autobyteus.agent.context.phases import AgentOperationalPhase 
+from autobyteus.agent.events.notifiers import AgentExternalEventNotifier 
+from autobyteus.agent.events import BaseEvent
+from autobyteus.agent.context.agent_phase_manager import AgentPhaseManager 
+from autobyteus.agent.handlers import EventHandlerRegistry
+from autobyteus.agent.runtime.agent_worker import AgentWorker
+
+if TYPE_CHECKING:
+    pass
+
+logger = logging.getLogger(__name__)
+
+class AgentRuntime:
+    """
+    The active execution engine for an agent. It creates and manages an AgentWorker.
+    """
+
+    def __init__(self,
+                 context: AgentContext, 
+                 event_handler_registry: EventHandlerRegistry):
+        
+        self.context: AgentContext = context 
+        self.event_handler_registry: EventHandlerRegistry = event_handler_registry
+        
+        self.external_event_notifier: AgentExternalEventNotifier = AgentExternalEventNotifier(agent_id=self.context.agent_id)
+        self.phase_manager: AgentPhaseManager = AgentPhaseManager(context=self.context, notifier=self.external_event_notifier) 
+        
+        self.context.state.phase_manager_ref = self.phase_manager 
+        
+        self._worker: AgentWorker = AgentWorker(
+            context=self.context,
+            event_handler_registry=self.event_handler_registry,
+        )
+        self._worker.add_done_callback(self._handle_worker_completion)
+
+        logger.info(f"AgentRuntime initialized for agent_id '{self.context.agent_id}'.")
+
+    def get_worker_loop(self) -> Optional[asyncio.AbstractEventLoop]:
+        return self._worker.get_worker_loop()
+
+    def _schedule_coroutine_on_worker(self, coro_factory: Callable[[], Awaitable[Any]]) -> concurrent.futures.Future:
+        worker_loop = self._worker.get_worker_loop()
+        if not worker_loop:
+             raise RuntimeError(f"AgentRuntime '{self.context.agent_id}': Worker loop not available.")
+        return self._worker.schedule_coroutine_on_worker_loop(coro_factory)
+
+    async def submit_event(self, event: BaseEvent) -> None: 
+        from autobyteus.agent.events import UserMessageReceivedEvent, InterAgentMessageReceivedEvent, ToolExecutionApprovalEvent
+
+        agent_id = self.context.agent_id
+        if not self._worker or not self._worker.is_alive():
+            raise RuntimeError(f"Agent '{agent_id}' worker is not active.")
+
+        def _coro_factory() -> Awaitable[Any]:
+            async def _enqueue_coro():
+                if not self.context.state.input_event_queues:
+                    logger.critical(f"AgentRuntime '{agent_id}': Input event queues not initialized for event {type(event).__name__}.")
+                    return 
+                
+                if isinstance(event, UserMessageReceivedEvent):
+                    await self.context.state.input_event_queues.enqueue_user_message(event)
+                elif isinstance(event, InterAgentMessageReceivedEvent):
+                    await self.context.state.input_event_queues.enqueue_inter_agent_message(event)
+                elif isinstance(event, ToolExecutionApprovalEvent):
+                    await self.context.state.input_event_queues.enqueue_tool_approval_event(event)
+                else: 
+                    await self.context.state.input_event_queues.enqueue_internal_system_event(event)
+            return _enqueue_coro()
+
+        future = self._schedule_coroutine_on_worker(_coro_factory)
+        await asyncio.wrap_future(future)
+
+    def start(self) -> None: 
+        agent_id = self.context.agent_id
+        if self._worker.is_alive(): 
+            logger.warning(f"AgentRuntime for '{agent_id}' is already running. Ignoring start request.")
+            return
+        
+        logger.info(f"AgentRuntime for '{agent_id}': Starting worker.")
+        # Removed redundant phase notification. The first meaningful phase change to BOOTSTRAPPING
+        # is triggered by the AgentBootstrapper within the worker's async context.
+        # self.phase_manager.notify_runtime_starting_and_uninitialized()
+        self._worker.start() 
+        logger.info(f"AgentRuntime for '{agent_id}': Worker start command issued. Worker will initialize itself.")
+
+    def _handle_worker_completion(self, future: concurrent.futures.Future):
+        agent_id = self.context.agent_id
+        try:
+            future.result() 
+            logger.info(f"AgentRuntime '{agent_id}': Worker thread completed successfully.")
+        except Exception as e:
+            logger.error(f"AgentRuntime '{agent_id}': Worker thread terminated with an exception: {e}", exc_info=True)
+            if not self.context.current_phase.is_terminal():
+                # Since the phase manager is now async, we must run it in a new event loop.
+                try:
+                    asyncio.run(self.phase_manager.notify_error_occurred("Worker thread exited unexpectedly.", traceback.format_exc()))
+                except Exception as run_e:
+                    logger.critical(f"AgentRuntime '{agent_id}': Failed to run async error notification: {run_e}")
+        
+        if not self.context.current_phase.is_terminal():
+             # Use asyncio.run() to execute the final async phase transition from a sync callback.
+             try:
+                 asyncio.run(self.phase_manager.notify_final_shutdown_complete())
+             except Exception as run_e:
+                 logger.critical(f"AgentRuntime '{agent_id}': Failed to run async final shutdown notification: {run_e}")
+        
+    async def stop(self, timeout: float = 10.0) -> None:
+        agent_id = self.context.agent_id
+        if not self._worker.is_alive() and not self._worker._is_active: 
+            if not self.context.current_phase.is_terminal():
+                await self.phase_manager.notify_final_shutdown_complete()
+            return
+        
+        await self.phase_manager.notify_shutdown_initiated() 
+        await self._worker.stop(timeout=timeout) 
+        
+        if self.context.llm_instance and hasattr(self.context.llm_instance, 'cleanup'):
+            cleanup_func = self.context.llm_instance.cleanup
+            if asyncio.iscoroutinefunction(cleanup_func): await cleanup_func()
+            else: cleanup_func()
+        
+        await self.phase_manager.notify_final_shutdown_complete() 
+        logger.info(f"AgentRuntime for '{agent_id}' stop() method completed.")
+
+    @property 
+    def current_phase_property(self) -> AgentOperationalPhase: 
+        return self.context.current_phase 
+        
+    @property
+    def is_running(self) -> bool:
+        return self._worker.is_alive()

autobyteus/agent/runtime/agent_thread_pool_manager.py

@@ -0,0 +1,88 @@
+# file: autobyteus/autobyteus/agent/runtime/agent_thread_pool_manager.py
+import asyncio
+import logging
+import concurrent.futures
+from typing import TYPE_CHECKING, Optional, Callable, Any
+
+from autobyteus.utils.singleton import SingletonMeta 
+
+if TYPE_CHECKING:
+    pass
+
+logger = logging.getLogger(__name__)
+
+class AgentThreadPoolManager(metaclass=SingletonMeta): 
+    """
+    A singleton manager for a shared ThreadPoolExecutor.
+    Used by agent components (like AgentWorker) to submit tasks 
+    that need to run in a separate thread.
+    """
+
+    def __init__(self, max_workers: Optional[int] = None):
+        """
+        Initializes the AgentThreadPoolManager's shared ThreadPoolExecutor.
+        This __init__ will be called only once by SingletonMeta upon first instantiation.
+
+        Args:
+            max_workers: The maximum number of threads in the pool.
+                         Defaults to None (Python's default).
+        """
+        self._thread_pool = concurrent.futures.ThreadPoolExecutor(
+            max_workers=max_workers,
+            thread_name_prefix="AgentThreadPool" 
+        )
+        self._is_shutdown = False 
+        logger.info(f"Singleton AgentThreadPoolManager initialized its ThreadPoolExecutor (max_workers={max_workers or 'default'}).")
+
+    def submit_task(self, func: Callable[..., Any], *args: Any, **kwargs: Any) -> concurrent.futures.Future:
+        """
+        Submits a callable to be executed in the shared thread pool.
+
+        Args:
+            func: The callable to execute.
+            *args: Positional arguments for the callable.
+            **kwargs: Keyword arguments for the callable.
+
+        Returns:
+            A concurrent.futures.Future representing the execution of the callable.
+        
+        Raises:
+            RuntimeError: If the manager is shutdown.
+        """
+        if self._is_shutdown: # pragma: no cover
+            raise RuntimeError("AgentThreadPoolManager is shutdown. Cannot submit new tasks.")
+        
+        func_name = getattr(func, '__name__', repr(func))
+        logger.debug(f"AgentThreadPoolManager submitting task '{func_name}' to thread pool.")
+        
+        future = self._thread_pool.submit(func, *args, **kwargs)
+        return future
+
+    def shutdown(self, wait: bool = True, cancel_futures: bool = False) -> None:
+        """
+        Shuts down the shared thread pool. This should typically be called at application exit.
+
+        Args:
+            wait: If True, wait for all submitted tasks to complete.
+            cancel_futures: If True, attempt to cancel pending futures (Python 3.9+).
+        """
+        if self._is_shutdown: # pragma: no cover
+            logger.info("AgentThreadPoolManager's shared ThreadPoolExecutor already requested to shutdown or is shutdown.")
+            return
+
+        logger.info(f"AgentThreadPoolManager shutting down shared ThreadPoolExecutor (wait={wait}, cancel_futures={cancel_futures})...")
+        self._is_shutdown = True 
+        
+        import inspect
+        sig = inspect.signature(self._thread_pool.shutdown)
+        if 'cancel_futures' in sig.parameters:
+             self._thread_pool.shutdown(wait=wait, cancel_futures=cancel_futures)
+        else: 
+             self._thread_pool.shutdown(wait=wait)
+
+        logger.info("AgentThreadPoolManager shared ThreadPoolExecutor shutdown process complete.")
+
+    def __del__(self): # pragma: no cover
+        if not self._is_shutdown:
+            logger.warning("AgentThreadPoolManager deleted without explicit shutdown. Attempting non-waiting shutdown of thread pool.")
+            self.shutdown(wait=False)

autobyteus/agent/runtime/agent_worker.py

@@ -0,0 +1,200 @@
+# file: autobyteus/autobyteus/agent/runtime/agent_worker.py
+import asyncio
+import logging
+import traceback
+import threading 
+import concurrent.futures
+from typing import TYPE_CHECKING, Optional, Any, Callable, Awaitable, List
+
+from autobyteus.agent.context.phases import AgentOperationalPhase
+from autobyteus.agent.events import ( 
+    BaseEvent,
+    AgentErrorEvent, 
+    AgentStoppedEvent,
+)
+from autobyteus.agent.events import WorkerEventDispatcher
+from autobyteus.agent.runtime.agent_thread_pool_manager import AgentThreadPoolManager 
+from autobyteus.agent.bootstrap_steps.agent_bootstrapper import AgentBootstrapper
+
+if TYPE_CHECKING:
+    from autobyteus.agent.context import AgentContext
+    from autobyteus.agent.handlers import EventHandlerRegistry 
+
+logger = logging.getLogger(__name__)
+
+class AgentWorker:
+    """
+    Encapsulates the core event processing loop for an agent.
+    It manages its own execution in a dedicated thread, runs its own asyncio event loop,
+    and performs its own initialization sequence before processing external events.
+    """
+
+    def __init__(self,
+                 context: 'AgentContext',
+                 event_handler_registry: 'EventHandlerRegistry'): 
+        self.context: 'AgentContext' = context
+        
+        self.phase_manager = self.context.phase_manager
+        if not self.phase_manager: # pragma: no cover
+            raise ValueError(f"AgentWorker for '{self.context.agent_id}': AgentPhaseManager not found.")
+
+        self.worker_event_dispatcher = WorkerEventDispatcher(
+            event_handler_registry=event_handler_registry, 
+            phase_manager=self.phase_manager
+        )
+        
+        self._thread_pool_manager = AgentThreadPoolManager() 
+        self._thread_future: Optional[concurrent.futures.Future] = None
+        self._worker_loop: Optional[asyncio.AbstractEventLoop] = None
+        self._async_stop_event: Optional[asyncio.Event] = None 
+        
+        self._is_active: bool = False 
+        self._stop_initiated: bool = False 
+
+        self._done_callbacks: list[Callable[[concurrent.futures.Future], None]] = []
+
+        logger.info(f"AgentWorker initialized for agent_id '{self.context.agent_id}'.")
+
+    async def _initialize(self) -> bool:
+        """
+        Runs the agent's initialization sequence by using an AgentBootstrapper.
+        Returns True on success, False on failure.
+        """
+        agent_id = self.context.agent_id
+        logger.info(f"Agent '{agent_id}': Starting internal initialization process using AgentBootstrapper.")
+
+        bootstrapper = AgentBootstrapper() # Using default steps
+        initialization_successful = await bootstrapper.run(self.context, self.phase_manager)
+
+        return initialization_successful
+
+    def add_done_callback(self, callback: Callable[[concurrent.futures.Future], None]):
+        """Adds a callback to be executed when the worker's thread completes."""
+        if self._thread_future: 
+            self._thread_future.add_done_callback(callback)
+        else: 
+            self._done_callbacks.append(callback)
+
+    def get_worker_loop(self) -> Optional[asyncio.AbstractEventLoop]:
+        """Returns the worker's event loop if it's running."""
+        return self._worker_loop if self._worker_loop and self._worker_loop.is_running() else None
+
+    def schedule_coroutine_on_worker_loop(self, coro_factory: Callable[[], Awaitable[Any]]) -> concurrent.futures.Future:
+        """Schedules a coroutine to be run on the worker's event loop from other threads."""
+        worker_loop = self.get_worker_loop()
+        if not worker_loop:
+            raise RuntimeError(f"AgentWorker '{self.context.agent_id}': Worker event loop is not available.")
+        return asyncio.run_coroutine_threadsafe(coro_factory(), worker_loop)
+
+    def start(self) -> None:
+        agent_id = self.context.agent_id
+        if self._is_active or (self._thread_future and not self._thread_future.done()):
+            logger.warning(f"AgentWorker '{agent_id}': Start called, but worker is already active or starting.")
+            return
+
+        logger.info(f"AgentWorker '{agent_id}': Starting...")
+        self._is_active = True
+        self._stop_initiated = False
+        self._thread_future = self._thread_pool_manager.submit_task(self._run_managed_thread_loop)
+        for cb in self._done_callbacks: 
+            self._thread_future.add_done_callback(cb)
+        self._done_callbacks.clear() 
+
+    def _run_managed_thread_loop(self) -> None:
+        thread_name = threading.current_thread().name
+        agent_id = self.context.agent_id
+        logger.info(f"AgentWorker '{agent_id}': Thread '{thread_name}' started. Setting up asyncio event loop.")
+        
+        try:
+            self._worker_loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(self._worker_loop)
+            self._async_stop_event = asyncio.Event() 
+            self._worker_loop.run_until_complete(self.async_run())
+        except Exception as e:
+            logger.error(f"AgentWorker '{agent_id}': Unhandled exception in _run_managed_thread_loop: {e}", exc_info=True)
+            if self.phase_manager and not self.context.current_phase.is_terminal():
+                try:
+                    # Since this is a sync context, we must run the async phase manager method in a temporary event loop.
+                    asyncio.run(self.phase_manager.notify_error_occurred(f"Worker thread fatal error: {e}", traceback.format_exc()))
+                except Exception as run_e:
+                    logger.critical(f"AgentWorker '{agent_id}': Failed to run async error notification from sync context: {run_e}")
+        finally:
+            if self._worker_loop:
+                try:
+                    # Gather all remaining tasks and cancel them
+                    tasks = asyncio.all_tasks(loop=self._worker_loop)
+                    for task in tasks:
+                        task.cancel()
+                    
+                    # Wait for all tasks to be cancelled
+                    if tasks:
+                        self._worker_loop.run_until_complete(asyncio.gather(*tasks, return_exceptions=True))
+                    
+                    # Shutdown async generators
+                    self._worker_loop.run_until_complete(self._worker_loop.shutdown_asyncgens())
+                except Exception as cleanup_exc: # pragma: no cover
+                    logger.error(f"AgentWorker '{agent_id}': Exception during event loop cleanup: {cleanup_exc}", exc_info=True)
+                finally:
+                    self._worker_loop.close()
+            self._is_active = False
+
+    async def async_run(self) -> None:
+        agent_id = self.context.agent_id
+        logger.info(f"AgentWorker '{agent_id}' async_run(): Starting.")
+        
+        # --- Direct Initialization ---
+        initialization_successful = await self._initialize()
+        if not initialization_successful:
+            logger.critical(f"AgentWorker '{agent_id}' failed to initialize. Worker is shutting down.")
+            if self._async_stop_event and not self._async_stop_event.is_set():
+                self._async_stop_event.set()
+            return
+        
+        # --- Main Event Loop ---
+        logger.info(f"AgentWorker '{agent_id}' initialized successfully. Entering main event loop.")
+        try:
+            while not self._async_stop_event.is_set(): 
+                try:
+                    queue_event_tuple = await asyncio.wait_for(
+                        self.context.state.input_event_queues.get_next_input_event(), timeout=0.1
+                    )
+                except asyncio.TimeoutError:
+                    if self._async_stop_event.is_set(): break
+                    continue
+                
+                if queue_event_tuple is None:
+                    if self._async_stop_event.is_set(): break
+                    continue
+
+                _queue_name, event_obj = queue_event_tuple
+                await self.worker_event_dispatcher.dispatch(event_obj, self.context)
+                await asyncio.sleep(0) 
+
+        except asyncio.CancelledError:
+            logger.info(f"AgentWorker '{agent_id}' async_run() loop task was cancelled.")
+        except Exception as e:
+            logger.error(f"Fatal error in AgentWorker '{agent_id}' async_run() loop: {e}", exc_info=True)
+        finally:
+            logger.info(f"AgentWorker '{agent_id}' async_run() loop has finished.")
+
+    async def _signal_internal_stop(self):
+        if self._async_stop_event and not self._async_stop_event.is_set():
+            self._async_stop_event.set()
+            if self.context.state.input_event_queues:
+                await self.context.state.input_event_queues.enqueue_internal_system_event(AgentStoppedEvent())
+
+    async def stop(self, timeout: float = 10.0) -> None:
+        if not self._is_active or self._stop_initiated:
+            return
+        self._stop_initiated = True
+        if self.get_worker_loop() and self._async_stop_event:
+            future = asyncio.run_coroutine_threadsafe(self._signal_internal_stop(), self.get_worker_loop())
+            try: future.result(timeout=1.0)
+            except Exception: pass
+        if self._thread_future:
+            try: await asyncio.wait_for(asyncio.wrap_future(self._thread_future), timeout=timeout)
+            except asyncio.TimeoutError: logger.warning(f"Timeout waiting for worker thread of '{self.context.agent_id}'.")
+        self._is_active = False
+
+    def is_alive(self) -> bool:
+        return self._thread_future is not None and not self._thread_future.done()

autobyteus/agent/streaming/__init__.py

@@ -0,0 +1,15 @@
+# file: autobyteus/autobyteus/agent/streaming/__init__.py
+"""
+Components related to agent output streaming, including event models, stream consumers, and streamer utilities.
+"""
+from .stream_events import StreamEventType, StreamEvent
+from .agent_event_stream import AgentEventStream     
+from .queue_streamer import stream_queue_items
+
+__all__ = [
+    "StreamEventType",
+    "StreamEvent",
+    "AgentEventStream",   
+    "stream_queue_items", 
+]
+

autobyteus/agent/streaming/agent_event_stream.py

@@ -0,0 +1,120 @@
+import asyncio
+import logging
+import traceback
+import functools 
+import queue as standard_queue
+from typing import AsyncIterator, Dict, Any, TYPE_CHECKING, List, Optional, Callable, Union
+
+from autobyteus.llm.utils.response_types import ChunkResponse, CompleteResponse
+from autobyteus.agent.streaming.stream_events import StreamEvent, StreamEventType 
+from autobyteus.agent.streaming.stream_event_payloads import ( 
+    create_assistant_chunk_data,
+    create_assistant_complete_response_data,
+    create_tool_interaction_log_entry_data,
+    create_agent_operational_phase_transition_data, 
+    create_error_event_data,
+    create_tool_invocation_approval_requested_data,
+    EmptyData,
+    StreamDataPayload,
+    ErrorEventData, 
+)
+from .queue_streamer import stream_queue_items 
+from autobyteus.events.event_types import EventType 
+from autobyteus.events.event_emitter import EventEmitter 
+
+if TYPE_CHECKING:
+    from autobyteus.agent.agent import Agent
+    from autobyteus.agent.events.notifiers import AgentExternalEventNotifier
+
+logger = logging.getLogger(__name__)
+
+_AES_INTERNAL_SENTINEL = object()
+
+class AgentEventStream(EventEmitter): 
+    def __init__(self, agent: 'Agent'):
+        super().__init__() 
+        
+        from autobyteus.agent.agent import Agent as ConcreteAgent 
+        if not isinstance(agent, ConcreteAgent):
+            raise TypeError(f"AgentEventStream requires an Agent instance, got {type(agent).__name__}.")
+
+        self.agent_id: str = agent.agent_id
+        
+        self._loop = asyncio.get_event_loop() 
+        self._generic_stream_event_internal_q: standard_queue.Queue[Union[StreamEvent, object]] = standard_queue.Queue()
+
+        self._notifier: Optional['AgentExternalEventNotifier'] = None
+        if agent.context and agent.context.phase_manager: 
+            self._notifier = agent.context.phase_manager.notifier
+        
+        if not self._notifier:
+            logger.error(f"AgentEventStream for '{self.agent_id}': Notifier not available. No events will be streamed.")
+            return
+
+        self._register_listeners()
+        
+        logger.info(f"AgentEventStream (ID: {self.object_id}) initialized for agent_id '{self.agent_id}'. Subscribed to notifier.")
+
+    def _register_listeners(self):
+        """Subscribes this instance's handler to all relevant events from the notifier."""
+        all_agent_event_types = [et for et in EventType if et.name.startswith("AGENT_")]
+        
+        for event_type in all_agent_event_types:
+            handler = functools.partial(self._handle_notifier_event_sync, event_type=event_type)
+            self.subscribe_from(self._notifier, event_type, handler)
+
+    def _handle_notifier_event_sync(self, event_type: EventType, payload: Optional[Any] = None, object_id: Optional[str] = None, **kwargs):
+        event_agent_id = kwargs.get("agent_id", self.agent_id) 
+        
+        typed_payload_for_stream_event: Optional[StreamDataPayload] = None
+        stream_event_type_for_generic_stream: Optional[StreamEventType] = None
+
+        try: 
+            if event_type == EventType.AGENT_PHASE_IDLE_ENTERED:
+                typed_payload_for_stream_event = create_agent_operational_phase_transition_data(payload)
+                stream_event_type_for_generic_stream = StreamEventType.AGENT_IDLE
+            elif event_type.name.startswith("AGENT_PHASE_"):
+                typed_payload_for_stream_event = create_agent_operational_phase_transition_data(payload)
+                stream_event_type_for_generic_stream = StreamEventType.AGENT_OPERATIONAL_PHASE_TRANSITION
+            elif event_type == EventType.AGENT_DATA_ASSISTANT_CHUNK:
+                typed_payload_for_stream_event = create_assistant_chunk_data(payload)
+                stream_event_type_for_generic_stream = StreamEventType.ASSISTANT_CHUNK
+            elif event_type == EventType.AGENT_DATA_ASSISTANT_COMPLETE_RESPONSE:
+                typed_payload_for_stream_event = create_assistant_complete_response_data(payload)
+                stream_event_type_for_generic_stream = StreamEventType.ASSISTANT_COMPLETE_RESPONSE
+            elif event_type == EventType.AGENT_DATA_TOOL_LOG:
+                typed_payload_for_stream_event = create_tool_interaction_log_entry_data(payload)
+                stream_event_type_for_generic_stream = StreamEventType.TOOL_INTERACTION_LOG_ENTRY
+            elif event_type == EventType.AGENT_REQUEST_TOOL_INVOCATION_APPROVAL:
+                typed_payload_for_stream_event = create_tool_invocation_approval_requested_data(payload)
+                stream_event_type_for_generic_stream = StreamEventType.TOOL_INVOCATION_APPROVAL_REQUESTED
+            elif event_type == EventType.AGENT_ERROR_OUTPUT_GENERATION:
+                typed_payload_for_stream_event = create_error_event_data(payload)
+                stream_event_type_for_generic_stream = StreamEventType.ERROR_EVENT
+            
+            # The other queues are no longer needed, as `all_events` is the single source of truth.
+            elif event_type in [EventType.AGENT_DATA_ASSISTANT_CHUNK_STREAM_END, EventType.AGENT_DATA_TOOL_LOG_STREAM_END]:
+                 pass # These events are signals, not data for the unified stream.
+            else:
+                 logger.debug(f"AgentEventStream received internal event '{event_type.name}' with no direct stream mapping.")
+        
+        except Exception as e:
+            logger.error(f"AgentEventStream error processing payload for event '{event_type.name}': {e}", exc_info=True)
+
+        if typed_payload_for_stream_event and stream_event_type_for_generic_stream:
+            stream_event = StreamEvent(
+                agent_id=event_agent_id, 
+                event_type=stream_event_type_for_generic_stream, 
+                data=typed_payload_for_stream_event
+            )
+            self._generic_stream_event_internal_q.put(stream_event)
+
+    async def close(self):
+        logger.info(f"AgentEventStream (ID: {self.object_id}) for '{self.agent_id}': close() called. Unsubscribing all listeners and signaling.")
+        self.unsubscribe_all_listeners()
+        await self._loop.run_in_executor(None, self._generic_stream_event_internal_q.put, _AES_INTERNAL_SENTINEL)
+
+    async def all_events(self) -> AsyncIterator[StreamEvent]:
+        """The primary method to consume all structured events from the agent."""
+        async for event in stream_queue_items(self._generic_stream_event_internal_q, _AES_INTERNAL_SENTINEL, f"agent_{self.agent_id}_all_events"):
+            yield event

autobyteus/agent/streaming/queue_streamer.py

@@ -0,0 +1,58 @@
+# file: autobyteus/autobyteus/agent/streaming/queue_streamer.py
+import asyncio
+import logging
+from typing import TypeVar, AsyncIterator, Union, Any
+import queue as standard_queue
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar('T')
+
+async def stream_queue_items(
+    queue: standard_queue.Queue[Union[T, object]], 
+    sentinel: object, 
+    source_name: str = "unspecified_queue" 
+) -> AsyncIterator[T]:
+    """
+    Asynchronously iterates over a standard `queue.Queue`, yielding items of type T
+    until a specific sentinel object is encountered. This is designed to be used
+    from an async context to consume from a queue populated by a synchronous/threaded context.
+
+    Args:
+        queue: The standard `queue.Queue` to stream items from.
+        sentinel: The unique object used to signal the end of data in the queue.
+        source_name: An optional identifier for the queue source, used in logging.
+
+    Yields:
+        Items of type T from the queue.
+
+    Raises:
+        TypeError: If queue is not a `queue.Queue`.
+        ValueError: If sentinel is None.
+        asyncio.CancelledError: If the generator is cancelled.
+        Exception: Propagates exceptions encountered during queue.get().
+    """
+    if not isinstance(queue, standard_queue.Queue):
+        raise TypeError(f"queue must be an instance of queue.Queue for source '{source_name}'.")
+    if sentinel is None: 
+        raise ValueError(f"sentinel object cannot be None for source '{source_name}'.")
+
+    logger.debug(f"Starting to stream items from queue '{source_name}'.")
+    loop = asyncio.get_running_loop()
+    try:
+        while True:
+            # Use run_in_executor to wait for the blocking get() call without blocking the event loop.
+            item: Any = await loop.run_in_executor(None, queue.get) 
+            if item is sentinel:
+                logger.debug(f"Sentinel {sentinel!r} received from queue '{source_name}'. Ending stream.")
+                break
+            
+            yield item # type: ignore 
+    except asyncio.CancelledError:
+        logger.info(f"Stream from queue '{source_name}' was cancelled.")
+        raise 
+    except Exception as e:
+        logger.error(f"Error streaming from queue '{source_name}': {e}", exc_info=True)
+        raise 
+    finally:
+        logger.debug(f"Exiting stream_queue_items for queue '{source_name}'.")