autobyteus 1.2.1__py3-none-any.whl → 1.3.0__py3-none-any.whl

autobyteus/agent/runtime/agent_worker.py

@@ -6,16 +6,20 @@ import threading
 import concurrent.futures
 from typing import TYPE_CHECKING, Optional, Any, Callable, Awaitable, List
 
-from autobyteus.agent.phases import AgentOperationalPhase
+from autobyteus.agent.status.status_enum import AgentStatus
 from autobyteus.agent.events import ( 
     BaseEvent,
     AgentErrorEvent, 
     AgentStoppedEvent,
+    AgentInputEventQueueManager,
+    BootstrapStartedEvent,
+    AgentEventStore,
 )
 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
 from autobyteus.agent.shutdown_steps import AgentShutdownOrchestrator
+from autobyteus.agent.status.status_deriver import AgentStatusDeriver
+from autobyteus.agent.status.status_update_utils import apply_event_and_derive_status
 
 if TYPE_CHECKING:
     from autobyteus.agent.context import AgentContext
@@ -35,13 +39,12 @@ class AgentWorker:
                  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.status_manager = self.context.status_manager
+        if not self.status_manager: # pragma: no cover
+            raise ValueError(f"AgentWorker for '{self.context.agent_id}': AgentStatusManager not found.")
 
         self.worker_event_dispatcher = WorkerEventDispatcher(
-            event_handler_registry=event_handler_registry, 
-            phase_manager=self.phase_manager
+            event_handler_registry=event_handler_registry
         )
         
         self._thread_pool_manager = AgentThreadPoolManager() 
@@ -58,16 +61,70 @@ class AgentWorker:
 
     async def _initialize(self) -> bool:
         """
-        Runs the agent's initialization sequence by using an AgentBootstrapper.
+        Runs the agent's initialization sequence via bootstrap events.
         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.")
+        logger.info(f"Agent '{agent_id}': Starting internal initialization process using bootstrap events.")
 
-        bootstrapper = AgentBootstrapper() # Using default steps
-        initialization_successful = await bootstrapper.run(self.context, self.phase_manager)
+        await self.context.input_event_queues.enqueue_internal_system_event(BootstrapStartedEvent())
 
-        return initialization_successful
+        while self.context.current_status not in [AgentStatus.IDLE, AgentStatus.ERROR]:
+            if self._async_stop_event and self._async_stop_event.is_set():
+                break
+            try:
+                queue_event_tuple = await asyncio.wait_for(
+                    self.context.state.input_event_queues.get_next_internal_event(), timeout=0.1
+                )
+            except asyncio.TimeoutError:
+                continue
+
+            if queue_event_tuple is None:
+                continue
+
+            _queue_name, event_obj = queue_event_tuple
+            await self.worker_event_dispatcher.dispatch(event_obj, self.context)
+            await asyncio.sleep(0)
+
+        return self.context.current_status == AgentStatus.IDLE
+
+    async def _runtime_init(self) -> bool:
+        """
+        Initializes the minimal runtime prerequisites required for event handling.
+        This must run before any event-driven bootstrap steps.
+        """
+        agent_id = self.context.agent_id
+        if self.context.state.event_store is None:
+            self.context.state.event_store = AgentEventStore(agent_id=agent_id)
+            logger.info(f"Agent '{agent_id}': Runtime init completed (event store initialized).")
+
+        if self.context.state.status_deriver is None:
+            self.context.state.status_deriver = AgentStatusDeriver()
+            logger.info(f"Agent '{agent_id}': Runtime init completed (status deriver initialized).")
+
+        if self.context.state.input_event_queues is not None:
+            logger.debug(f"Agent '{agent_id}': Runtime init skipped; input event queues already initialized.")
+            return True
+
+        try:
+            queue_size = getattr(self.context.config, "input_event_queue_size", 0)
+            if queue_size is None:
+                queue_size = 0
+            if queue_size < 0:
+                logger.warning(
+                    f"Agent '{agent_id}': input_event_queue_size must be >= 0. "
+                    f"Got {queue_size}. Falling back to unbounded queues."
+                )
+                queue_size = 0
+
+            self.context.state.input_event_queues = AgentInputEventQueueManager(queue_size=queue_size)
+            logger.info(
+                f"Agent '{agent_id}': Runtime init completed (input queues initialized, size={queue_size})."
+            )
+            return True
+        except Exception as e:
+            logger.critical(f"Agent '{agent_id}': Runtime init failed while initializing input queues: {e}", exc_info=True)
+            return False
 
     def add_done_callback(self, callback: Callable[[concurrent.futures.Future], None]):
         """Adds a callback to be executed when the worker's thread completes."""
