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

autobyteus/agent/handlers/tool_invocation_request_event_handler.py

@@ -0,0 +1,186 @@
+# file: autobyteus/autobyteus/agent/handlers/tool_invocation_request_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 PendingToolInvocationEvent, ToolResultEvent 
+from autobyteus.agent.tool_invocation import ToolInvocation
+
+if TYPE_CHECKING:
+    from autobyteus.agent.context import AgentContext 
+    from autobyteus.agent.events.notifiers import AgentExternalEventNotifier 
+
+logger = logging.getLogger(__name__)
+
+class ToolInvocationRequestEventHandler(AgentEventHandler):
+    """
+    Handles PendingToolInvocationEvents.
+    If 'auto_execute_tools' (from AgentConfig) is False, it stores the invocation,
+    updates history, and emits an AGENT_REQUEST_TOOL_INVOCATION_APPROVAL event via the notifier.
+    If 'auto_execute_tools' is True, it executes the tool directly, emits
+    AGENT_DATA_TOOL_LOG events for call and result/error, 
+    and queues a ToolResultEvent.
+    """
+    def __init__(self): # pragma: no cover
+        logger.info("ToolInvocationRequestEventHandler initialized.")
+
+    async def _execute_tool_directly(self, 
+                                     tool_invocation: ToolInvocation, 
+                                     context: 'AgentContext',
+                                     notifier: Optional['AgentExternalEventNotifier']) -> None: # pragma: no cover
+        agent_id = context.agent_id 
+        tool_name = tool_invocation.name
+        arguments = tool_invocation.arguments
+        invocation_id = tool_invocation.id
+        
+        logger.info(f"Agent '{agent_id}' executing tool directly: '{tool_name}' (ID: {invocation_id}) with args: {arguments}")
+        
+        try:
+            args_str = json.dumps(arguments)
+        except TypeError:
+            args_str = str(arguments) 
+
+        log_msg_call = f"[TOOL_CALL_DIRECT] Agent_ID: {agent_id}, Tool: {tool_name}, Invocation_ID: {invocation_id}, Arguments: {args_str}"
+        if notifier:
+            try:
+                notifier.notify_agent_data_tool_log(log_msg_call) # USE RENAMED METHOD
+            except Exception as e_notify: 
+                 logger.error(f"Agent '{agent_id}': Error notifying tool call log: {e_notify}", exc_info=True)
+
+        tool_instance = context.get_tool(tool_name) 
+        result_event: ToolResultEvent
+
+        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: Tool '{tool_name}' execution failed. Reason: {error_message}",
+            })
+            log_msg_error = f"[TOOL_ERROR_DIRECT] Agent_ID: {agent_id}, Tool: {tool_name}, Invocation_ID: {invocation_id}, Error: {error_message}"
+            if notifier:
+                try:
+                    notifier.notify_agent_data_tool_log(log_msg_error) # USE RENAMED METHOD
+                    notifier.notify_agent_error_output_generation( # USE RENAMED METHOD
+                        error_source=f"ToolExecutionDirect.ToolNotFound.{tool_name}",
+                        error_message=error_message
+                    )
+                except Exception as e_notify: 
+                    logger.error(f"Agent '{agent_id}': Error notifying tool error log/output error: {e_notify}", exc_info=True)
+        else:
+            try:
+                logger.debug(f"Executing tool '{tool_name}' for agent '{agent_id}'. Invocation ID: {invocation_id}")
+                execution_result = await tool_instance.execute(context=context, **arguments) 
+                
+                try:
+                    result_str_for_log = json.dumps(execution_result)
+                except TypeError: 
+                    result_str_for_log = str(execution_result)
+
+                logger.info(f"Tool '{tool_name}' (ID: {invocation_id}) executed by agent '{agent_id}'. Result: {result_str_for_log[:200]}...")
+                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,
+                })
+                log_msg_result = f"[TOOL_RESULT_DIRECT] Agent_ID: {agent_id}, Tool: {tool_name}, Invocation_ID: {invocation_id}, Outcome (first 200 chars): {result_str_for_log[:200]}"
+                if notifier:
+                    try:
+                        notifier.notify_agent_data_tool_log(log_msg_result) # USE RENAMED METHOD
+                    except Exception as e_notify: 
+                        logger.error(f"Agent '{agent_id}': Error notifying tool result log: {e_notify}", exc_info=True)
+
+            except Exception as e: 
+                error_message = f"Error executing tool '{tool_name}' (ID: {invocation_id}): {str(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)
+                context.add_message_to_history({ 
+                    "role": "tool",
+                    "tool_call_id": invocation_id,
+                    "name": tool_name,
+                    "content": f"Error: Tool '{tool_name}' execution failed. Reason: {error_message}",
+                })
+                log_msg_exception = f"[TOOL_EXCEPTION_DIRECT] Agent_ID: {agent_id}, Tool: {tool_name}, Invocation_ID: {invocation_id}, Exception: {error_message}"
+                if notifier:
+                    try:
+                        notifier.notify_agent_data_tool_log(log_msg_exception) # USE RENAMED METHOD
+                        notifier.notify_agent_error_output_generation( # USE RENAMED METHOD
+                            error_source=f"ToolExecutionDirect.Exception.{tool_name}",
+                            error_message=error_message,
+                            error_details=traceback.format_exc()
+                        )
+                    except Exception as e_notify: 
+                        logger.error(f"Agent '{agent_id}': Error notifying tool exception log/output error: {e_notify}", exc_info=True)
+        
+        await context.input_event_queues.enqueue_tool_result(result_event) 
+        logger.debug(f"Agent '{agent_id}' enqueued ToolResultEvent (direct exec) for '{tool_name}' (ID: {invocation_id}).")
+
+
+    async def handle(self,
+                     event: PendingToolInvocationEvent, 
+                     context: 'AgentContext') -> None: # pragma: no cover
+        if not isinstance(event, PendingToolInvocationEvent): 
+            logger.warning(f"ToolInvocationRequestEventHandler received non-PendingToolInvocationEvent: {type(event)}. Skipping.")
+            return
+
+        tool_invocation: ToolInvocation = event.tool_invocation
+        agent_id = context.agent_id 
+        
+        notifier: Optional['AgentExternalEventNotifier'] = None
+        if context.phase_manager:
+            notifier = context.phase_manager.notifier
+        
+        if not notifier:
+            logger.error(f"Agent '{agent_id}': Notifier not available in ToolInvocationRequestEventHandler. Output events for tool approval/logging will be lost.")
+            if not context.auto_execute_tools:
+                logger.critical(f"Agent '{agent_id}': Notifier is REQUIRED for manual tool approval flow but is unavailable. Tool '{tool_invocation.name}' cannot be processed for approval.")
+                return
+
+        if not context.auto_execute_tools:
+            logger.info(f"Agent '{agent_id}': Tool '{tool_invocation.name}' (ID: {tool_invocation.id}) requires approval. Storing pending invocation and emitting request.")
+            
+            context.store_pending_tool_invocation(tool_invocation) 
+
+            try:
+                arguments_json_str = json.dumps(tool_invocation.arguments or {})
+            except TypeError: 
+                logger.warning(f"Could not serialize args for history tool_call for '{tool_invocation.name}'. Using empty dict string.")
+                arguments_json_str = "{}"
+
+            context.add_message_to_history({ 
+                "role": "assistant",
+                "content": None, 
+                "tool_calls": [{
+                    "id": tool_invocation.id,
+                    "type": "function", 
+                    "function": {
+                        "name": tool_invocation.name,
+                        "arguments": arguments_json_str 
+                    }
+                }]
+            })
+            
+            approval_data = {
+                "invocation_id": tool_invocation.id,
+                "tool_name": tool_invocation.name,
+                "arguments": tool_invocation.arguments,
+            }
+            if notifier:
+                try:
+                    notifier.notify_agent_request_tool_invocation_approval(approval_data) # USE RENAMED METHOD
+                    logger.debug(f"Agent '{agent_id}': Emitted AGENT_REQUEST_TOOL_INVOCATION_APPROVAL for '{tool_invocation.name}' (ID: {tool_invocation.id}).")
+                except Exception as e_notify: 
+                    logger.error(f"Agent '{agent_id}': Error emitting AGENT_REQUEST_TOOL_INVOCATION_APPROVAL: {e_notify}", exc_info=True)
+            
+        else: 
+            logger.info(f"Agent '{agent_id}': Tool '{tool_invocation.name}' (ID: {tool_invocation.id}) executing automatically (auto_execute_tools=True).")
+            await self._execute_tool_directly(tool_invocation, context, notifier)

