autobyteus 1.1.7__py3-none-any.whl → 1.1.9__py3-none-any.whl

autobyteus/agent/bootstrap_steps/system_prompt_processing_step.py

@@ -45,8 +45,12 @@ class SystemPromptProcessingStep(BaseBootstrapStep):
             if not processor_instances:
                 logger.debug(f"Agent '{agent_id}': No system prompt processors configured. Using system prompt as is.")
             else:
-                logger.debug(f"Agent '{agent_id}': Found {len(processor_instances)} configured system prompt processors. Applying sequentially.")
-                for processor_instance in processor_instances:
+                # Sort processors by their order attribute
+                sorted_processors = sorted(processor_instances, key=lambda p: p.get_order())
+                processor_names = [p.get_name() for p in sorted_processors]
+                logger.debug(f"Agent '{agent_id}': Found {len(sorted_processors)} configured system prompt processors. Applying sequentially in order: {processor_names}")
+
+                for processor_instance in sorted_processors:
                     if not isinstance(processor_instance, BaseSystemPromptProcessor):
                         error_message = f"Agent '{agent_id}': Invalid system prompt processor configuration type: {type(processor_instance)}. Expected BaseSystemPromptProcessor."
                         logger.error(error_message)

autobyteus/agent/handlers/inter_agent_message_event_handler.py

@@ -3,10 +3,10 @@ import logging
 from typing import TYPE_CHECKING
 
 from autobyteus.agent.handlers.base_event_handler import AgentEventHandler
-from autobyteus.agent.events import InterAgentMessageReceivedEvent, LLMUserMessageReadyEvent 
+from autobyteus.agent.events import InterAgentMessageReceivedEvent, UserMessageReceivedEvent
 from autobyteus.agent.message.inter_agent_message import InterAgentMessage
-from autobyteus.llm.user_message import LLMUserMessage
-from autobyteus.agent.sender_type import TASK_NOTIFIER_SENDER_ID # New import
+from autobyteus.agent.message.agent_input_user_message import AgentInputUserMessage
+from autobyteus.agent.sender_type import SenderType
 
 if TYPE_CHECKING:
     from autobyteus.agent.context import AgentContext 
@@ -17,7 +17,8 @@ logger = logging.getLogger(__name__)
 class InterAgentMessageReceivedEventHandler(AgentEventHandler):
     """
     Handles InterAgentMessageReceivedEvents by formatting the InterAgentMessage
-    into an LLMUserMessage and enqueuing an LLMUserMessageReadyEvent for LLM processing.
+    into an AgentInputUserMessage and enqueuing a UserMessageReceivedEvent to route
+    it through the main input processing pipeline.
     """
 
     def __init__(self):
@@ -47,10 +48,6 @@ class InterAgentMessageReceivedEventHandler(AgentEventHandler):
             f"'{inter_agent_msg.sender_agent_id}', type '{inter_agent_msg.message_type.value}'. "
             f"Content: '{inter_agent_msg.content}'"
         )
-
-        # This handler now only deals with messages from other agents, not the system notifier.
-        # The logic for system task notifications has been moved to UserInputMessageEventHandler
-        # by checking the message metadata.
         
         content_for_llm = (
             f"You have received a message from another agent.\n"
@@ -63,19 +60,20 @@ class InterAgentMessageReceivedEventHandler(AgentEventHandler):
             f"Please process this information and act accordingly."
         )
         
-        context.state.add_message_to_history({
-            "role": "user", 
-            "content": content_for_llm,
-            "sender_agent_id": inter_agent_msg.sender_agent_id, 
-            "original_message_type": inter_agent_msg.message_type.value
-        })
-
-        llm_user_message = LLMUserMessage(content=content_for_llm)
+        # --- REFACTORED: Route through the main input pipeline ---
+        agent_input_user_message = AgentInputUserMessage(
+            content=content_for_llm,
+            sender_type=SenderType.AGENT,
+            metadata={
+                "sender_agent_id": inter_agent_msg.sender_agent_id,
+                "original_message_type": inter_agent_msg.message_type.value
+            }
+        )
         