@@ -113,12 +170,16 @@ class AgentWorker:
             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():
+            if not self.context.current_status.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()))
+                    self._apply_event_and_derive_status_sync(
+                        AgentErrorEvent(
+                            error_message=f"Worker thread fatal error: {e}",
+                            exception_details=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}")
+                    logger.critical(f"AgentWorker '{agent_id}': Failed to emit derived error from sync context: {run_e}")
         finally:
             if self._worker_loop:
                 try:
@@ -145,6 +206,13 @@ class AgentWorker:
             logger.info(f"AgentWorker '{agent_id}' async_run(): Starting.")
             
             # --- Direct Initialization ---
+            runtime_init_successful = await self._runtime_init()
+            if not runtime_init_successful:
+                logger.critical(f"AgentWorker '{agent_id}' failed during runtime init. Worker is shutting down.")
+                if self._async_stop_event and not self._async_stop_event.is_set():
+                    self._async_stop_event.set()
+                return
+
             initialization_successful = await self._initialize()
             if not initialization_successful:
                 logger.critical(f"AgentWorker '{agent_id}' failed to initialize. Worker is shutting down.")
@@ -156,9 +224,14 @@ class AgentWorker:
             logger.info(f"AgentWorker '{agent_id}' initialized successfully. Entering main event loop.")
             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
-                    )
+                    if self.context.current_status == AgentStatus.BOOTSTRAPPING:
+                        queue_event_tuple = await asyncio.wait_for(
+                            self.context.state.input_event_queues.get_next_internal_event(), timeout=0.1
+                        )
+                    else:
+                        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
@@ -229,6 +302,12 @@ class AgentWorker:
         
         self._is_active = False
 
+    def _apply_event_and_derive_status_sync(self, event: BaseEvent) -> None:
+        try:
+            asyncio.run(apply_event_and_derive_status(event, self.context))
+        except Exception as e:  # pragma: no cover
+            logger.error(f"AgentWorker '{self.context.agent_id}': Failed to project status: {e}", exc_info=True)
+
 
     def is_alive(self) -> bool:
         return self._thread_future is not None and not self._thread_future.done()

autobyteus/agent/shutdown_steps/__init__.py

@@ -7,11 +7,13 @@ These steps are orchestrated by the AgentShutdownOrchestrator.
 from .base_shutdown_step import BaseShutdownStep
 from .llm_instance_cleanup_step import LLMInstanceCleanupStep
 from .mcp_server_cleanup_step import McpServerCleanupStep
+from .tool_cleanup_step import ToolCleanupStep
 from .agent_shutdown_orchestrator import AgentShutdownOrchestrator
 
 __all__ = [
     "BaseShutdownStep",
     "LLMInstanceCleanupStep",
     "McpServerCleanupStep",
+    "ToolCleanupStep",
     "AgentShutdownOrchestrator",
 ]

autobyteus/agent/shutdown_steps/agent_shutdown_orchestrator.py

@@ -5,6 +5,7 @@ from typing import TYPE_CHECKING, List, Optional
 from .base_shutdown_step import BaseShutdownStep
 from .llm_instance_cleanup_step import LLMInstanceCleanupStep
 from .mcp_server_cleanup_step import McpServerCleanupStep
+from .tool_cleanup_step import ToolCleanupStep
 
 if TYPE_CHECKING:
     from autobyteus.agent.context import AgentContext
