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

autobyteus/agent/message/send_message_to.py

@@ -2,149 +2,118 @@
 import logging
 from typing import TYPE_CHECKING, Any, Optional
 
-from autobyteus.agent.message.inter_agent_message import InterAgentMessage
 from autobyteus.tools.base_tool import BaseTool
-from autobyteus.agent.group.agent_group_context import AgentGroupContext
-# Updated imports for schema
+from autobyteus.tools.tool_category import ToolCategory
 from autobyteus.tools.parameter_schema import ParameterSchema, ParameterDefinition, ParameterType
-
+from autobyteus.tools.tool_config import ToolConfig
+# This import is for type hinting only and avoids circular dependencies at runtime
 if TYPE_CHECKING:
     from autobyteus.agent.context import AgentContext
-    from autobyteus.agent.agent import Agent 
+    from autobyteus.workflow.context.team_manager import TeamManager
+    from autobyteus.workflow.events.workflow_events import InterAgentMessageRequestEvent
 
 logger = logging.getLogger(__name__)
 
 class SendMessageTo(BaseTool):
     """
-    A tool for sending messages to other agents within the same AgentGroup.
-    It utilizes AgentGroupContext injected into the calling agent's AgentContext
-    to resolve recipient agents.
+    A tool for sending messages to other agents within the same workflow team.
+    This tool requires a TeamManager to be injected at runtime by the
+    workflow framework to enable communication with the parent orchestrator.
     """
-    TOOL_NAME = "SendMessageTo" # Class attribute for the name
+    TOOL_NAME = "SendMessageTo"
+    CATEGORY = ToolCategory.AGENT_COMMUNICATION
+
+    def __init__(self, config: Optional[ToolConfig] = None):
+        """
+        Initializes the SendMessageTo tool. The TeamManager is injected separately
+        after instantiation.
+        """
+        super().__init__(config=config)
+        self._team_manager: Optional['TeamManager'] = None
+        logger.debug("SendMessageTo tool initialized. TeamManager is not yet injected.")
 
-    def __init__(self):
-        super().__init__()
-        logger.debug(f"{self.get_name()} tool initialized.") # Use get_name()
+    def set_team_manager(self, team_manager: 'TeamManager'):
+        """Sets the TeamManager instance after the tool has been created."""
+        self._team_manager = team_manager
+        logger.debug(f"TeamManager was set on SendMessageTo instance post-creation.")
 
     @classmethod
-    def get_name(cls) -> str: # Implemented as per BaseTool requirement
+    def get_name(cls) -> str:
         return cls.TOOL_NAME
 
     @classmethod
     def get_description(cls) -> str:
-        return ("Sends a message to another agent within the same group. "
-                "Can target by role or specific agent ID.")
+        return ("Sends a message to another agent within the same team, starting them if necessary. "
+                "You must specify the recipient by their unique name as provided in your team manifest.")
 
     @classmethod
     def get_argument_schema(cls) -> Optional[ParameterSchema]:
         schema = ParameterSchema()
         schema.add_parameter(ParameterDefinition(
-            name="recipient_role_name",
+            name="recipient_name",
             param_type=ParameterType.STRING,
-            description="The general role name of the recipient agent (e.g., 'worker', 'reviewer').",
+            description='The unique name of the recipient agent (e.g., "Researcher", "Writer_1"). This MUST match a name from your team manifest.',
             required=True
         ))
         schema.add_parameter(ParameterDefinition(
             name="content",
             param_type=ParameterType.STRING,
-            description="The actual message text.",
+            description="The actual message content or task instruction.",
             required=True
         ))
         schema.add_parameter(ParameterDefinition(
             name="message_type",
-            param_type=ParameterType.STRING, # Or ENUM if InterAgentMessageType values are known and fixed for schema
+            param_type=ParameterType.STRING,
             description="Type of the message (e.g., TASK_ASSIGNMENT, CLARIFICATION). Custom types allowed.",
             required=True
         ))