autobyteus/agent/handlers/tool_result_event_handler.py

@@ -0,0 +1,96 @@
+# file: autobyteus/autobyteus/agent/handlers/tool_result_event_handler.py
+import logging
+import json 
+from typing import TYPE_CHECKING, Optional 
+
+from autobyteus.agent.handlers.base_event_handler import AgentEventHandler 
+from autobyteus.agent.events import ToolResultEvent, LLMUserMessageReadyEvent 
+from autobyteus.llm.user_message import LLMUserMessage 
+
+if TYPE_CHECKING:
+    from autobyteus.agent.context import AgentContext 
+    from autobyteus.agent.events.notifiers import AgentExternalEventNotifier 
+
+logger = logging.getLogger(__name__)
+
+class ToolResultEventHandler(AgentEventHandler):
+    """
+    Handles ToolResultEvents by formatting the tool's output (or error)
+    as a new LLMUserMessage, emitting AGENT_DATA_TOOL_LOG event for this outcome,
+    and enqueuing an LLMUserMessageReadyEvent for further LLM processing.
+    """
+    def __init__(self):
+        logger.info("ToolResultEventHandler initialized.")
+
+    async def handle(self,
+                     event: ToolResultEvent,
+                     context: 'AgentContext') -> None:
+        if not isinstance(event, ToolResultEvent): 
+            logger.warning(f"ToolResultEventHandler received non-ToolResultEvent: {type(event)}. Skipping.")
+            return
+
+        agent_id = context.agent_id 
+        tool_invocation_id = event.tool_invocation_id if event.tool_invocation_id else 'N/A'
+
+        logger.info(f"Agent '{agent_id}' handling ToolResultEvent from tool: '{event.tool_name}' (Invocation ID: {tool_invocation_id}). Error: {event.error is not None}")
+        
+        notifier: Optional['AgentExternalEventNotifier'] = None
+        if context.phase_manager:
+            notifier = context.phase_manager.notifier
+        
+        if not notifier: # pragma: no cover
+            logger.error(f"Agent '{agent_id}': Notifier not available in ToolResultEventHandler. Tool result processing logs will not be emitted.")
+
+        if event.error:
+            logger.debug(f"Agent '{agent_id}' tool '{event.tool_name}' (ID: {tool_invocation_id}) raw error details: {event.error}")
+        else:
+            try:
+                raw_result_str_for_debug_log = json.dumps(event.result, indent=2)
+            except TypeError: # pragma: no cover
+                raw_result_str_for_debug_log = str(event.result)
+            logger.debug(f"Agent '{agent_id}' tool '{event.tool_name}' (ID: {tool_invocation_id}) raw result:\n---\n{raw_result_str_for_debug_log}\n---")
+
+
+        content_for_llm: str
+        if event.error:
+            content_for_llm = (
+                f"The tool '{event.tool_name}' (invocation ID: {tool_invocation_id}) encountered an error.\n"
+                f"Error details: {event.error}\n"
+                f"Please analyze this error and decide the next course of action."
+            )
+            log_msg_error_processed = f"[TOOL_RESULT_ERROR_PROCESSED] Agent_ID: {agent_id}, Tool: {event.tool_name}, Invocation_ID: {tool_invocation_id}, Error: {event.error}"
+            if notifier:
+                try:
+                    notifier.notify_agent_data_tool_log(log_msg_error_processed) # USE RENAMED METHOD
+                except Exception as e_notify: 
+                    logger.error(f"Agent '{agent_id}': Error notifying tool result error log: {e_notify}", exc_info=True)
+        else:
+            try:
+                result_str_for_llm = json.dumps(event.result, indent=2) if not isinstance(event.result, str) else event.result
+            except TypeError: # pragma: no cover
+                result_str_for_llm = str(event.result)
+
+            max_len = 2000  
+            if len(result_str_for_llm) > max_len: # pragma: no cover
+                original_len = len(str(event.result)) 
+                result_str_for_llm = result_str_for_llm[:max_len] + f"... (result truncated, original length {original_len})"
+            
+            content_for_llm = (
+                f"The tool '{event.tool_name}' (invocation ID: {tool_invocation_id}) has executed.\n"
+                f"Result:\n{result_str_for_llm}\n" 
+                f"Based on this result, what is the next step or final answer?"
+            )
+            log_msg_success_processed = f"[TOOL_RESULT_SUCCESS_PROCESSED] Agent_ID: {agent_id}, Tool: {event.tool_name}, Invocation_ID: {tool_invocation_id}, Result (first 200 chars of stringified): {str(event.result)[:200]}"
+            if notifier:
+                try:
+                    notifier.notify_agent_data_tool_log(log_msg_success_processed) # USE RENAMED METHOD
+                except Exception as e_notify: 
+                    logger.error(f"Agent '{agent_id}': Error notifying tool result success log: {e_notify}", exc_info=True)
+        
+        logger.debug(f"Agent '{agent_id}' preparing message for LLM based on tool '{event.tool_name}' (ID: {tool_invocation_id}) result:\n---\n{content_for_llm}\n---")
+        llm_user_message = LLMUserMessage(content=content_for_llm)
+        
+        next_event = LLMUserMessageReadyEvent(llm_user_message=llm_user_message) 
+        await context.input_event_queues.enqueue_internal_system_event(next_event)
+        
+        logger.info(f"Agent '{agent_id}' enqueued LLMUserMessageReadyEvent for LLM based on tool '{event.tool_name}' (ID: {tool_invocation_id}) result summary.") 