@@ -27,6 +28,7 @@ class AgentShutdownOrchestrator:
         if steps is None:
             self.shutdown_steps: List[BaseShutdownStep] = [
                 LLMInstanceCleanupStep(),
+                ToolCleanupStep(),
                 McpServerCleanupStep(),
             ]
             logger.debug("AgentShutdownOrchestrator initialized with default steps.")

autobyteus/agent/shutdown_steps/tool_cleanup_step.py

@@ -0,0 +1,58 @@
+import asyncio
+import logging
+from typing import TYPE_CHECKING
+
+from .base_shutdown_step import BaseShutdownStep
+
+if TYPE_CHECKING:
+    from autobyteus.agent.context import AgentContext
+    from autobyteus.tools.base_tool import BaseTool
+
+logger = logging.getLogger(__name__)
+
+
+class ToolCleanupStep(BaseShutdownStep):
+    """
+    Shutdown step responsible for cleaning up all tool instances retained in the agent context.
+    """
+
+    def __init__(self):
+        logger.debug("ToolCleanupStep initialized.")
+
+    async def execute(self, context: 'AgentContext') -> bool:
+        agent_id = context.agent_id
+        logger.info(f"Agent '{agent_id}': Executing ToolCleanupStep.")
+
+        tool_instances = context.tool_instances
+        if not tool_instances:
+            logger.debug(f"Agent '{agent_id}': No tool instances found. Skipping ToolCleanupStep.")
+            return True
+
+        all_cleanups_succeeded = True
+
+        for tool_name, tool_instance in tool_instances.items():
+            try:
+                cleanup_func = getattr(tool_instance, "cleanup", None)
+                if cleanup_func is None:
+                    logger.debug(f"Agent '{agent_id}': Tool '{tool_name}' has no cleanup hook. Skipping.")
+                    continue
+
+                logger.info(f"Agent '{agent_id}': Cleaning up tool '{tool_name}'.")
+                if asyncio.iscoroutinefunction(cleanup_func):
+                    await cleanup_func()
+                else:
+                    cleanup_func()
+                logger.debug(f"Agent '{agent_id}': Tool '{tool_name}' cleanup completed.")
+            except Exception as exc:  # pragma: no cover - defensive logging
+                all_cleanups_succeeded = False
+                logger.error(
+                    f"Agent '{agent_id}': Error during cleanup of tool '{tool_name}': {exc}",
+                    exc_info=True,
+                )
+
+        if all_cleanups_succeeded:
+            logger.info(f"Agent '{agent_id}': ToolCleanupStep completed successfully.")
+        else:
+            logger.warning(f"Agent '{agent_id}': ToolCleanupStep completed with errors; see logs above.")
+
+        return all_cleanups_succeeded

autobyteus/agent/status/__init__.py

@@ -0,0 +1,14 @@
+# file: autobyteus/autobyteus/agent/status/__init__.py
+"""
+This package contains components for defining and describing agent operational statuses
+and their updates.
+"""
+from .status_enum import AgentStatus
+from .manager import AgentStatusManager
+from .status_deriver import AgentStatusDeriver
+
+__all__ = [
+    "AgentStatus",
+    "AgentStatusManager",
+    "AgentStatusDeriver",
+]

autobyteus/agent/status/manager.py