-        llm_user_message_ready_event = LLMUserMessageReadyEvent(llm_user_message=llm_user_message) 
-        await context.input_event_queues.enqueue_internal_system_event(llm_user_message_ready_event)
+        user_message_received_event = UserMessageReceivedEvent(agent_input_user_message=agent_input_user_message) 
+        await context.input_event_queues.enqueue_user_message(user_message_received_event)
         
         logger.info(
             f"Agent '{context.agent_id}' processed InterAgentMessage from sender '{inter_agent_msg.sender_agent_id}' "
-            f"and enqueued LLMUserMessageReadyEvent."
+            f"and enqueued UserMessageReceivedEvent to route through input pipeline."
         )

autobyteus/agent/handlers/llm_complete_response_received_event_handler.py

@@ -63,9 +63,12 @@ class LLMCompleteResponseReceivedEventHandler(AgentEventHandler):
                     f"Proceeding to treat LLM response as output for this leg."
                 )
             else:
-                processor_names = [p.get_name() for p in processor_instances_to_try]
-                logger.debug(f"Agent '{agent_id}': Attempting LLM response processing with: {processor_names}")
-                for processor_instance in processor_instances_to_try:
+                # Sort processors by their order attribute
+                sorted_processors = sorted(processor_instances_to_try, key=lambda p: p.get_order())
+                processor_names = [p.get_name() for p in sorted_processors]
+                logger.debug(f"Agent '{agent_id}': Attempting LLM response processing in order: {processor_names}")
+
+                for processor_instance in sorted_processors:
                     processor_name_for_log: str = "unknown"
                     try:
                         if not isinstance(processor_instance, BaseLLMResponseProcessor):

autobyteus/agent/handlers/tool_result_event_handler.py

@@ -4,9 +4,11 @@ import json
 from typing import TYPE_CHECKING, Optional, List
 
 from autobyteus.agent.handlers.base_event_handler import AgentEventHandler 
-from autobyteus.agent.events import ToolResultEvent, LLMUserMessageReadyEvent 
-from autobyteus.llm.user_message import LLMUserMessage 
+from autobyteus.agent.events import ToolResultEvent, UserMessageReceivedEvent
 from autobyteus.agent.tool_execution_result_processor import BaseToolExecutionResultProcessor
+from autobyteus.agent.message.context_file import ContextFile
+from autobyteus.agent.message import AgentInputUserMessage
+from autobyteus.agent.sender_type import SenderType
 
 if TYPE_CHECKING:
     from autobyteus.agent.context import AgentContext 
@@ -16,34 +18,68 @@ logger = logging.getLogger(__name__)
 
 class ToolResultEventHandler(AgentEventHandler):
     """
-    Handles ToolResultEvents. It immediately processes and notifies for each
-    individual tool result. If a multi-tool call turn is active, it accumulates
-    these processed results until the turn is complete, then sends a single
-    aggregated message to the LLM.
+    Handles ToolResultEvents. It processes and notifies for each individual tool
+    result as it arrives. If a multi-tool call turn is active, it accumulates
+    these results until the turn is complete, re-orders them to match the original
+    invocation sequence, and then sends a single aggregated message to the LLM
+    by enqueuing a UserMessageReceivedEvent.
+    
+    This handler is now "media-aware": if a tool's result is a `ContextFile`
+    object, it will be added as multimodal context to the next LLM call rather
+    than as plain text.
     """
     def __init__(self):
         logger.info("ToolResultEventHandler initialized.")
 