-        schema.add_parameter(ParameterDefinition(
-            name="recipient_agent_id",
-            param_type=ParameterType.STRING,
-            description='Optional. Specific ID of the recipient agent. If "unknown" or omitted, resolves by role.',
-            required=False,
-            default_value=None # Explicitly no default, truly optional
-        ))
         return schema
 
-    # tool_usage_xml() and tool_usage_json() are inherited from BaseTool
-    # get_config_schema() for instantiation defaults to None
-
     async def _execute(self, 
                        context: 'AgentContext', 
-                       recipient_role_name: str, 
+                       recipient_name: str, 
                        content: str, 
-                       message_type: str, 
-                       recipient_agent_id: Optional[str] = None) -> str: # Named parameters
+                       message_type: str) -> str:
         """
-        Sends a message to another agent in the group.
-        Arguments are validated by BaseTool.execute().
+        Creates and dispatches a InterAgentMessageRequestEvent to the parent workflow
+        using the injected team_manager.
         """
-        sender_agent_id = context.agent_id
-        logger.info(f"Tool '{self.get_name()}': Sender '{sender_agent_id}' attempting to send message. "
-                    f"Recipient Role: '{recipient_role_name}', Recipient ID: '{recipient_agent_id}', Type: '{message_type}'.")
+        # Local import to break circular dependency at module load time.
+        from autobyteus.workflow.events.workflow_events import InterAgentMessageRequestEvent
 
-        group_context_any = context.custom_data.get('agent_group_context')
-        
-        if not isinstance(group_context_any, AgentGroupContext):
-            error_msg = f"Tool '{self.get_name()}' critical error: AgentGroupContext not found or invalid in AgentContext.custom_data for agent '{sender_agent_id}'. Cannot send message."
-            logger.error(error_msg)
+        if self._team_manager is None:
+            error_msg = "Critical error: SendMessageTo tool is not configured for workflow communication. It can only be used within a managed AgenticWorkflow."
+            logger.error(f"Agent '{context.agent_id}': {error_msg}")
             return f"Error: {error_msg}"
-        
-        group_context: AgentGroupContext = group_context_any # Type cast after check
 
-        target_agent: Optional['Agent'] = None
-
-        # Use recipient_agent_id if provided and not explicitly "unknown" (case-insensitive)
-        if recipient_agent_id and recipient_agent_id.lower() != "unknown":
-            target_agent = group_context.get_agent(recipient_agent_id)
-            if not target_agent:
-                logger.warning(f"Tool '{self.get_name()}': Agent with ID '{recipient_agent_id}' not found in group '{group_context.group_id}'. "
-                               f"Attempting to find by role '{recipient_role_name}'.")
-        
-        if not target_agent: 
-            agents_with_role = group_context.get_agents_by_role(recipient_role_name)
-            if not agents_with_role:
-                error_msg = f"No agent found with role '{recipient_role_name}' (and specific ID '{recipient_agent_id}' if provided was not found) in group '{group_context.group_id}'."
-                logger.error(f"Tool '{self.get_name()}': {error_msg}")
-                return f"Error: {error_msg}"
+        # --- Input Validation ---
+        if not isinstance(recipient_name, str) or not recipient_name.strip():
+            error_msg = "Error: `recipient_name` must be a non-empty string."
+            logger.error(f"Tool '{self.get_name()}' validation failed: {error_msg}")
+            return error_msg
+        if not isinstance(content, str) or not content.strip():
+            error_msg = "Error: `content` must be a non-empty string."
+            logger.error(f"Tool '{self.get_name()}' validation failed: {error_msg}")
+            return error_msg
+        if not isinstance(message_type, str) or not message_type.strip():
+            error_msg = "Error: `message_type` must be a non-empty string."
+            logger.error(f"Tool '{self.get_name()}' validation failed: {error_msg}")
+            return error_msg
             