@@ -0,0 +1,93 @@
+
+# file: autobyteus/autobyteus/agent/status/manager.py
+import logging
+from typing import TYPE_CHECKING, Optional, Dict, Any, List
+
+from autobyteus.agent.status.status_enum import AgentStatus
+
+if TYPE_CHECKING:
+    from autobyteus.agent.context import AgentContext
+    from autobyteus.agent.events.notifiers import AgentExternalEventNotifier
+
+
+logger = logging.getLogger(__name__)
+
+class AgentStatusManager:
+    """
+    Handles lifecycle processor execution and external status notifications.
+    Status is derived from events; this manager does not own the source of truth.
+    """
+    def __init__(self, context: 'AgentContext', notifier: Optional['AgentExternalEventNotifier'] = None):
+        self.context: 'AgentContext' = context
+        if notifier is None:
+            raise ValueError("AgentStatusManager requires a notifier.")
+        self.notifier = notifier
+        if not isinstance(self.context.current_status, AgentStatus):
+            self.context.current_status = AgentStatus.UNINITIALIZED
+
+        logger.debug(
+            f"AgentStatusManager initialized for agent_id '{self.context.agent_id}'. "
+            f"Initial status: {self.context.current_status.value}. Notifier provided: {bool(notifier)}"
+        )
+
+    async def _execute_lifecycle_processors(self, old_status: AgentStatus, new_status: AgentStatus, event_data: Optional[Dict[str, Any]] = None):
+        """
+        Execute lifecycle processors for the given status update.
+        Maps internal status changes to simple LifecycleEvent values.
+        """
+        from autobyteus.agent.lifecycle import LifecycleEvent
+        
+        # Map status changes to lifecycle events
+        lifecycle_event = None
+        if old_status == AgentStatus.BOOTSTRAPPING and new_status == AgentStatus.IDLE:
+            lifecycle_event = LifecycleEvent.AGENT_READY
+        elif new_status == AgentStatus.AWAITING_LLM_RESPONSE:
+            lifecycle_event = LifecycleEvent.BEFORE_LLM_CALL
+        elif old_status == AgentStatus.AWAITING_LLM_RESPONSE and new_status == AgentStatus.ANALYZING_LLM_RESPONSE:
+            lifecycle_event = LifecycleEvent.AFTER_LLM_RESPONSE
+        elif new_status == AgentStatus.EXECUTING_TOOL:
+            lifecycle_event = LifecycleEvent.BEFORE_TOOL_EXECUTE
+        elif old_status == AgentStatus.EXECUTING_TOOL:
+            lifecycle_event = LifecycleEvent.AFTER_TOOL_EXECUTE
+        elif new_status == AgentStatus.SHUTTING_DOWN:
+            lifecycle_event = LifecycleEvent.AGENT_SHUTTING_DOWN
+        
+        if lifecycle_event is None:
+            return
+        
+        # Find and execute matching processors
+        processors_to_run = [
+            p for p in self.context.config.lifecycle_processors
+            if p.event == lifecycle_event
+        ]
+        
+        if not processors_to_run:
+            return
+        
+        # Sort by order
+        sorted_processors = sorted(processors_to_run, key=lambda p: p.get_order())
+        processor_names = [p.get_name() for p in sorted_processors]
+        logger.info(f"Agent '{self.context.agent_id}': Executing {len(sorted_processors)} lifecycle processors for '{lifecycle_event.value}': {processor_names}")
+        
+        for processor in sorted_processors:
+            try:
+                await processor.process(self.context, event_data or {})
+                logger.debug(f"Agent '{self.context.agent_id}': Lifecycle processor '{processor.get_name()}' executed successfully.")
+            except Exception as e:
+                logger.error(f"Agent '{self.context.agent_id}': Error executing lifecycle processor "
+                             f"'{processor.get_name()}' for '{lifecycle_event.value}': {e}",
+                             exc_info=True)
+
+    async def emit_status_update(self,
+                                 old_status: AgentStatus,
+                                 new_status: AgentStatus,
+                                 additional_data: Optional[Dict[str, Any]] = None) -> None:
+        """
+        Emits notifier events and lifecycle processors for a status update
+        derived from the event stream.
+        """
+        if old_status == new_status:
+            return
+
+        await self._execute_lifecycle_processors(old_status, new_status, additional_data)
+        self.notifier.notify_status_updated(new_status, old_status, additional_data)

autobyteus/agent/status/status_deriver.py

