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

autobyteus/agent/events/worker_event_dispatcher.py

@@ -1,117 +1,74 @@
 # file: autobyteus/autobyteus/agent/events/worker_event_dispatcher.py
-import asyncio
 import logging
 import traceback
-from typing import TYPE_CHECKING, Optional
+from typing import TYPE_CHECKING
 
-from autobyteus.agent.phases import AgentOperationalPhase
+from autobyteus.agent.status.status_enum import AgentStatus
+from autobyteus.agent.status.status_update_utils import apply_event_and_derive_status
 from autobyteus.agent.events.agent_events import ( # Updated relative import path if needed, but BaseEvent is fine
     BaseEvent,
-    AgentReadyEvent,
     AgentErrorEvent,
-    LLMUserMessageReadyEvent,
-    PendingToolInvocationEvent,
-    ToolExecutionApprovalEvent,
-    ToolResultEvent,
+    AgentIdleEvent,
     LLMCompleteResponseReceivedEvent,
-    UserMessageReceivedEvent, 
-    InterAgentMessageReceivedEvent, 
 )
 
 if TYPE_CHECKING:
     from autobyteus.agent.context import AgentContext
     from autobyteus.agent.handlers import EventHandlerRegistry
-    from autobyteus.agent.phases import AgentPhaseManager
 logger = logging.getLogger(__name__)
 
 class WorkerEventDispatcher:
     """
     Responsible for dispatching events to their appropriate handlers within an AgentWorker.
-    It also manages related phase transitions that occur immediately before or after
+    It also manages related status updates that occur immediately before or after
     an event is handled. This component is part of the agent's event system.
     """
 
     def __init__(self,
-                 event_handler_registry: 'EventHandlerRegistry',
-                 phase_manager: 'AgentPhaseManager'):
+                 event_handler_registry: 'EventHandlerRegistry'):
         """
         Initializes the WorkerEventDispatcher.
 
         Args:
             event_handler_registry: The registry for event handlers.
-            phase_manager: The agent's phase manager.
         """
         self.event_handler_registry: 'EventHandlerRegistry' = event_handler_registry
-        self.phase_manager: 'AgentPhaseManager' = phase_manager
         logger.debug("WorkerEventDispatcher initialized.")
 
     async def dispatch(self, event: BaseEvent, context: 'AgentContext') -> None: # pragma: no cover
         """
-        Dispatches an event to its registered handler and manages phase transitions.
+        Dispatches an event to its registered handler and manages status updates.
         """
         event_class = type(event)
         handler = self.event_handler_registry.get_handler(event_class)
         agent_id = context.agent_id 
 
+        try:
+            await apply_event_and_derive_status(event, context)
+        except Exception as e:  # pragma: no cover
+            logger.error(f"WorkerEventDispatcher '{agent_id}': Status projection failed: {e}", exc_info=True)
+
         if handler:
             event_class_name = event_class.__name__
             handler_class_name = type(handler).__name__
 
-            current_phase_before_dispatch = context.current_phase
-
-            if current_phase_before_dispatch == AgentOperationalPhase.IDLE:
-                if isinstance(event, (UserMessageReceivedEvent, InterAgentMessageReceivedEvent)):
-                    await self.phase_manager.notify_processing_input_started(trigger_info=type(event).__name__)
-            
-            if isinstance(event, LLMUserMessageReadyEvent):
-                if current_phase_before_dispatch not in [AgentOperationalPhase.AWAITING_LLM_RESPONSE, AgentOperationalPhase.ERROR]:
-                    await self.phase_manager.notify_awaiting_llm_response()
-            elif isinstance(event, PendingToolInvocationEvent):
-                if not context.auto_execute_tools:
-                    await self.phase_manager.notify_tool_execution_pending_approval(event.tool_invocation)
-                else: 
-                    await self.phase_manager.notify_tool_execution_started(event.tool_invocation.name)
-            elif isinstance(event, ToolExecutionApprovalEvent):
-                tool_name_for_approval: Optional[str] = None
-                pending_invocation = context.state.pending_tool_approvals.get(event.tool_invocation_id) 
-                if pending_invocation:
-                    tool_name_for_approval = pending_invocation.name
-                else: 
-                    logger.warning(f"WorkerEventDispatcher '{agent_id}': Could not find pending invocation for ID '{event.tool_invocation_id}' to get tool name for phase notification.")
-                    tool_name_for_approval = "unknown_tool" 
-
-                await self.phase_manager.notify_tool_execution_resumed_after_approval(
-                    approved=event.is_approved, 
-                    tool_name=tool_name_for_approval
-                )
-            elif isinstance(event, ToolResultEvent):
-                 if context.current_phase == AgentOperationalPhase.EXECUTING_TOOL: 
-                    await self.phase_manager.notify_processing_tool_result(event.tool_name)
-            elif isinstance(event, LLMCompleteResponseReceivedEvent):
-                if context.current_phase == AgentOperationalPhase.AWAITING_LLM_RESPONSE:
-                    await self.phase_manager.notify_analyzing_llm_response()
-
             try:
-                logger.debug(f"WorkerEventDispatcher '{agent_id}' (Phase: {context.current_phase.value}) dispatching '{event_class_name}' to {handler_class_name}.")
+                logger.debug(f"WorkerEventDispatcher '{agent_id}' (Status: {context.current_status.value}) dispatching '{event_class_name}' to {handler_class_name}.")
                 await handler.handle(event, context) 
-                logger.debug(f"WorkerEventDispatcher '{agent_id}' (Phase: {context.current_phase.value}) event '{event_class_name}' handled by {handler_class_name}.")
-
-                if isinstance(event, AgentReadyEvent): 
-                    await self.phase_manager.notify_initialization_complete() 
-                
-                if isinstance(event, LLMCompleteResponseReceivedEvent):
-                    if context.current_phase == AgentOperationalPhase.ANALYZING_LLM_RESPONSE and \
-                       not context.state.pending_tool_approvals and \
-                       context.input_event_queues.tool_invocation_request_queue.empty():
-                           await self.phase_manager.notify_processing_complete_and_idle()
+                logger.debug(f"WorkerEventDispatcher '{agent_id}' (Status: {context.current_status.value}) event '{event_class_name}' handled by {handler_class_name}.")
 
             except Exception as e: 
                 error_details = traceback.format_exc()
                 error_msg = f"WorkerEventDispatcher '{agent_id}' error handling '{event_class_name}' with {handler_class_name}: {e}"
                 logger.error(error_msg, exc_info=True)
-                await self.phase_manager.notify_error_occurred(error_msg, error_details) 
                 await context.input_event_queues.enqueue_internal_system_event(
                     AgentErrorEvent(error_message=error_msg, exception_details=error_details)
                 )
+            else:
+                if isinstance(event, LLMCompleteResponseReceivedEvent):
+                    if context.current_status == AgentStatus.ANALYZING_LLM_RESPONSE and \
+                       not context.state.pending_tool_approvals and \
+                       context.input_event_queues.tool_invocation_request_queue.empty():
+                           await context.input_event_queues.enqueue_internal_system_event(AgentIdleEvent())
         else: 
-            logger.warning(f"WorkerEventDispatcher '{agent_id}' (Phase: {context.current_phase.value}) No handler for '{event_class.__name__}'. Event: {event}")
+            logger.warning(f"WorkerEventDispatcher '{agent_id}' (Status: {context.current_status.value}) No handler for '{event_class.__name__}'. Event: {event}")

autobyteus/agent/factory/agent_factory.py

@@ -13,6 +13,13 @@ from autobyteus.agent.workspace.base_workspace import BaseAgentWorkspace
 from autobyteus.agent.handlers import *
 from autobyteus.utils.singleton import SingletonMeta
 from autobyteus.tools.base_tool import BaseTool
+from autobyteus.memory import FileMemoryStore, MemoryManager, resolve_memory_base_dir
+from autobyteus.memory.store.working_context_snapshot_store import WorkingContextSnapshotStore
+from autobyteus.memory.restore.working_context_snapshot_bootstrapper import WorkingContextSnapshotBootstrapOptions
+from autobyteus.agent.input_processor.memory_ingest_input_processor import MemoryIngestInputProcessor
+from autobyteus.agent.tool_execution_result_processor.memory_ingest_tool_result_processor import (
+    MemoryIngestToolResultProcessor,
+)
 
 if TYPE_CHECKING:
     from autobyteus.agent.runtime.agent_runtime import AgentRuntime