-    async def _dispatch_aggregated_results_to_llm(self,
+    async def _dispatch_results_to_input_pipeline(self,
                                                   processed_events: List[ToolResultEvent],
                                                   context: 'AgentContext'):
         """
-        Aggregates a list of PRE-PROCESSED tool results into a single message and
-        dispatches it to the LLM.
+        Aggregates a list of PRE-PROCESSED and ORDERED tool results into a single
+        AgentInputUserMessage and dispatches it into the main input processing pipeline
+        by enqueuing a UserMessageReceivedEvent.
         """
         agent_id = context.agent_id
         
-        # --- Aggregate results into a single message ---
-        aggregated_content_parts = []
+        # --- NEW: Separate text results from media context results ---
+        aggregated_content_parts: List[str] = []
+        media_context_files: List[ContextFile] = []
+
         for p_event in processed_events:
             tool_invocation_id = p_event.tool_invocation_id if p_event.tool_invocation_id else 'N/A'
-            content_part: str
+            
+            # Check if the result is a ContextFile or a list of them
+            result_is_media = False
+            if isinstance(p_event.result, ContextFile):
+                media_context_files.append(p_event.result)
+                aggregated_content_parts.append(
+                    f"Tool: {p_event.tool_name} (ID: {tool_invocation_id})\n"
+                    f"Status: Success\n"
+                    f"Result: The file '{p_event.result.file_name}' has been loaded into the context for you to view."
+                )
+                result_is_media = True
+            elif isinstance(p_event.result, list) and all(isinstance(item, ContextFile) for item in p_event.result):
+                media_context_files.extend(p_event.result)
+                file_names = [cf.file_name for cf in p_event.result if cf.file_name]
+                aggregated_content_parts.append(
+                    f"Tool: {p_event.tool_name} (ID: {tool_invocation_id})\n"
+                    f"Status: Success\n"
+                    f"Result: The following files have been loaded into the context for you to view: {file_names}"
+                )
+                result_is_media = True
+
+            if result_is_media:
+                continue
+
+            # Handle errors
             if p_event.error:
                 content_part = (
                     f"Tool: {p_event.tool_name} (ID: {tool_invocation_id})\n"
                     f"Status: Error\n"
                     f"Details: {p_event.error}"
                 )
+                aggregated_content_parts.append(content_part)
+            # Handle standard text/JSON results
             else:
                 try:
                     result_str = json.dumps(p_event.result, indent=2) if not isinstance(p_event.result, str) else p_event.result
@@ -54,20 +90,26 @@ class ToolResultEventHandler(AgentEventHandler):
                     f"Status: Success\n"
                     f"Result:\n{result_str}" 
                 )
-            aggregated_content_parts.append(content_part)
+                aggregated_content_parts.append(content_part)
 
         final_content_for_llm = (
             "The following tool executions have completed. Please analyze their results and decide the next course of action.\n\n"
             + "\n\n---\n\n".join(aggregated_content_parts)
         )
         
-        logger.debug(f"Agent '{agent_id}' preparing aggregated message for LLM:\n---\n{final_content_for_llm}\n---")
-        llm_user_message = LLMUserMessage(content=final_content_for_llm)
+        logger.debug(f"Agent '{agent_id}' preparing aggregated message from tool results for input pipeline:\n---\n{final_content_for_llm}\n---")
+        
+        # --- REFACTORED: Create an AgentInputUserMessage and route it through the standard input pipeline ---
+        agent_input_user_message = AgentInputUserMessage(
+            content=final_content_for_llm,
+            sender_type=SenderType.TOOL,
+            context_files=media_context_files
+        )
         
-        next_event = LLMUserMessageReadyEvent(llm_user_message=llm_user_message) 
-        await context.input_event_queues.enqueue_internal_system_event(next_event)
+        next_event = UserMessageReceivedEvent(agent_input_user_message=agent_input_user_message)
+        await context.input_event_queues.enqueue_user_message(next_event)
         