@@ -0,0 +1,96 @@
+# file: autobyteus/autobyteus/agent/status/status_deriver.py
+import logging
+from typing import Optional, Tuple, TYPE_CHECKING
+
+from autobyteus.agent.status.status_enum import AgentStatus
+from autobyteus.agent.events.agent_events import (
+    AgentReadyEvent,
+    AgentStoppedEvent,
+    AgentErrorEvent,
+    AgentIdleEvent,
+    ShutdownRequestedEvent,
+    BootstrapStartedEvent,
+    BootstrapCompletedEvent,
+    UserMessageReceivedEvent,
+    InterAgentMessageReceivedEvent,
+    LLMUserMessageReadyEvent,
+    LLMCompleteResponseReceivedEvent,
+    PendingToolInvocationEvent,
+    ToolExecutionApprovalEvent,
+    ApprovedToolInvocationEvent,
+    ToolResultEvent,
+)
+
+if TYPE_CHECKING:
+    from autobyteus.agent.context import AgentContext
+    from autobyteus.agent.events.agent_events import BaseEvent
+
+logger = logging.getLogger(__name__)
+
+
+class AgentStatusDeriver:
+    """
+    Derives agent status from an event stream.
+    This is a pure read-model: no side effects beyond status updates.
+    """
+    def __init__(self, initial_status: AgentStatus = AgentStatus.UNINITIALIZED):
+        self._current_status = initial_status
+        logger.debug(f"AgentStatusDeriver initialized with status '{initial_status.value}'.")
+
+    @property
+    def current_status(self) -> AgentStatus:
+        return self._current_status
+
+    def apply(self, event: 'BaseEvent', context: Optional['AgentContext'] = None) -> Tuple[AgentStatus, AgentStatus]:
+        old_status = self._current_status
+        new_status = self._reduce(event, old_status, context)
+        self._current_status = new_status
+        return old_status, new_status
+
+    def _reduce(self, event: 'BaseEvent', current_status: AgentStatus, context: Optional['AgentContext']) -> AgentStatus:
+        if isinstance(event, BootstrapStartedEvent):
+            return AgentStatus.BOOTSTRAPPING
+        if isinstance(event, BootstrapCompletedEvent):
+            return current_status
+        if isinstance(event, AgentReadyEvent):
+            return AgentStatus.IDLE
+        if isinstance(event, AgentIdleEvent):
+            return AgentStatus.IDLE
+        if isinstance(event, ShutdownRequestedEvent):
+            if current_status == AgentStatus.ERROR:
+                return current_status
+            return AgentStatus.SHUTTING_DOWN
+        if isinstance(event, AgentStoppedEvent):
+            if current_status == AgentStatus.ERROR:
+                return AgentStatus.ERROR
+            return AgentStatus.SHUTDOWN_COMPLETE
+        if isinstance(event, AgentErrorEvent):
+            return AgentStatus.ERROR
+
+        if isinstance(event, (UserMessageReceivedEvent, InterAgentMessageReceivedEvent)):
+            return AgentStatus.PROCESSING_USER_INPUT
+        if isinstance(event, LLMUserMessageReadyEvent):
+            if current_status in [AgentStatus.AWAITING_LLM_RESPONSE, AgentStatus.ERROR]:
+                return current_status
+            return AgentStatus.AWAITING_LLM_RESPONSE
+        if isinstance(event, LLMCompleteResponseReceivedEvent):
+            if current_status != AgentStatus.AWAITING_LLM_RESPONSE:
+                return current_status
+            return AgentStatus.ANALYZING_LLM_RESPONSE
+
+        if isinstance(event, PendingToolInvocationEvent):
+            if context and not context.auto_execute_tools:
+                return AgentStatus.AWAITING_TOOL_APPROVAL
+            return AgentStatus.EXECUTING_TOOL
+        if isinstance(event, ApprovedToolInvocationEvent):
+            return AgentStatus.EXECUTING_TOOL
+        if isinstance(event, ToolExecutionApprovalEvent):
+            if event.is_approved:
+                return AgentStatus.EXECUTING_TOOL
+            return AgentStatus.TOOL_DENIED
+        if isinstance(event, ToolResultEvent):
+            if current_status != AgentStatus.EXECUTING_TOOL:
+                return current_status
+            return AgentStatus.PROCESSING_TOOL_RESULT
+
+        return current_status

autobyteus/agent/{phases/phase_enum.py → status/status_enum.py}

@@ -1,10 +1,10 @@
-# file: autobyteus/autobyteus/agent/context/phases/phase_enum.py
+# file: autobyteus/autobyteus/agent/status/status_enum.py
 from enum import Enum
 