autobyteus/agent/handlers/user_input_message_event_handler.py

@@ -0,0 +1,77 @@
+# file: autobyteus/autobyteus/agent/handlers/user_input_message_event_handler.py
+import logging
+from typing import TYPE_CHECKING
+
+from autobyteus.agent.handlers.base_event_handler import AgentEventHandler
+from autobyteus.agent.events import UserMessageReceivedEvent, LLMUserMessageReadyEvent 
+from autobyteus.agent.message.agent_input_user_message import AgentInputUserMessage 
+from autobyteus.agent.input_processor import BaseAgentUserInputMessageProcessor
+from autobyteus.llm.user_message import LLMUserMessage
+
+
+if TYPE_CHECKING:
+    from autobyteus.agent.context import AgentContext 
+
+logger = logging.getLogger(__name__)
+
+class UserInputMessageEventHandler(AgentEventHandler):
+    """
+    Handles UserMessageReceivedEvents by first applying any configured
+    AgentUserInputMessageProcessors (provided as instances) to the AgentInputUserMessage,
+    then converting the processed message into an LLMUserMessage, and finally
+    enqueuing an LLMUserMessageReadyEvent for further processing by the LLM.
+    """
+
+    def __init__(self):
+        logger.info("UserInputMessageEventHandler initialized.")
+
+    async def handle(self,
+                     event: UserMessageReceivedEvent, 
+                     context: 'AgentContext') -> None:
+        if not isinstance(event, UserMessageReceivedEvent): 
+            logger.warning(f"UserInputMessageEventHandler received non-UserMessageReceivedEvent: {type(event)}. Skipping.")
+            return
+
+        original_agent_input_user_msg: AgentInputUserMessage = event.agent_input_user_message 
+        processed_agent_input_user_msg: AgentInputUserMessage = original_agent_input_user_msg 
+        
+        logger.info(f"Agent '{context.agent_id}' handling UserMessageReceivedEvent: '{original_agent_input_user_msg.content[:100]}...'") 
+        
+        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:
+                processor_name_for_log = "unknown"
+                try:
+                    if not isinstance(processor_instance, BaseAgentUserInputMessageProcessor):
+                        logger.error(f"Agent '{context.agent_id}': Invalid input processor type in config: {type(processor_instance)}. Skipping.")
+                        continue
+                    
+                    processor_name_for_log = processor_instance.get_name()
+                    logger.debug(f"Agent '{context.agent_id}': Applying input processor '{processor_name_for_log}'.")
+                    msg_before_this_processor = processed_agent_input_user_msg
+                    # Pass the original event to the processor
+                    processed_agent_input_user_msg = await processor_instance.process(
+                        message=msg_before_this_processor, 
+                        context=context, 
+                        triggering_event=event
+                    )
+                    logger.info(f"Agent '{context.agent_id}': Input processor '{processor_name_for_log}' applied successfully.")
+
+                except Exception as e:
+                    logger.error(f"Agent '{context.agent_id}': Error applying input processor '{processor_name_for_log}': {e}. "
+                                 f"Skipping this processor and continuing with message from before this processor.", exc_info=True)
+                    processed_agent_input_user_msg = msg_before_this_processor
+        else:
+            logger.debug(f"Agent '{context.agent_id}': No input processors configured in agent config.")
+
+        llm_user_message = LLMUserMessage( 
+            content=processed_agent_input_user_msg.content,
+            image_urls=processed_agent_input_user_msg.image_urls 
+        )
+        
+        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)
+        
+        logger.info(f"Agent '{context.agent_id}' processed AgentInputUserMessage and enqueued LLMUserMessageReadyEvent.")