@@ -41,9 +48,16 @@ class AgentFactory(metaclass=SingletonMeta):
         registry.register(ToolExecutionApprovalEvent, ToolExecutionApprovalEventHandler())
         registry.register(LLMUserMessageReadyEvent, LLMUserMessageReadyEventHandler())
         registry.register(ApprovedToolInvocationEvent, ApprovedToolInvocationEventHandler())
+        bootstrap_handler = BootstrapEventHandler()
+        registry.register(BootstrapStartedEvent, bootstrap_handler)
+        registry.register(BootstrapStepRequestedEvent, bootstrap_handler)
+        registry.register(BootstrapStepCompletedEvent, bootstrap_handler)
+        registry.register(BootstrapCompletedEvent, bootstrap_handler)
         lifecycle_logger_instance = LifecycleEventLogger()
         registry.register(AgentReadyEvent, lifecycle_logger_instance)
         registry.register(AgentStoppedEvent, lifecycle_logger_instance)
+        registry.register(AgentIdleEvent, lifecycle_logger_instance)
+        registry.register(ShutdownRequestedEvent, lifecycle_logger_instance)
         registry.register(AgentErrorEvent, lifecycle_logger_instance)
         return registry
 
@@ -69,18 +83,58 @@ class AgentFactory(metaclass=SingletonMeta):
         
         return tool_instances_dict
 
-    def _create_runtime(self, 
-                        agent_id: str, 
-                        config: AgentConfig
-                        ) -> 'AgentRuntime': 
+    def _prepare_skills(self, agent_id: str, config: AgentConfig):
+        """
+        Registers skills from paths and ensures all skill names are valid.
+        """
+        from autobyteus.skills.registry import SkillRegistry
+        import os
+
+        registry = SkillRegistry()
+        updated_skills = []
+        for skill_item in config.skills:
+            # Check if it's a path (absolute or relative to current working directory)
+            if os.path.isabs(skill_item) or os.path.exists(skill_item):
+                try:
+                    skill = registry.register_skill_from_path(skill_item)
+                    updated_skills.append(skill.name)
+                except Exception as e:
+                    logger.error(f"Agent '{agent_id}': Failed to register skill from path '{skill_item}': {e}")
+            else:
+                updated_skills.append(skill_item)
+        
+        config.skills = updated_skills
+
+    def _create_runtime_with_id(self,
+                                agent_id: str,
+                                config: AgentConfig,
+                                memory_dir_override: Optional[str] = None,
+                                restore_options: Optional[WorkingContextSnapshotBootstrapOptions] = None
+                                ) -> 'AgentRuntime':
         from autobyteus.agent.runtime.agent_runtime import AgentRuntime 
 
+        # Prepare skills (resolve paths to names and register them)
+        self._prepare_skills(agent_id, config)
+
         # The workspace and initial custom data are now passed directly from the config to the state.
         runtime_state = AgentRuntimeState(
             agent_id=agent_id,
             workspace=config.workspace,
             custom_data=config.initial_custom_data
         )
+
+        # Memory manager (file-backed) initialization
+        memory_dir = resolve_memory_base_dir(override_dir=memory_dir_override or config.memory_dir)
+        memory_store = FileMemoryStore(base_dir=memory_dir, agent_id=agent_id)
+        working_context_snapshot_store = WorkingContextSnapshotStore(base_dir=memory_dir, agent_id=agent_id)
+        runtime_state.memory_manager = MemoryManager(store=memory_store, working_context_snapshot_store=working_context_snapshot_store)
+        runtime_state.restore_options = restore_options
+
+        # Ensure memory ingest processors are present
+        if not any(isinstance(p, MemoryIngestInputProcessor) for p in config.input_processors):
+            config.input_processors.append(MemoryIngestInputProcessor())
+        if not any(isinstance(p, MemoryIngestToolResultProcessor) for p in config.tool_execution_result_processors):
+            config.tool_execution_result_processors.append(MemoryIngestToolResultProcessor())
         
         # --- Set pre-initialized instances on the state ---
         runtime_state.llm_instance = config.llm_instance