-class AgentOperationalPhase(str, Enum):
+class AgentStatus(str, Enum):
     """
-    Defines the fine-grained operational phases of an agent.
-    This is the single source of truth for an agent's current state of operation.
+    Defines the possible operational statuses of an agent.
+    Renamed from the legacy operational state enum.
     """
     UNINITIALIZED = "uninitialized"            # Agent object created, but runtime not started or fully set up.
     BOOTSTRAPPING = "bootstrapping"            # Agent is running its internal initialization/bootstrap sequence.
@@ -27,23 +27,23 @@ class AgentOperationalPhase(str, Enum):
         return self.value
 
     def is_initializing(self) -> bool:
-        """Checks if the agent is in any of the initializing phases."""
+        """Checks if the agent is in any of the initializing statuses."""
         return self in [
-            AgentOperationalPhase.BOOTSTRAPPING,
+            AgentStatus.BOOTSTRAPPING,
         ]
 
     def is_processing(self) -> bool:
-        """Checks if the agent is in any active processing phase (post-initialization, pre-shutdown)."""
+        """Checks if the agent is in any active processing status (post-initialization, pre-shutdown)."""
         return self in [
-            AgentOperationalPhase.PROCESSING_USER_INPUT,
-            AgentOperationalPhase.AWAITING_LLM_RESPONSE,
-            AgentOperationalPhase.ANALYZING_LLM_RESPONSE,
-            AgentOperationalPhase.AWAITING_TOOL_APPROVAL,
-            AgentOperationalPhase.TOOL_DENIED,
-            AgentOperationalPhase.EXECUTING_TOOL,
-            AgentOperationalPhase.PROCESSING_TOOL_RESULT,
+            AgentStatus.PROCESSING_USER_INPUT,
+            AgentStatus.AWAITING_LLM_RESPONSE,
+            AgentStatus.ANALYZING_LLM_RESPONSE,
+            AgentStatus.AWAITING_TOOL_APPROVAL,
+            AgentStatus.TOOL_DENIED,
+            AgentStatus.EXECUTING_TOOL,
+            AgentStatus.PROCESSING_TOOL_RESULT,
         ]
     
     def is_terminal(self) -> bool:
-        """Checks if the phase is a terminal state (shutdown or error)."""
-        return self in [AgentOperationalPhase.SHUTDOWN_COMPLETE, AgentOperationalPhase.ERROR]
+        """Checks if the status is a terminal state (shutdown or error)."""
+        return self in [AgentStatus.SHUTDOWN_COMPLETE, AgentStatus.ERROR]

autobyteus/agent/status/status_update_utils.py

@@ -0,0 +1,73 @@
+# file: autobyteus/autobyteus/agent/status/status_update_utils.py
+import logging
+from typing import Optional, Tuple, TYPE_CHECKING
+
+from autobyteus.agent.status.status_enum import AgentStatus
+from autobyteus.agent.events.agent_events import (
+    AgentErrorEvent,
+    PendingToolInvocationEvent,
+    ApprovedToolInvocationEvent,
+    ToolExecutionApprovalEvent,
+    ToolResultEvent,
+)
+
+if TYPE_CHECKING:
+    from autobyteus.agent.context import AgentContext
+    from autobyteus.agent.events.agent_events import BaseEvent
+
+logger = logging.getLogger(__name__)
+
+
+def build_status_update_data(event: 'BaseEvent',
+                             context: 'AgentContext',
+                             new_status: AgentStatus) -> Optional[dict]:
+    if new_status == AgentStatus.PROCESSING_USER_INPUT:
+        return {"trigger": type(event).__name__}
+
+    if new_status == AgentStatus.EXECUTING_TOOL:
+        tool_name = None
+        if isinstance(event, PendingToolInvocationEvent):
+            tool_name = event.tool_invocation.name
+        elif isinstance(event, ApprovedToolInvocationEvent):
+            tool_name = event.tool_invocation.name
+        elif isinstance(event, ToolExecutionApprovalEvent):
+            pending_invocation = context.state.pending_tool_approvals.get(event.tool_invocation_id)
+            tool_name = pending_invocation.name if pending_invocation else "unknown_tool"
+        if tool_name:
+            return {"tool_name": tool_name}
+
+    if new_status == AgentStatus.PROCESSING_TOOL_RESULT and isinstance(event, ToolResultEvent):
+        return {"tool_name": event.tool_name}
+
+    if new_status == AgentStatus.TOOL_DENIED and isinstance(event, ToolExecutionApprovalEvent):
+        pending_invocation = context.state.pending_tool_approvals.get(event.tool_invocation_id)
+        tool_name = pending_invocation.name if pending_invocation else "unknown_tool"
+        return {"tool_name": tool_name, "denial_for_tool": tool_name}
+
+    if new_status == AgentStatus.ERROR and isinstance(event, AgentErrorEvent):
+        return {"error_message": event.error_message, "error_details": event.exception_details}
+
+    return None
+
+
+async def apply_event_and_derive_status(event: 'BaseEvent',
+                                        context: 'AgentContext') -> Tuple[AgentStatus, AgentStatus]:
+    if context.state.event_store:
+        try:
+            context.state.event_store.append(event)
+        except Exception as exc:  # pragma: no cover
+            logger.error(f"Failed to append event to store: {exc}", exc_info=True)
+
+    if not context.state.status_deriver:
+        return context.current_status, context.current_status
+
+    old_status, new_status = context.state.status_deriver.apply(event, context)
+    if old_status != new_status:
+        context.current_status = new_status
+        additional_data = build_status_update_data(event, context, new_status)
+        if context.status_manager:
+            await context.status_manager.emit_status_update(
+                old_status, new_status, additional_data=additional_data
+            )
+
+    return old_status, new_status