autobyteus/agent/hooks/__init__.py

@@ -0,0 +1,9 @@
+# file: autobyteus/autobyteus/agent/hooks/__init__.py
+"""
+Components for defining and running lifecycle hooks based on agent phase transitions.
+"""
+from .base_phase_hook import BasePhaseHook
+
+__all__ = [
+    "BasePhaseHook",
+]

autobyteus/agent/hooks/base_phase_hook.py

@@ -0,0 +1,52 @@
+# file: autobyteus/autobyteus/agent/hooks/base_phase_hook.py
+import logging
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+from autobyteus.agent.context.phases import AgentOperationalPhase
+
+if TYPE_CHECKING:
+    from autobyteus.agent.context import AgentContext
+
+logger = logging.getLogger(__name__)
+
+class BasePhaseHook(ABC):
+    """
+    Abstract base class for creating hooks that execute on specific agent
+    phase transitions.
+
+    Subclasses must define the `source_phase` and `target_phase` to specify
+    the exact transition they are interested in, and implement the `execute`
+    method for their custom logic.
+    """
+
+    @property
+    @abstractmethod
+    def source_phase(self) -> AgentOperationalPhase:
+        """The source phase for the transition this hook targets."""
+        raise NotImplementedError
+
+    @property
+    @abstractmethod
+    def target_phase(self) -> AgentOperationalPhase:
+        """The target phase for the transition this hook targets."""
+        raise NotImplementedError
+
+    @abstractmethod
+    async def execute(self, context: 'AgentContext') -> None:
+        """
+        The method executed when the specified phase transition occurs.
+
+        Args:
+            context: The agent's context at the time of the transition.
+        """
+        raise NotImplementedError
+
+    def __repr__(self) -> str:
+        # Use try-except in case properties are not yet implemented during introspection
+        try:
+            return (f"<{self.__class__.__name__} "
+                    f"source='{self.source_phase.value}' "
+                    f"target='{self.target_phase.value}'>")
+        except (NotImplementedError, AttributeError):
+            return f"<{self.__class__.__name__} (unconfigured)>"