-        logger.info(f"Agent '{agent_id}' enqueued LLMUserMessageReadyEvent with aggregated results from {len(processed_events)} tool(s).")
+        logger.info(f"Agent '{agent_id}' enqueued UserMessageReceivedEvent with aggregated results from {len(processed_events)} tool(s) and {len(media_context_files)} media file(s).")
 
 
     async def handle(self,
@@ -84,7 +126,9 @@ class ToolResultEventHandler(AgentEventHandler):
         processed_event = event
         processor_instances = context.config.tool_execution_result_processors
         if processor_instances:
-            for processor_instance in processor_instances:
+            # Sort processors by their order attribute
+            sorted_processors = sorted(processor_instances, key=lambda p: p.get_order())
+            for processor_instance in sorted_processors:
                 if not isinstance(processor_instance, BaseToolExecutionResultProcessor):
                     logger.error(f"Agent '{agent_id}': Invalid tool result processor type: {type(processor_instance)}. Skipping.")
                     continue
@@ -119,7 +163,7 @@ class ToolResultEventHandler(AgentEventHandler):
         # Case 1: Not a multi-tool call turn, dispatch to LLM immediately.
         if not active_turn:
             logger.info(f"Agent '{agent_id}' handling single ToolResultEvent from tool: '{processed_event.tool_name}'.")
-            await self._dispatch_aggregated_results_to_llm([processed_event], context)
+            await self._dispatch_results_to_input_pipeline([processed_event], context)
             return
 
         # Case 2: Multi-tool call turn is active, accumulate results.
@@ -133,9 +177,28 @@ class ToolResultEventHandler(AgentEventHandler):
         if not active_turn.is_complete():
             return
             
-        # If all results are in, dispatch them to the LLM and clean up the turn state.
-        logger.info(f"Agent '{agent_id}': All tool results for the turn collected. Aggregating for LLM.")
-        await self._dispatch_aggregated_results_to_llm(active_turn.results, context)
+        # If all results are in, re-order them and then dispatch to the LLM.
+        logger.info(f"Agent '{agent_id}': All tool results for the turn collected. Re-ordering to match invocation sequence.")
+        
+        # --- NEW RE-ORDERING LOGIC ---
+        results_by_id = {res.tool_invocation_id: res for res in active_turn.results}
+        sorted_results: List[ToolResultEvent] = []
+        for original_invocation in active_turn.invocations:
+            result = results_by_id.get(original_invocation.id)
+            if result:
+                sorted_results.append(result)
+            else:
+                # This should not happen if the logic is correct, but it's a good safeguard.
+                logger.error(f"Agent '{agent_id}': Missing result for invocation ID '{original_invocation.id}' during re-ordering.")
+                # Add a synthetic error result to maintain sequence length.
+                sorted_results.append(ToolResultEvent(
+                    tool_name=original_invocation.name,
+                    result=None,
+                    error=f"Critical Error: Result for this tool call was lost.",
+                    tool_invocation_id=original_invocation.id
+                ))
+
+        await self._dispatch_results_to_input_pipeline(sorted_results, context)
         
         context.state.active_multi_tool_call_turn = None
         logger.info(f"Agent '{agent_id}': Multi-tool call turn state has been cleared.")

autobyteus/agent/handlers/user_input_message_event_handler.py

@@ -1,5 +1,6 @@
 # file: autobyteus/autobyteus/agent/handlers/user_input_message_event_handler.py
 import logging
+import copy
 from typing import TYPE_CHECKING
 
 from autobyteus.agent.handlers.base_event_handler import AgentEventHandler
@@ -7,6 +8,7 @@ from autobyteus.agent.events import UserMessageReceivedEvent, LLMUserMessageRead
 from autobyteus.agent.message.agent_input_user_message import AgentInputUserMessage
 from autobyteus.agent.input_processor import BaseAgentUserInputMessageProcessor
 from autobyteus.agent.message.multimodal_message_builder import build_llm_user_message
+from autobyteus.agent.sender_type import SenderType
 
 
 if TYPE_CHECKING:
@@ -35,27 +37,34 @@ class UserInputMessageEventHandler(AgentEventHandler):
 
         original_agent_input_user_msg: AgentInputUserMessage = event.agent_input_user_message
 
-        # --- NEW LOGIC: Check metadata for system-generated tasks and notify TUI ---
-        if original_agent_input_user_msg.metadata.get('source') == 'system_task_notifier':
+        # --- UPDATED LOGIC: Check sender_type for system-generated tasks and notify TUI ---
+        if original_agent_input_user_msg.sender_type == SenderType.SYSTEM:
             if context.phase_manager:
                 notifier: 'AgentExternalEventNotifier' = context.phase_manager.notifier
                 notification_data = {
-                    "sender_id": "system.task_notifier",
+                    "sender_id": original_agent_input_user_msg.metadata.get("sender_id", "system"),
                     "content": original_agent_input_user_msg.content,
                 }
                 notifier.notify_agent_data_system_task_notification_received(notification_data)
-                logger.info(f"Agent '{context.agent_id}' emitted system task notification for TUI.")
-        # --- END NEW LOGIC ---
+                logger.info(f"Agent '{context.agent_id}' emitted system task notification for TUI based on SYSTEM sender_type.")
+        # --- END UPDATED LOGIC ---
 
-        processed_agent_input_user_msg: AgentInputUserMessage = original_agent_input_user_msg
+        # Create a deep copy of the message to pass through the processor chain.
+        # This prevents in-place mutation of the original event's message object,
+        # ensuring that processors like UserInputPersistenceProcessor can access
+        # the true original content via the triggering_event.
+        processed_agent_input_user_msg = copy.deepcopy(original_agent_input_user_msg)
 
-        logger.info(f"Agent '{context.agent_id}' handling UserMessageReceivedEvent: '{original_agent_input_user_msg.content}'")
+        logger.info(f"Agent '{context.agent_id}' handling UserMessageReceivedEvent (type: {original_agent_input_user_msg.sender_type.value}): '{original_agent_input_user_msg.content}'")
 
         processor_instances = context.config.input_processors
         if processor_instances:
-            processor_names = [p.get_name() for p in processor_instances]
-            logger.debug(f"Agent '{context.agent_id}': Applying input processors: {processor_names}")
-            for processor_instance in processor_instances:
+            # Sort processors by their order attribute
+            sorted_processors = sorted(processor_instances, key=lambda p: p.get_order())
+            processor_names = [p.get_name() for p in sorted_processors]
+            logger.debug(f"Agent '{context.agent_id}': Applying input processors in order: {processor_names}")
+            
+            for processor_instance in sorted_processors:
                 processor_name_for_log = "unknown"
                 try:
                     if not isinstance(processor_instance, BaseAgentUserInputMessageProcessor):

autobyteus/agent/hooks/base_phase_hook.py

@@ -29,6 +29,23 @@ class BasePhaseHook(ABC, metaclass=PhaseHookMeta):
         """
         return cls.__name__
 
+    @classmethod
+    def get_order(cls) -> int:
+        """
+        Returns the execution order for this hook if multiple hooks are triggered
+        on the same transition. Lower numbers execute earlier.
+        Defaults to 500 (normal priority).
+        """
+        return 500
+
+    @classmethod
+    def is_mandatory(cls) -> bool:
+        """
+        Returns True if this hook is mandatory for the agent to function correctly.
+        Defaults to False (optional).
+        """
+        return False
+
     @property
     @abstractmethod
     def source_phase(self) -> AgentOperationalPhase:

autobyteus/agent/hooks/hook_registry.py

@@ -3,6 +3,7 @@ import logging
 from typing import TYPE_CHECKING, Dict, List, Optional
 
 from autobyteus.utils.singleton import SingletonMeta
+from autobyteus.agent.processor_option import HookOption
 from .hook_definition import PhaseHookDefinition
 
 if TYPE_CHECKING:
@@ -24,14 +25,6 @@ class PhaseHookRegistry(metaclass=SingletonMeta):
     def register_hook(self, definition: PhaseHookDefinition) -> None:
         """
         Registers a phase hook definition.
-        If a definition with the same name already exists, it will be overwritten,
-        and a warning will be logged.
-
-        Args:
-            definition: The PhaseHookDefinition object to register.
-
-        Raises:
-            TypeError: If the definition is not an instance of PhaseHookDefinition.
         """
         if not isinstance(definition, PhaseHookDefinition):
             raise TypeError(f"Expected PhaseHookDefinition instance, got {type(definition).__name__}.")
@@ -46,12 +39,6 @@ class PhaseHookRegistry(metaclass=SingletonMeta):
     def get_hook_definition(self, name: str) -> Optional[PhaseHookDefinition]:
         """
         Retrieves a phase hook definition by its name.
-
-        Args:
-            name: The name of the phase hook definition to retrieve.
-
-        Returns:
-            The PhaseHookDefinition object if found, otherwise None.
         """
         if not isinstance(name, str):
             logger.warning(f"Attempted to retrieve hook definition with non-string name: {type(name).__name__}.")
@@ -64,12 +51,6 @@ class PhaseHookRegistry(metaclass=SingletonMeta):
     def get_hook(self, name: str) -> Optional['BasePhaseHook']:
         """
         Retrieves an instance of a phase hook by its name.
-
-        Args:
-            name: The name of the phase hook to retrieve.
-
-        Returns:
-            An instance of the BasePhaseHook if found and instantiable, otherwise None.
         """
         definition = self.get_hook_definition(name)
         if definition:
@@ -82,19 +63,26 @@ class PhaseHookRegistry(metaclass=SingletonMeta):
 
     def list_hook_names(self) -> List[str]:
         """
-        Returns a list of names of all registered phase hook definitions.
-
-        Returns:
-            A list of strings, where each string is a registered hook name.
+        Returns an unordered list of names of all registered phase hook definitions.
         """
         return list(self._definitions.keys())
 
+    def get_ordered_hook_options(self) -> List[HookOption]:
+        """
+        Returns a list of HookOption objects, sorted by their execution order.
+        """
+        definitions = list(self._definitions.values())
+        sorted_definitions = sorted(definitions, key=lambda d: d.hook_class.get_order())
+        return [
+            HookOption(
+                name=d.name,
+                is_mandatory=d.hook_class.is_mandatory()
+            ) for d in sorted_definitions
+        ]
+
     def get_all_definitions(self) -> Dict[str, PhaseHookDefinition]:
         """
         Returns a shallow copy of the dictionary containing all registered phase hook definitions.
-
-        Returns:
-            A dictionary where keys are hook names and values are PhaseHookDefinition objects.
         """
         return dict(self._definitions)
 

autobyteus/agent/input_processor/base_user_input_processor.py

@@ -28,6 +28,22 @@ class BaseAgentUserInputMessageProcessor(ABC, metaclass=AgentUserInputMessagePro
         """
         return cls.__name__
 
+    @classmethod
+    def get_order(cls) -> int:
+        """
+        Returns the execution order for this processor. Lower numbers execute earlier.
+        Defaults to 500 (normal priority).
+        """
+        return 500
+
+    @classmethod
+    def is_mandatory(cls) -> bool:
+        """
+        Returns True if this processor is mandatory for the agent to function correctly.
+        Defaults to False (optional).
+        """
+        return False
+
     @abstractmethod
     async def process(self,
                       message: 'AgentInputUserMessage', 
@@ -51,4 +67,4 @@ class BaseAgentUserInputMessageProcessor(ABC, metaclass=AgentUserInputMessagePro
         raise NotImplementedError("Subclasses must implement the 'process' method.")
 
     def __repr__(self) -> str:
-        return f"<{self.__class__.__name__}>"
+        return f"&lt;{self.__class__.__name__}&gt;"

autobyteus/agent/input_processor/processor_registry.py

@@ -3,6 +3,7 @@ import logging
 from typing import TYPE_CHECKING, Dict, List, Optional, Type
 
 from autobyteus.utils.singleton import SingletonMeta
+from autobyteus.agent.processor_option import ProcessorOption
 from .processor_definition import AgentUserInputMessageProcessorDefinition
 if TYPE_CHECKING:
     from .base_user_input_processor import BaseAgentUserInputMessageProcessor
@@ -23,14 +24,6 @@ class AgentUserInputMessageProcessorRegistry(metaclass=SingletonMeta):
     def register_processor(self, definition: AgentUserInputMessageProcessorDefinition) -> None:
         """
         Registers an input processor definition.
-        If a definition with the same name already exists, it will be overwritten,
-        and a warning will be logged.
-
-        Args:
-            definition: The AgentUserInputMessageProcessorDefinition object to register.
-
-        Raises:
-            ValueError: If the definition is not an instance of AgentUserInputMessageProcessorDefinition.
         """
         if not isinstance(definition, AgentUserInputMessageProcessorDefinition):
             raise TypeError(f"Expected AgentUserInputMessageProcessorDefinition instance, got {type(definition).__name__}.")
@@ -45,12 +38,6 @@ class AgentUserInputMessageProcessorRegistry(metaclass=SingletonMeta):
     def get_processor_definition(self, name: str) -> Optional[AgentUserInputMessageProcessorDefinition]:
         """
         Retrieves an input processor definition by its name.
-
-        Args:
-            name: The name of the input processor definition to retrieve.
-
-        Returns:
-            The AgentUserInputMessageProcessorDefinition object if found, otherwise None.
         """
         if not isinstance(name, str):
             logger.warning(f"Attempted to retrieve input processor definition with non-string name: {type(name).__name__}.")
@@ -63,12 +50,6 @@ class AgentUserInputMessageProcessorRegistry(metaclass=SingletonMeta):
     def get_processor(self, name: str) -> Optional['BaseAgentUserInputMessageProcessor']:
         """
         Retrieves an instance of an input processor by its name.
-
-        Args:
-            name: The name of the input processor to retrieve.
-
-        Returns:
-            An instance of the BaseAgentUserInputMessageProcessor if found and instantiable, otherwise None.
         """
         definition = self.get_processor_definition(name)
         if definition:
@@ -81,19 +62,26 @@ class AgentUserInputMessageProcessorRegistry(metaclass=SingletonMeta):
 
     def list_processor_names(self) -> List[str]:
         """
-        Returns a list of names of all registered input processor definitions.
-
-        Returns:
-            A list of strings, where each string is a registered processor name.
+        Returns an unordered list of names of all registered input processor definitions.
         """
         return list(self._definitions.keys())
 
+    def get_ordered_processor_options(self) -> List[ProcessorOption]:
+        """
+        Returns a list of ProcessorOption objects, sorted by their execution order.
+        """
+        definitions = list(self._definitions.values())
+        sorted_definitions = sorted(definitions, key=lambda d: d.processor_class.get_order())
+        return [
+            ProcessorOption(
+                name=d.name,
+                is_mandatory=d.processor_class.is_mandatory()
+            ) for d in sorted_definitions
+        ]
+
     def get_all_definitions(self) -> Dict[str, AgentUserInputMessageProcessorDefinition]:
         """
         Returns a shallow copy of the dictionary containing all registered input processor definitions.
-
-        Returns:
-            A dictionary where keys are processor names and values are AgentUserInputMessageProcessorDefinition objects.
         """
         return dict(self._definitions)
 

autobyteus/agent/llm_response_processor/base_processor.py

@@ -30,6 +30,22 @@ class BaseLLMResponseProcessor(ABC, metaclass=LLMResponseProcessorMeta):
         """
         return cls.__name__
 
+    @classmethod
+    def get_order(cls) -> int:
+        """
+        Returns the execution order for this processor. Lower numbers execute earlier.
+        Defaults to 500 (normal priority).
+        """
+        return 500
+
+    @classmethod
+    def is_mandatory(cls) -> bool:
+        """
+        Returns True if this processor is mandatory for the agent to function correctly.
+        Defaults to False (optional).
+        """
+        return False
+
     @abstractmethod
     async def process_response(self, response: 'CompleteResponse', context: 'AgentContext', triggering_event: 'LLMCompleteResponseReceivedEvent') -> bool:
         """
@@ -50,4 +66,4 @@ class BaseLLMResponseProcessor(ABC, metaclass=LLMResponseProcessorMeta):
         raise NotImplementedError("Subclasses must implement the 'process_response' method.")
 
     def __repr__(self) -> str:
-        return f"<{self.__class__.__name__}>"
+        return f"&lt;{self.__class__.__name__}&gt;"