autobyteus/agent/streaming/__init__.py

@@ -1,15 +1,62 @@
 # file: autobyteus/autobyteus/agent/streaming/__init__.py
 """
-Components related to agent output streaming, including event models, stream consumers, and streamer utilities.
+Components related to agent output streaming.
+
+Main components:
+- StreamingResponseHandler: High-level handler for LLM response parsing
+- StreamingParser: Low-level character-by-character parser
+- SegmentEvent: Structured events for UI streaming
+
+Legacy components (for backward compatibility):
+- StreamEvent, StreamEventType: Old event format
+- AgentEventStream: Old stream consumer
 """
-from .stream_events import StreamEventType, StreamEvent
-from .agent_event_stream import AgentEventStream     
-from .queue_streamer import stream_queue_items
+from .events.stream_events import StreamEventType, StreamEvent
+from .streams.agent_event_stream import AgentEventStream
+from .utils.queue_streamer import stream_queue_items
+from .handlers.streaming_response_handler import StreamingResponseHandler
+from .handlers.streaming_handler_factory import StreamingResponseHandlerFactory
+from .handlers.parsing_streaming_response_handler import ParsingStreamingResponseHandler
+from .handlers.pass_through_streaming_response_handler import PassThroughStreamingResponseHandler
+from .handlers.api_tool_call_streaming_response_handler import ApiToolCallStreamingResponseHandler
+
+# Re-export commonly used parser components
+from .parser import (
+    StreamingParser,
+    SegmentEvent,
+    SegmentType,
+    SegmentEventType,
+    ToolInvocationAdapter,
+    ParserConfig,
+    parse_complete_response,
+    extract_segments,
+    StreamingParserProtocol,
+    create_streaming_parser,
+    resolve_parser_name,
+)
 
 __all__ = [
+    # New streaming API
+    "StreamingResponseHandler",
+    "StreamingResponseHandlerFactory",
+    "ParsingStreamingResponseHandler",
+    "PassThroughStreamingResponseHandler",
+    "ApiToolCallStreamingResponseHandler",
+    "StreamingParser",
+    "SegmentEvent",
+    "SegmentType",
+    "SegmentEventType",
+    "ToolInvocationAdapter",
+    "ParserConfig",
+    "parse_complete_response",
+    "extract_segments",
+    "StreamingParserProtocol",
+    "create_streaming_parser",
+    "resolve_parser_name",
+    
+    # Legacy (backward compatible)
     "StreamEventType",
     "StreamEvent",
     "AgentEventStream",   
     "stream_queue_items", 
 ]
-