autobyteus/agent/input_processor/__init__.py

@@ -0,0 +1,18 @@
+# file: autobyteus/autobyteus/agent/input_processor/__init__.py
+"""
+Components for pre-processing AgentUserMessage objects.
+"""
+from .base_user_input_processor import BaseAgentUserInputMessageProcessor
+
+# Import concrete processors to make them easily accessible for instantiation
+from .passthrough_input_processor import PassthroughInputProcessor
+from .metadata_appending_input_processor import MetadataAppendingInputProcessor
+from .content_prefixing_input_processor import ContentPrefixingInputProcessor
+
+
+__all__ = [
+    "BaseAgentUserInputMessageProcessor",
+    "PassthroughInputProcessor",
+    "MetadataAppendingInputProcessor",
+    "ContentPrefixingInputProcessor",
+]

autobyteus/agent/input_processor/base_user_input_processor.py

@@ -0,0 +1,51 @@
+# file: autobyteus/autobyteus/agent/input_processor/base_user_input_processor.py
+import logging
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+    from autobyteus.agent.message.agent_input_user_message import AgentInputUserMessage 
+    from autobyteus.agent.context import AgentContext # Composite AgentContext
+    from autobyteus.agent.events import UserMessageReceivedEvent
+
+logger = logging.getLogger(__name__)
+
+class BaseAgentUserInputMessageProcessor(ABC):
+    """
+    Abstract base class for agent user input message processors.
+    These processors can modify an AgentInputUserMessage, specifically from a user,
+    before it is converted to an LLMUserMessage.
+    Subclasses should be instantiated and passed to the AgentSpecification.
+    """
+
+    def get_name(self) -> str:
+        """
+        Returns the unique registration name for this processor.
+        Defaults to the class name. Can be overridden by subclasses.
+        """
+        return self.__class__.__name__
+
+    @abstractmethod
+    async def process(self,
+                      message: 'AgentInputUserMessage', 
+                      context: 'AgentContext',
+                      triggering_event: 'UserMessageReceivedEvent') -> 'AgentInputUserMessage':
+        """
+        Processes the given AgentInputUserMessage.
+
+        Args:
+            message: The AgentInputUserMessage to process.
+            context: The composite AgentContext, providing access to agent's config and state.
+            triggering_event: The original UserMessageReceivedEvent that triggered this processing.
+                              This provides access to the full event payload for more complex processors.
+
+        Returns:
+            The processed (potentially modified) AgentInputUserMessage.
+
+        Raises:
+            NotImplementedError: If the subclass does not implement this method.
+        """
+        raise NotImplementedError("Subclasses must implement the 'process' method.")
+
+    def __repr__(self) -> str:
+        return f"<{self.__class__.__name__}>"