-            if len(agents_with_role) > 1:
-                logger.warning(f"Tool '{self.get_name()}': Multiple agents ({len(agents_with_role)}) found for role '{recipient_role_name}'. "
-                               f"Sending to the first one: {agents_with_role[0].agent_id}. "
-                               "Consider using specific recipient_agent_id for clarity.")
-            target_agent = agents_with_role[0]
-            # Update recipient_agent_id to the one resolved by role if it was initially None or "unknown"
-            recipient_agent_id = target_agent.agent_id
-
-
-        if not target_agent: 
-            error_msg = f"Could not resolve recipient agent with role '{recipient_role_name}' or ID '{recipient_agent_id}'." # recipient_agent_id would be updated here
-            logger.error(f"Tool '{self.get_name()}': {error_msg}")
-            return f"Error: {error_msg}"
-
-        try:
-            message_to_send = InterAgentMessage.create_with_dynamic_message_type(
-                recipient_role_name=target_agent.context.config.role, 
-                recipient_agent_id=target_agent.agent_id, # Use the definitively resolved agent ID
-                content=content,
-                message_type=message_type,
-                sender_agent_id=sender_agent_id
-            )
-            
-            await target_agent.post_inter_agent_message(message_to_send)
-            success_msg = (f"Message successfully sent from '{sender_agent_id}' to agent "
-                           f"'{target_agent.agent_id}' (Role: '{target_agent.context.config.role}').")
-            logger.info(f"Tool '{self.get_name()}': {success_msg}")
-            return success_msg
-        except ValueError as ve: 
-            error_msg = f"Error creating message: {str(ve)}"
-            logger.error(f"Tool '{self.get_name()}': {error_msg}", exc_info=True)
-            return f"Error: {error_msg}"
-        except Exception as e:
-            error_msg = f"An unexpected error occurred while sending message: {str(e)}"
-            logger.error(f"Tool '{self.get_name()}': {error_msg}", exc_info=True)
-            return f"Error: {error_msg}"
+        sender_agent_id = context.agent_id
+        logger.info(f"Tool '{self.get_name()}': Agent '{sender_agent_id}' requesting to send message to '{recipient_name}'.")
+
+        # Create the event for the workflow to handle
+        event = InterAgentMessageRequestEvent(
+            sender_agent_id=sender_agent_id,
+            recipient_name=recipient_name,
+            content=content,
+            message_type=message_type
+        )
+        
+        # Dispatch the event "up" to the workflow's event loop via the team manager
+        await self._team_manager.dispatch_inter_agent_message_request(event)
 
-    # tool_usage_xml was defined directly here, this is now inherited from BaseTool
-    # BaseTool.tool_usage_xml() will use get_argument_schema() to generate it.
-    # If a custom XML format was desired that differs from the auto-generated one,
-    # then this method could be overridden. For now, assume auto-generated is fine.
+        success_msg = f"Message dispatch for recipient '{recipient_name}' has been successfully requested."
+        logger.info(f"Tool '{self.get_name()}': {success_msg}")
+        return success_msg

autobyteus/agent/phases/discover.py

@@ -3,7 +3,8 @@ import inspect
 import logging
 from typing import List, Optional
 
-from autobyteus.agent.context.agent_phase_manager import AgentPhaseManager
+from autobyteus.agent.phases.manager import AgentPhaseManager
+
 from .transition_info import PhaseTransitionInfo
 
 logger = logging.getLogger(__name__)

autobyteus/agent/runtime/agent_worker.py

@@ -15,6 +15,7 @@ from autobyteus.agent.events import (
 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
 
 if TYPE_CHECKING:
     from autobyteus.agent.context import AgentContext
@@ -176,41 +177,22 @@ class AgentWorker:
             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.")
+            # --- Shutdown sequence moved here, inside the original task's finally block ---
+            logger.info(f"AgentWorker '{agent_id}': Running shutdown sequence on worker loop.")
+            orchestrator = AgentShutdownOrchestrator()
+            cleanup_successful = await orchestrator.run(self.context)
 
-    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())
+            if not cleanup_successful:
+                logger.critical(f"AgentWorker '{agent_id}': Shutdown resource cleanup failed. The agent may not have shut down cleanly.")
+            else:
+                logger.info(f"AgentWorker '{agent_id}': Shutdown resource cleanup completed successfully.")
+            logger.info(f"AgentWorker '{agent_id}': Shutdown sequence completed.")
 