@@ -94,7 +148,7 @@ class AgentFactory(metaclass=SingletonMeta):
         logger.info(f"Instantiating AgentRuntime for agent_id: '{agent_id}' with config: '{config.name}'.")
         
         return AgentRuntime(
-            context=context, 
+            context=context,
             event_handler_registry=event_handler_registry
         )
 
@@ -114,7 +168,7 @@ class AgentFactory(metaclass=SingletonMeta):
         while agent_id in self._active_agents:
             agent_id = f"{config.name}_{config.role}_{random.randint(1000, 9999)}"
 
-        runtime = self._create_runtime(
+        runtime = self._create_runtime_with_id(
             agent_id=agent_id,
             config=config,
         )
@@ -124,6 +178,29 @@ class AgentFactory(metaclass=SingletonMeta):
         logger.info(f"Agent '{agent_id}' created and stored successfully.")
         return agent
 
+    def restore_agent(
+        self,
+        agent_id: str,
+        config: AgentConfig,
+        memory_dir: Optional[str] = None,
+    ) -> Agent:
+        if not agent_id or not isinstance(agent_id, str):
+            raise ValueError("restore_agent requires a non-empty string agent_id.")
+        if agent_id in self._active_agents:
+            raise ValueError(f"Agent '{agent_id}' is already active.")
+
+        restore_options = WorkingContextSnapshotBootstrapOptions()
+        runtime = self._create_runtime_with_id(
+            agent_id=agent_id,
+            config=config,
+            memory_dir_override=memory_dir,
+            restore_options=restore_options,
+        )
+        agent = Agent(runtime=runtime)
+        self._active_agents[agent_id] = agent
+        logger.info(f"Agent '{agent_id}' restored and stored successfully.")
+        return agent
+
     def get_agent(self, agent_id: str) -> Optional[Agent]:
         """Retrieves an active agent instance by its ID."""
         return self._active_agents.get(agent_id)

autobyteus/agent/handlers/__init__.py

@@ -14,6 +14,7 @@ from .tool_invocation_request_event_handler import ToolInvocationRequestEventHan
 from .tool_result_event_handler import ToolResultEventHandler
 from .approved_tool_invocation_event_handler import ApprovedToolInvocationEventHandler
 from .tool_execution_approval_event_handler import ToolExecutionApprovalEventHandler
+from .bootstrap_event_handler import BootstrapEventHandler
 
 # General Purpose and Lifecycle Handlers
 from .generic_event_handler import GenericEventHandler
@@ -31,6 +32,7 @@ __all__ = [
     "ToolResultEventHandler",
     "ApprovedToolInvocationEventHandler",
     "ToolExecutionApprovalEventHandler",
+    "BootstrapEventHandler",
     "GenericEventHandler",
     "LifecycleEventLogger", 
 ]

autobyteus/agent/handlers/approved_tool_invocation_event_handler.py

@@ -1,12 +1,13 @@
 # file: autobyteus/autobyteus/agent/handlers/approved_tool_invocation_event_handler.py
 import logging
-import json
+
 import traceback 
 from typing import TYPE_CHECKING, Optional 
 
 from autobyteus.agent.handlers.base_event_handler import AgentEventHandler
 from autobyteus.agent.events import ApprovedToolInvocationEvent, ToolResultEvent
 from autobyteus.agent.tool_invocation import ToolInvocation
+from autobyteus.utils.llm_output_formatter import format_to_clean_string
 
 if TYPE_CHECKING:
     from autobyteus.agent.context import AgentContext 
@@ -38,18 +39,38 @@ class ApprovedToolInvocationEventHandler(AgentEventHandler):
         agent_id = context.agent_id 
 
         notifier: Optional['AgentExternalEventNotifier'] = None
-        if context.phase_manager:
-            notifier = context.phase_manager.notifier
+        if context.status_manager:
+            notifier = context.status_manager.notifier
         
         if not notifier: # pragma: no cover
             logger.error(f"Agent '{agent_id}': Notifier not available in ApprovedToolInvocationEventHandler. Tool interaction logs will not be emitted.")
 
         logger.info(f"Agent '{agent_id}' handling ApprovedToolInvocationEvent for tool: '{tool_name}' (ID: {invocation_id}) with args: {arguments}")
 
-        try:
-            args_str = json.dumps(arguments)
-        except TypeError: # pragma: no cover
-            args_str = str(arguments) 
+        # Run tool invocation preprocessors before execution
+        processors = context.config.tool_invocation_preprocessors
+        if processors:
+            sorted_processors = sorted(processors, key=lambda p: p.get_order())
+            for processor in sorted_processors:
+                try:
+                    tool_invocation = await processor.process(tool_invocation, context)
+                    tool_name = tool_invocation.name
+                    arguments = tool_invocation.arguments
+                    invocation_id = tool_invocation.id
+                except Exception as e:
+                    error_message = f"Error in tool invocation preprocessor '{processor.get_name()}' for tool '{tool_name}': {e}"
+                    logger.error(f"Agent '{agent_id}': {error_message}", exc_info=True)
+                    result_event = ToolResultEvent(
+                        tool_name=tool_name,
+                        result=None,
+                        error=error_message,
+                        tool_invocation_id=invocation_id,
+                        turn_id=tool_invocation.turn_id,
+                    )
+                    await context.input_event_queues.enqueue_tool_result(result_event)
+                    return
+
+        args_str = format_to_clean_string(arguments) 
         log_msg_call = f"[APPROVED_TOOL_CALL] Agent_ID: {agent_id}, Tool: {tool_name}, Invocation_ID: {invocation_id}, Arguments: {args_str}"
         
         if notifier:
@@ -69,13 +90,13 @@ class ApprovedToolInvocationEventHandler(AgentEventHandler):
         if not tool_instance:
             error_message = f"Tool '{tool_name}' not found or configured for agent '{agent_id}'."
             logger.error(error_message)
-            result_event = ToolResultEvent(tool_name=tool_name, result=None, error=error_message, tool_invocation_id=invocation_id)
-            context.add_message_to_history({
-                "role": "tool",
-                "tool_call_id": invocation_id,
-                "name": tool_name,
-                "content": f"Error: Approved tool '{tool_name}' execution failed. Reason: {error_message}",
-            })
+            result_event = ToolResultEvent(
+                tool_name=tool_name,
+                result=None,
+                error=error_message,
+                tool_invocation_id=invocation_id,
+                turn_id=tool_invocation.turn_id,
+            )
             log_msg_error = f"[APPROVED_TOOL_ERROR] {error_message}"
             if notifier:
                 try:
@@ -94,21 +115,17 @@ class ApprovedToolInvocationEventHandler(AgentEventHandler):
                 logger.debug(f"Executing approved tool '{tool_name}' for agent '{agent_id}'. Invocation ID: {invocation_id}")
                 execution_result = await tool_instance.execute(context=context, **arguments)
                 
-                try:
-                    result_json_for_log = json.dumps(execution_result)
-                except (TypeError, ValueError): 
-                    result_json_for_log = json.dumps(str(execution_result))
+                result_json_for_log = format_to_clean_string(execution_result)
 
                 logger.info(f"Approved tool '{tool_name}' (ID: {invocation_id}) executed successfully by agent '{agent_id}'.")
-                result_event = ToolResultEvent(tool_name=tool_name, result=execution_result, error=None, tool_invocation_id=invocation_id)
-                
-                history_content = str(execution_result) 
-                context.add_message_to_history({
-                    "role": "tool",
-                    "tool_call_id": invocation_id,
-                    "name": tool_name,
-                    "content": history_content,
-                })
+                result_event = ToolResultEvent(
+                    tool_name=tool_name,
+                    result=execution_result,
+                    error=None,
+                    tool_invocation_id=invocation_id,
+                    tool_args=arguments,
+                    turn_id=tool_invocation.turn_id,
+                )
                 log_msg_result = f"[APPROVED_TOOL_RESULT] {result_json_for_log}"
                 if notifier:
                     try:
@@ -122,13 +139,13 @@ class ApprovedToolInvocationEventHandler(AgentEventHandler):
                 error_message = f"Error executing approved tool '{tool_name}' (ID: {invocation_id}): {str(e)}"
                 error_details = traceback.format_exc()
                 logger.error(f"Agent '{agent_id}' {error_message}", exc_info=True)
-                result_event = ToolResultEvent(tool_name=tool_name, result=None, error=error_message, tool_invocation_id=invocation_id)
-                context.add_message_to_history({
-                    "role": "tool",
-                    "tool_call_id": invocation_id,
-                    "name": tool_name,
-                    "content": f"Error: Approved tool '{tool_name}' execution failed. Reason: {error_message}",
-                })
+                result_event = ToolResultEvent(
+                    tool_name=tool_name,
+                    result=None,
+                    error=error_message,
+                    tool_invocation_id=invocation_id,
+                    turn_id=tool_invocation.turn_id,
+                )
                 log_msg_exception = f"[APPROVED_TOOL_EXCEPTION] {error_message}\nDetails:\n{error_details}"
                 if notifier:
                     try:

autobyteus/agent/handlers/bootstrap_event_handler.py

@@ -0,0 +1,155 @@
+# file: autobyteus/autobyteus/agent/handlers/bootstrap_event_handler.py
+import logging
+from typing import List, Optional, TYPE_CHECKING
+
+from autobyteus.agent.bootstrap_steps.agent_bootstrapper import AgentBootstrapper
+from autobyteus.agent.bootstrap_steps.base_bootstrap_step import BaseBootstrapStep
+from autobyteus.agent.events import (
+    AgentErrorEvent,
+    AgentReadyEvent,
+    BootstrapStartedEvent,
+    BootstrapStepRequestedEvent,
+    BootstrapStepCompletedEvent,
+    BootstrapCompletedEvent,
+)
+from autobyteus.agent.handlers.base_event_handler import AgentEventHandler
+
+if TYPE_CHECKING:
+    from autobyteus.agent.context import AgentContext
+
+logger = logging.getLogger(__name__)
+
+_BOOTSTRAP_STEPS_KEY = "_bootstrap_steps"
+
+
+class BootstrapEventHandler(AgentEventHandler):
+    """
+    Orchestrates the agent bootstrap sequence using internal lifecycle events.
+    """
+
+    def __init__(self, steps: Optional[List[BaseBootstrapStep]] = None) -> None:
+        self._bootstrapper = AgentBootstrapper(steps=steps)
+
+    async def handle(self, event: object, context: 'AgentContext') -> None:
+        if isinstance(event, BootstrapStartedEvent):
+            await self._handle_bootstrap_started(context)
+            return
+
+        if isinstance(event, BootstrapStepRequestedEvent):
+            await self._handle_bootstrap_step_requested(event, context)
+            return
+
+        if isinstance(event, BootstrapStepCompletedEvent):
+            await self._handle_bootstrap_step_completed(event, context)
+            return
+
+        if isinstance(event, BootstrapCompletedEvent):
+            await self._handle_bootstrap_completed(event, context)
+            return
+
+        logger.warning(f"BootstrapEventHandler received unexpected event type: {type(event).__name__}")
+
+    async def _handle_bootstrap_started(self, context: 'AgentContext') -> None:
+        steps = list(self._bootstrapper.bootstrap_steps)
+        context.state.custom_data[_BOOTSTRAP_STEPS_KEY] = steps
+
+        if not steps:
+            logger.info(f"Agent '{context.agent_id}': No bootstrap steps configured. Marking bootstrap complete.")
+            await context.input_event_queues.enqueue_internal_system_event(
+                BootstrapCompletedEvent(success=True)
+            )
+            return
+
+        logger.info(f"Agent '{context.agent_id}': Bootstrap started with {len(steps)} steps.")
+        await context.input_event_queues.enqueue_internal_system_event(
+            BootstrapStepRequestedEvent(step_index=0)
+        )
+
+    async def _handle_bootstrap_step_requested(self, event: BootstrapStepRequestedEvent, context: 'AgentContext') -> None:
+        steps: Optional[List[BaseBootstrapStep]] = context.state.custom_data.get(_BOOTSTRAP_STEPS_KEY)
+        if not steps:
+            error_message = "Bootstrap steps list missing from context during step request."
+            logger.error(f"Agent '{context.agent_id}': {error_message}")
+            await self._notify_bootstrap_error(context, error_message)
+            await context.input_event_queues.enqueue_internal_system_event(
+                BootstrapCompletedEvent(success=False, error_message=error_message)
+            )
+            return
+
+        step_index = event.step_index
+        if step_index < 0 or step_index >= len(steps):
+            error_message = f"Invalid bootstrap step index {step_index}."
+            logger.error(f"Agent '{context.agent_id}': {error_message}")
+            await self._notify_bootstrap_error(context, error_message)
+            await context.input_event_queues.enqueue_internal_system_event(
+                BootstrapCompletedEvent(success=False, error_message=error_message)
+            )
+            return
+
+        step = steps[step_index]
+        step_name = step.__class__.__name__
+        logger.debug(f"Agent '{context.agent_id}': Executing bootstrap step {step_index + 1}/{len(steps)}: {step_name}")
+
+        try:
+            success = await step.execute(context)
+        except Exception as e:  # pragma: no cover
+            error_message = f"Exception during bootstrap step '{step_name}': {e}"
+            logger.error(f"Agent '{context.agent_id}': {error_message}", exc_info=True)
+            success = False
+        if not success:
+            error_message = f"Bootstrap step '{step_name}' failed."
+            await self._notify_bootstrap_error(context, error_message)
+
+        await context.input_event_queues.enqueue_internal_system_event(
+            BootstrapStepCompletedEvent(
+                step_index=step_index,
+                step_name=step_name,
+                success=success,
+                error_message=None if success else f"Step '{step_name}' failed",
+            )
+        )
+
+    async def _handle_bootstrap_step_completed(self, event: BootstrapStepCompletedEvent, context: 'AgentContext') -> None:
+        if not event.success:
+            await context.input_event_queues.enqueue_internal_system_event(
+                BootstrapCompletedEvent(success=False, error_message=event.error_message)
+            )
+            return
+
+        steps: Optional[List[BaseBootstrapStep]] = context.state.custom_data.get(_BOOTSTRAP_STEPS_KEY)
+        if not steps:
+            error_message = "Bootstrap steps list missing during step completion."
+            logger.error(f"Agent '{context.agent_id}': {error_message}")
+            await self._notify_bootstrap_error(context, error_message)
+            await context.input_event_queues.enqueue_internal_system_event(
+                BootstrapCompletedEvent(success=False, error_message=error_message)
+            )
+            return
+
+        next_index = event.step_index + 1
+        if next_index < len(steps):
+            await context.input_event_queues.enqueue_internal_system_event(
+                BootstrapStepRequestedEvent(step_index=next_index)
+            )
+            return
+
+        await context.input_event_queues.enqueue_internal_system_event(
+            BootstrapCompletedEvent(success=True)
+        )
+
+    async def _handle_bootstrap_completed(self, event: BootstrapCompletedEvent, context: 'AgentContext') -> None:
+        if not event.success:
+            logger.error(
+                f"Agent '{context.agent_id}': Bootstrap completed with failure. "
+                f"Error: {event.error_message}"
+            )
+            await self._notify_bootstrap_error(context, event.error_message or "Bootstrap failed.")
+            return
+
+        logger.info(f"Agent '{context.agent_id}': Bootstrap completed successfully. Emitting AgentReadyEvent.")
+        await context.input_event_queues.enqueue_internal_system_event(AgentReadyEvent())
+
+    async def _notify_bootstrap_error(self, context: 'AgentContext', error_message: str) -> None:
+        await context.input_event_queues.enqueue_internal_system_event(
+            AgentErrorEvent(error_message=error_message, exception_details=error_message)
+        )

autobyteus/agent/handlers/inter_agent_message_event_handler.py

@@ -48,6 +48,16 @@ class InterAgentMessageReceivedEventHandler(AgentEventHandler):
             f"'{inter_agent_msg.sender_agent_id}', type '{inter_agent_msg.message_type.value}'. "
             f"Content: '{inter_agent_msg.content}'"
         )
+
+        # Surface this inter-agent message to external subscribers (UI, etc.)
+        if context.status_manager and context.status_manager.notifier:
+            notifier: 'AgentExternalEventNotifier' = context.status_manager.notifier
+            notifier.notify_agent_data_inter_agent_message_received({
+                "sender_agent_id": inter_agent_msg.sender_agent_id,
+                "recipient_role_name": inter_agent_msg.recipient_role_name,
+                "content": inter_agent_msg.content,
+                "message_type": inter_agent_msg.message_type.value,
+            })
         
         content_for_llm = (
             f"You have received a message from another agent.\n"