autobyteus/agent/input_processor/content_prefixing_input_processor.py

@@ -0,0 +1,41 @@
+# file: autobyteus/autobyteus/agent/input_processor/content_prefixing_input_processor.py
+import logging
+from typing import TYPE_CHECKING
+
+from .base_user_input_processor import BaseAgentUserInputMessageProcessor 
+
+if TYPE_CHECKING:
+    from autobyteus.agent.message.agent_input_user_message import AgentInputUserMessage
+    from autobyteus.agent.context import AgentContext # Composite AgentContext
+    from autobyteus.agent.events import UserMessageReceivedEvent
+
+logger = logging.getLogger(__name__)
+
+class ContentPrefixingInputProcessor(BaseAgentUserInputMessageProcessor):
+    """
+    A processor that adds a predefined prefix to the message content.
+    The prefix is defined by the agent's custom_data (in AgentRuntimeState) or a default.
+    Example prefix key in custom_data: "content_prefix"
+    """
+    DEFAULT_PREFIX = "[Processed Message] "
+
+    async def process(self,
+                      message: 'AgentInputUserMessage', 
+                      context: 'AgentContext',
+                      triggering_event: 'UserMessageReceivedEvent') -> 'AgentInputUserMessage':
+        """
+        Handles the message by prefixing its content.
+        The 'triggering_event' parameter is ignored by this processor.
+        """
+        agent_id = context.agent_id # Convenience property
+        logger.debug(f"Agent '{agent_id}': ContentPrefixingInputProcessor processing message.")
+        
+        # Access custom_data via convenience property (or context.state.custom_data)
+        prefix = context.custom_data.get("content_prefix", self.DEFAULT_PREFIX)
+        if not isinstance(prefix, str):
+            logger.warning(f"Agent '{agent_id}': 'content_prefix' in custom_data is not a string. Using default prefix. Found: {type(prefix)}")
+            prefix = self.DEFAULT_PREFIX
+            
+        message.content = prefix + message.content
+        logger.info(f"Agent '{agent_id}': Prefixed message content with '{prefix}'.")
+        return message

autobyteus/agent/input_processor/metadata_appending_input_processor.py