-    async def _shutdown_sequence(self):
-        """
-        The explicit, ordered shutdown sequence for the worker, executed on its own event loop.
-        """
-        agent_id = self.context.agent_id
-        logger.info(f"AgentWorker '{agent_id}': Running shutdown sequence on worker loop.")
-
-        # 1. Clean up resources like the LLM instance.
-        if self.context.llm_instance and hasattr(self.context.llm_instance, 'cleanup'):
-            logger.info(f"AgentWorker '{agent_id}': Running LLM instance cleanup.")
-            try:
-                cleanup_func = self.context.llm_instance.cleanup
-                if asyncio.iscoroutinefunction(cleanup_func):
-                    await cleanup_func()
-                else:
-                    cleanup_func()
-                logger.info(f"AgentWorker '{agent_id}': LLM instance cleanup completed.")
-            except Exception as e:
-                logger.error(f"AgentWorker '{agent_id}': Error during LLM instance cleanup: {e}", exc_info=True)
-
-        # 2. Signal the main event loop to stop.
-        await self._signal_internal_stop()
-        logger.info(f"AgentWorker '{agent_id}': Shutdown sequence completed.")
 
     async def stop(self, timeout: float = 10.0) -> None:
         """
-        Gracefully stops the worker by scheduling a final shutdown sequence on its
-        event loop, then waiting for the thread to terminate.
+        Gracefully stops the worker by signaling its event loop to terminate,
+        then waiting for the thread to complete its cleanup and exit.
         """
         if not self._is_active or self._stop_initiated:
             return
@@ -219,18 +201,27 @@ class AgentWorker:
         logger.info(f"AgentWorker '{agent_id}': Stop requested.")
         self._stop_initiated = True
 
-        # Schedule the explicit shutdown sequence on the worker's loop.
+        # Schedule a coroutine on the worker's loop to set the stop event.
         if self.get_worker_loop():
-            future = self.schedule_coroutine_on_worker_loop(self._shutdown_sequence)
+            def _coro_factory():
+                async def _signal_coro():
+                    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())
+                return _signal_coro()
+            
+            future = self.schedule_coroutine_on_worker_loop(_coro_factory)
             try:
-                # Wait for the cleanup and stop signal to be processed.
+                # Wait for the signal to be processed.
                 future.result(timeout=max(1.0, timeout-1))
             except Exception as e:
-                logger.error(f"AgentWorker '{agent_id}': Error during scheduled shutdown sequence: {e}", exc_info=True)
+                logger.error(f"AgentWorker '{agent_id}': Error signaling stop event: {e}", exc_info=True)
 
         # Wait for the main thread future to complete.
         if self._thread_future:
             try:
+                # FIX: Use asyncio.wait_for() to handle the timeout correctly.
                 await asyncio.wait_for(asyncio.wrap_future(self._thread_future), timeout=timeout)
                 logger.info(f"AgentWorker '{agent_id}': Worker thread has terminated.")
             except asyncio.TimeoutError:

autobyteus/agent/shutdown_steps/__init__.py