@@ -0,0 +1,34 @@
+# file: autobyteus/autobyteus/agent/input_processor/metadata_appending_input_processor.py
+import logging
+from typing import TYPE_CHECKING
+
+from .base_user_input_processor import BaseAgentUserInputMessageProcessor 
+
+if TYPE_CHECKING:
+    from autobyteus.agent.message.agent_input_user_message import AgentInputUserMessage
+    from autobyteus.agent.context import AgentContext # Composite AgentContext
+    from autobyteus.agent.events import UserMessageReceivedEvent
+
+logger = logging.getLogger(__name__)
+
+class MetadataAppendingInputProcessor(BaseAgentUserInputMessageProcessor):
+    """
+    A processor that appends fixed metadata to the message.
+    Example: Appends agent_id and config_name to metadata.
+    """
+    async def process(self,
+                      message: 'AgentInputUserMessage', 
+                      context: 'AgentContext',
+                      triggering_event: 'UserMessageReceivedEvent') -> 'AgentInputUserMessage':
+        """
+        Handles the message by appending metadata.
+        The 'triggering_event' parameter is ignored by this processor.
+        """
+        agent_id = context.agent_id
+        config_name = context.config.name
+
+        logger.debug(f"Agent '{agent_id}': MetadataAppendingInputProcessor processing message.")
+        message.metadata["processed_by_agent_id"] = agent_id
+        message.metadata["processed_with_config_name"] = config_name
+        logger.info(f"Agent '{agent_id}': Appended 'processed_by_agent_id' and 'processed_with_config_name' to message metadata.")
+        return message

autobyteus/agent/input_processor/passthrough_input_processor.py

@@ -0,0 +1,32 @@
+# file: autobyteus/autobyteus/agent/input_processor/passthrough_input_processor.py
+import logging
+from typing import TYPE_CHECKING
+
+from .base_user_input_processor import BaseAgentUserInputMessageProcessor 
+
+if TYPE_CHECKING:
+    from autobyteus.agent.message.agent_input_user_message import AgentInputUserMessage
+    from autobyteus.agent.context import AgentContext # Composite AgentContext
+    from autobyteus.agent.events import UserMessageReceivedEvent
+
+logger = logging.getLogger(__name__)
+
+class PassthroughInputProcessor(BaseAgentUserInputMessageProcessor):
+    """
+    A processor that returns the message unchanged.
+    Can be used as a default or for testing.
+    """
+    def get_name(self) -> str:
+        return "PassthroughInputProcessor"
+
+    async def process(self,
+                      message: 'AgentInputUserMessage', 
+                      context: 'AgentContext',
+                      triggering_event: 'UserMessageReceivedEvent') -> 'AgentInputUserMessage':
+        """
+        Handles the message by returning it without modification.
+        The 'triggering_event' parameter is ignored by this processor.
+        """
+        agent_id = context.agent_id # Convenience property
+        logger.debug(f"Agent '{agent_id}': PassthroughInputProcessor received message, returning as is.")
+        return message

autobyteus/agent/input_processor/processor_definition.py

@@ -0,0 +1,42 @@
+# file: autobyteus/autobyteus/agent/input_processor/processor_definition.py
+import logging
+from typing import Type, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .base_user_input_processor import BaseAgentUserInputMessageProcessor
+
+logger = logging.getLogger(__name__)
+
+class AgentUserInputMessageProcessorDefinition:
+    """
+    Represents the definition of an agent user input message processor.
+    Contains its registered name and the class itself.
+    """
+    def __init__(self, name: str, processor_class: Type['BaseAgentUserInputMessageProcessor']):
+        """
+        Initializes the AgentUserInputMessageProcessorDefinition.
+
+        Args:
+            name: The unique registered name of the processor.
+            processor_class: The class of the input processor.
+
+        Raises:
+            ValueError: If name is empty or processor_class is not a type.
+        """
+        if not name or not isinstance(name, str):
+            raise ValueError("Processor name must be a non-empty string.")
+        if not isinstance(processor_class, type): # Check if it's actually a class
+            raise ValueError("processor_class must be a class type.")
+        
+        # Further check if it's a subclass of BaseAgentUserInputMessageProcessor might be too restrictive
+        # here if base class is not yet defined due to import cycles, metaclass handles this better.
+        # from .base_user_input_processor import BaseAgentUserInputMessageProcessor # Delayed import for check
+        # if not issubclass(processor_class, BaseAgentUserInputMessageProcessor):
+        #    raise ValueError(f"processor_class '{processor_class.__name__}' must be a subclass of BaseAgentUserInputMessageProcessor.")
+
+        self.name: str = name
+        self.processor_class: Type['BaseAgentUserInputMessageProcessor'] = processor_class
+        logger.debug(f"AgentUserInputMessageProcessorDefinition created: name='{name}', class='{processor_class.__name__}'.")
+
+    def __repr__(self) -> str:
+        return f"<AgentUserInputMessageProcessorDefinition name='{self.name}', class='{self.processor_class.__name__}'>"