@@ -0,0 +1,17 @@
+# file: autobyteus/autobyteus/agent/shutdown_steps/__init__.py
+"""
+Defines individual, self-contained steps for the agent shutdown process.
+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 .agent_shutdown_orchestrator import AgentShutdownOrchestrator
+
+__all__ = [
+    "BaseShutdownStep",
+    "LLMInstanceCleanupStep",
+    "McpServerCleanupStep",
+    "AgentShutdownOrchestrator",
+]

autobyteus/agent/shutdown_steps/agent_shutdown_orchestrator.py

@@ -0,0 +1,63 @@
+# file: autobyteus/autobyteus/agent/shutdown_steps/agent_shutdown_orchestrator.py
+import logging
+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
+
+if TYPE_CHECKING:
+    from autobyteus.agent.context import AgentContext
+
+logger = logging.getLogger(__name__)
+
+class AgentShutdownOrchestrator:
+    """
+    Orchestrates the agent's shutdown process by executing a sequence of
+    self-contained cleanup steps.
+    """
+    def __init__(self, steps: Optional[List[BaseShutdownStep]] = None):
+        """
+        Initializes the AgentShutdownOrchestrator.
+
+        Args:
+            steps: An optional list of shutdown steps to execute. If not provided,
+                   a default sequence will be used.
+        """
+        if steps is None:
+            self.shutdown_steps: List[BaseShutdownStep] = [
+                LLMInstanceCleanupStep(),
+                McpServerCleanupStep(),
+            ]
+            logger.debug("AgentShutdownOrchestrator initialized with default steps.")
+        else:
+            self.shutdown_steps = steps
+            logger.debug(f"AgentShutdownOrchestrator initialized with {len(steps)} custom steps.")
+
+    async def run(self, context: 'AgentContext') -> bool:
+        """
+        Executes the configured sequence of shutdown steps.
+
+        Args:
+            context: The agent's context.
+
+        Returns:
+            True if all steps completed successfully, False otherwise.
+        """
+        agent_id = context.agent_id
+        logger.info(f"Agent '{agent_id}': AgentShutdownOrchestrator starting execution.")
+
+        for step_index, step_instance in enumerate(self.shutdown_steps):
+            step_name = step_instance.__class__.__name__
+            logger.debug(f"Agent '{agent_id}': Executing shutdown step {step_index + 1}/{len(self.shutdown_steps)}: {step_name}")
+            
+            success = await step_instance.execute(context)
+            
+            if not success:
+                error_message = f"Shutdown step {step_name} failed."
+                logger.error(f"Agent '{agent_id}': {error_message} Halting shutdown orchestration.")
+                # The step itself is responsible for detailed error logging.
+                return False
+
+        logger.info(f"Agent '{agent_id}': All shutdown steps completed successfully.")
+        return True

autobyteus/agent/shutdown_steps/base_shutdown_step.py

@@ -0,0 +1,33 @@
+# file: autobyteus/autobyteus/agent/shutdown_steps/base_shutdown_step.py
+import logging
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from autobyteus.agent.context import AgentContext
+
+logger = logging.getLogger(__name__)
+
+class BaseShutdownStep(ABC):
+    """
+    Abstract base class for individual steps in the agent shutdown process.
+    Each step is responsible for a specific part of the cleanup and
+    for reporting its success or failure.
+    """
+
+    @abstractmethod
+    async def execute(self, context: 'AgentContext') -> bool:
+        """
+        Executes the shutdown step.
+
+        Args:
+            context: The agent's context, providing access to state and resources.
+
+        Returns:
+            True if the step completed successfully, False otherwise.
+            If False, the step is expected to have handled its own detailed logging.
+        """
+        raise NotImplementedError("Subclasses must implement the 'execute' method.")
+
+    def __repr__(self) -> str:
+        return f"<{self.__class__.__name__}>"

autobyteus/agent/shutdown_steps/llm_instance_cleanup_step.py

@@ -0,0 +1,45 @@
+# file: autobyteus/autobyteus/agent/shutdown_steps/llm_instance_cleanup_step.py
+import asyncio
+import logging
+from typing import TYPE_CHECKING
+
+from .base_shutdown_step import BaseShutdownStep
+
+if TYPE_CHECKING:
+    from autobyteus.agent.context import AgentContext
+
+logger = logging.getLogger(__name__)
+
+class LLMInstanceCleanupStep(BaseShutdownStep):
+    """
+    Shutdown step for cleaning up the agent's LLM instance.
+    """
+    def __init__(self):
+        logger.debug("LLMInstanceCleanupStep initialized.")
+
+    async def execute(self, context: 'AgentContext') -> bool:
+        agent_id = context.agent_id
+        logger.info(f"Agent '{agent_id}': Executing LLMInstanceCleanupStep.")
+
+        llm_instance = context.llm_instance
+        if not llm_instance:
+            logger.debug(f"Agent '{agent_id}': No LLM instance found in context. Skipping cleanup.")
+            return True
+
+        if hasattr(llm_instance, 'cleanup') and callable(getattr(llm_instance, 'cleanup')):
+            try:
+                logger.info(f"Agent '{agent_id}': Running LLM instance cleanup for '{llm_instance.__class__.__name__}'.")
+                cleanup_func = llm_instance.cleanup
+                if asyncio.iscoroutinefunction(cleanup_func):
+                    await cleanup_func()
+                else:
+                    cleanup_func()
+                logger.info(f"Agent '{agent_id}': LLM instance cleanup completed successfully.")
+                return True
+            except Exception as e:
+                error_message = f"Agent '{agent_id}': Error during LLM instance cleanup: {e}"
+                logger.error(error_message, exc_info=True)
+                return False
+        else:
+            logger.debug(f"Agent '{agent_id}': LLM instance of type '{llm_instance.__class__.__name__}' does not have a 'cleanup' method. Skipping.")
+            return True

autobyteus/agent/shutdown_steps/mcp_server_cleanup_step.py

@@ -0,0 +1,32 @@
+# file: autobyteus/autobyteus/agent/shutdown_steps/mcp_server_cleanup_step.py
+import logging
+from typing import TYPE_CHECKING
+
+from .base_shutdown_step import BaseShutdownStep
+from autobyteus.tools.mcp.server_instance_manager import McpServerInstanceManager
+
+if TYPE_CHECKING:
+    from autobyteus.agent.context import AgentContext
+
+logger = logging.getLogger(__name__)
+
+class McpServerCleanupStep(BaseShutdownStep):
+    """
+    Shutdown step for cleaning up all MCP server instances associated with an agent.
+    """
+    def __init__(self):
+        self._instance_manager = McpServerInstanceManager()
+        logger.debug("McpServerCleanupStep initialized.")
+
+    async def execute(self, context: 'AgentContext') -> bool:
+        agent_id = context.agent_id
+        logger.info(f"Agent '{agent_id}': Executing McpServerCleanupStep.")
+
+        try:
+            await self._instance_manager.cleanup_mcp_server_instances_for_agent(agent_id)
+            logger.info(f"Agent '{agent_id}': MCP server instance cleanup completed successfully.")
+            return True
+        except Exception as e:
+            error_message = f"Agent '{agent_id}': Critical failure during McpServerCleanupStep: {e}"
+            logger.error(error_message, exc_info=True)
+            return False

autobyteus/agent/tool_execution_result_processor/__init__.py

@@ -0,0 +1,9 @@
+# file: autobyteus/autobyteus/agent/tool_execution_result_processor/__init__.py
+"""
+Components for processing tool execution results before they are sent to the LLM.
+"""
+from .base_processor import BaseToolExecutionResultProcessor
+
+__all__ = [
+    "BaseToolExecutionResultProcessor",
+]

autobyteus/agent/tool_execution_result_processor/base_processor.py

@@ -0,0 +1,46 @@
+# file: autobyteus/autobyteus/agent/tool_execution_result_processor/base_processor.py
+import logging
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+from .processor_meta import ToolExecutionResultProcessorMeta
+
+if TYPE_CHECKING:
+    from autobyteus.agent.context import AgentContext
+    from autobyteus.agent.events import ToolResultEvent
+
+logger = logging.getLogger(__name__)
+
+class BaseToolExecutionResultProcessor(ABC, metaclass=ToolExecutionResultProcessorMeta):
+    """
+    Abstract base class for processors that can modify a tool's execution result.
+    These processors are applied after a tool runs but before its result is formatted
+    for the LLM.
+    """
+
+    @classmethod
+    def get_name(cls) -> str:
+        """
+        Returns the unique registration name for this processor.
+        Defaults to the class name.
+        """
+        return cls.__name__
+
+    @abstractmethod
+    async def process(self,
+                      event: 'ToolResultEvent',
+                      context: 'AgentContext') -> 'ToolResultEvent':
+        """
+        Processes the given ToolResultEvent.
+
+        Args:
+            event: The ToolResultEvent containing the tool's output or error.
+            context: The agent's context, providing access to config and state.
+
+        Returns:
+            The processed (potentially modified) ToolResultEvent.
+        """
+        raise NotImplementedError("Subclasses must implement the 'process' method.")
+
+    def __repr__(self) -> str:
+        return f"<{self.__class__.__name__}>"

autobyteus/agent/tool_execution_result_processor/processor_definition.py

@@ -0,0 +1,36 @@
+# file: autobyteus/autobyteus/agent/tool_execution_result_processor/processor_definition.py
+import logging
+from typing import Type, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .base_processor import BaseToolExecutionResultProcessor
+
+logger = logging.getLogger(__name__)
+
+class ToolExecutionResultProcessorDefinition:
+    """
+    Represents the definition of a tool execution result processor.
+    Contains its registered name and the class itself.
+    """
+    def __init__(self, name: str, processor_class: Type['BaseToolExecutionResultProcessor']):
+        """
+        Initializes the ToolExecutionResultProcessorDefinition.
+
+        Args:
+            name: The unique registered name of the processor.
+            processor_class: The class of the tool execution result processor.
+
+        Raises:
+            ValueError: If name is empty or processor_class is not a type.
+        """
+        if not name or not isinstance(name, str):
+            raise ValueError("Tool Execution Result Processor name must be a non-empty string.")
+        if not isinstance(processor_class, type):
+            raise ValueError("processor_class must be a class type.")
+        
+        self.name: str = name
+        self.processor_class: Type['BaseToolExecutionResultProcessor'] = processor_class
+        logger.debug(f"ToolExecutionResultProcessorDefinition created: name='{name}', class='{processor_class.__name__}'.")
+
+    def __repr__(self) -> str:
+        return f"<ToolExecutionResultProcessorDefinition name='{self.name}', class='{self.processor_class.__name__}'>"

autobyteus/agent/tool_execution_result_processor/processor_meta.py

@@ -0,0 +1,36 @@
+# file: autobyteus/autobyteus/agent/tool_execution_result_processor/processor_meta.py
+import logging
+from abc import ABCMeta
+
+from .processor_registry import default_tool_execution_result_processor_registry
+from .processor_definition import ToolExecutionResultProcessorDefinition
+
+logger = logging.getLogger(__name__)
+
+class ToolExecutionResultProcessorMeta(ABCMeta):
+    """
+    Metaclass for BaseToolExecutionResultProcessor that automatically registers
+    concrete processor subclasses with the default registry.
+    """
+    def __init__(cls, name, bases, dct):
+        super().__init__(name, bases, dct)
+
+        if name == 'BaseToolExecutionResultProcessor' or getattr(cls, "__abstractmethods__", None):
+            logger.debug(f"Skipping registration for abstract tool execution result processor class: {name}")
+            return
+
+        try:
+            processor_name = cls.get_name()
+
+            if not processor_name or not isinstance(processor_name, str):
+                logger.error(f"Tool execution result processor class {name} must return a valid string from get_name(). Skipping.")
+                return
+            
+            definition = ToolExecutionResultProcessorDefinition(name=processor_name, processor_class=cls)
+            default_tool_execution_result_processor_registry.register_processor(definition)
+            logger.info(f"Auto-registered tool execution result processor: '{processor_name}' from class {name}.")
+
+        except AttributeError as e:
+            logger.error(f"Tool execution result processor class {name} is missing 'get_name' method ({e}). Skipping registration.")
+        except Exception as e:
+            logger.error(f"Failed to auto-register tool execution result processor class {name}: {e}", exc_info=True)