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

autobyteus/agent/bootstrap_steps/workspace_context_initialization_step.py

@@ -0,0 +1,47 @@
+# file: autobyteus/autobyteus/agent/bootstrap_steps/workspace_context_initialization_step.py
+import logging
+from typing import TYPE_CHECKING
+
+from .base_bootstrap_step import BaseBootstrapStep
+
+if TYPE_CHECKING:
+    from autobyteus.agent.context import AgentContext
+    from autobyteus.agent.context.agent_phase_manager import AgentPhaseManager
+
+logger = logging.getLogger(__name__)
+
+class WorkspaceContextInitializationStep(BaseBootstrapStep):
+    """
+    Bootstrap step for injecting the AgentContext into the agent's workspace instance.
+    """
+
+    def __init__(self):
+        logger.debug("WorkspaceContextInitializationStep initialized.")
+
+    async def execute(self,
+                      context: 'AgentContext',
+                      phase_manager: 'AgentPhaseManager') -> bool:
+        agent_id = context.agent_id
+        logger.info(f"Agent '{agent_id}': Executing WorkspaceContextInitializationStep.")
+
+        workspace = context.workspace
+
+        if not workspace:
+            logger.debug(f"Agent '{agent_id}': No workspace configured. Skipping context injection.")
+            return True
+
+        try:
+            if hasattr(workspace, 'set_context') and callable(getattr(workspace, 'set_context')):
+                workspace.set_context(context)
+                logger.info(f"Agent '{agent_id}': AgentContext successfully injected into workspace instance of type '{type(workspace).__name__}'.")
+            else:
+                logger.warning(f"Agent '{agent_id}': Configured workspace of type '{type(workspace).__name__}' does not have a 'set_context' method. "
+                               "Workspace will not have access to the agent's context.")
+
+            return True
+        except Exception as e:
+            error_message = f"Agent '{agent_id}': Critical failure during WorkspaceContextInitializationStep: {e}"
+            logger.error(error_message, exc_info=True)
+            # No easy way to enqueue an error event here if queues aren't even initialized yet.
+            # The failure of a bootstrap step is handled by the bootstrapper, which will log and set error phase.
+            return False

autobyteus/agent/context/__init__.py

@@ -0,0 +1,18 @@
+# file: autobyteus/autobyteus/agent/context/__init__.py
+"""
+Components related to the agent's runtime context, state, config, and status management.
+"""
+from .agent_config import AgentConfig
+from .agent_runtime_state import AgentRuntimeState
+from .agent_context import AgentContext 
+from .agent_phase_manager import AgentPhaseManager
+from .phases import AgentOperationalPhase
+
+
+__all__ = [
+    "AgentContext",
+    "AgentConfig", 
+    "AgentRuntimeState", 
+    "AgentPhaseManager",
+    "AgentOperationalPhase",
+]

autobyteus/agent/context/agent_config.py

@@ -0,0 +1,80 @@
+# file: autobyteus/autobyteus/agent/context/agent_config.py
+import logging
+from typing import List, Optional, Union, Tuple, TYPE_CHECKING
+
+# Correctly import the new master processor and the base class
+from autobyteus.agent.system_prompt_processor import ToolManifestInjectorProcessor, BaseSystemPromptProcessor
+from autobyteus.agent.llm_response_processor import ProviderAwareToolUsageProcessor, BaseLLMResponseProcessor
+
+
+if TYPE_CHECKING:
+    from autobyteus.tools.base_tool import BaseTool
+    from autobyteus.agent.input_processor import BaseAgentUserInputMessageProcessor
+    from autobyteus.llm.base_llm import BaseLLM
+    from autobyteus.agent.workspace.base_workspace import BaseAgentWorkspace
+    from autobyteus.agent.hooks.base_phase_hook import BasePhaseHook
+
+logger = logging.getLogger(__name__)
+
+class AgentConfig:
+    """
+    Represents the complete, static configuration for an agent instance.
+    This is the single source of truth for an agent's definition, including
+    its identity, capabilities, and default behaviors.
+    """
+    # Use the new ProviderAwareToolUsageProcessor as the default
+    DEFAULT_LLM_RESPONSE_PROCESSORS = [ProviderAwareToolUsageProcessor()]
+    # Use the new, single, unified processor as the default
+    DEFAULT_SYSTEM_PROMPT_PROCESSORS = [ToolManifestInjectorProcessor()]
+
+    def __init__(self,
+                 name: str,
+                 role: str,
+                 description: str,
+                 llm_instance: 'BaseLLM',
+                 system_prompt: str,
+                 tools: List['BaseTool'],
+                 auto_execute_tools: bool = True,
+                 use_xml_tool_format: bool = True,
+                 input_processors: Optional[List['BaseAgentUserInputMessageProcessor']] = None,
+                 llm_response_processors: Optional[List['BaseLLMResponseProcessor']] = None,
+                 system_prompt_processors: Optional[List['BaseSystemPromptProcessor']] = None,
+                 workspace: Optional['BaseAgentWorkspace'] = None,
+                 phase_hooks: Optional[List['BasePhaseHook']] = None):
+        """
+        Initializes the AgentConfig.
+
+        Args:
+            name: The agent's name.
+            role: The agent's role.
+            description: A description of the agent.
+            llm_instance: A pre-initialized LLM instance (subclass of BaseLLM).
+                          The user is responsible for creating and configuring this instance.
+            system_prompt: The base system prompt.
+            tools: A list of pre-initialized tool instances (subclasses of BaseTool).
+            auto_execute_tools: If True, the agent will execute tools without approval.
+            use_xml_tool_format: Whether to use XML for tool descriptions and examples.
+            input_processors: A list of input processor instances.
+            llm_response_processors: A list of LLM response processor instances.
+            system_prompt_processors: A list of system prompt processor instances.
+            workspace: An optional pre-initialized workspace instance for the agent.
+            phase_hooks: An optional list of phase transition hook instances.
+        """
+        self.name = name
+        self.role = role
+        self.description = description
+        self.llm_instance = llm_instance
+        self.system_prompt = system_prompt
+        self.tools = tools
+        self.workspace = workspace
+        self.auto_execute_tools = auto_execute_tools
+        self.use_xml_tool_format = use_xml_tool_format
+        self.input_processors = input_processors or []
+        self.llm_response_processors = llm_response_processors if llm_response_processors is not None else list(self.DEFAULT_LLM_RESPONSE_PROCESSORS)
+        self.system_prompt_processors = system_prompt_processors if system_prompt_processors is not None else list(self.DEFAULT_SYSTEM_PROMPT_PROCESSORS)
+        self.phase_hooks = phase_hooks or []
+
+        logger.debug(f"AgentConfig created for name '{self.name}', role '{self.role}'.")
+
+    def __repr__(self) -> str:
+        return (f"AgentConfig(name='{self.name}', role='{self.role}', llm_instance='{self.llm_instance.__class__.__name__}', workspace_configured={self.workspace is not None})")

autobyteus/agent/context/agent_context.py

@@ -0,0 +1,132 @@
+# file: autobyteus/autobyteus/agent/context/agent_context.py
+import logging
+from typing import TYPE_CHECKING, List, Dict, Any, Optional
+
+from .phases import AgentOperationalPhase 
+
+if TYPE_CHECKING:
+    from .agent_config import AgentConfig 
+    from .agent_runtime_state import AgentRuntimeState 
+    from autobyteus.llm.base_llm import BaseLLM
+    from autobyteus.tools.base_tool import BaseTool
+    from autobyteus.agent.events.agent_input_event_queue_manager import AgentInputEventQueueManager 
+    from autobyteus.agent.tool_invocation import ToolInvocation
+    # LLMConfig no longer needed here
+    from autobyteus.agent.workspace.base_workspace import BaseAgentWorkspace
+    from autobyteus.agent.context.agent_phase_manager import AgentPhaseManager 
+
+logger = logging.getLogger(__name__)
+
+class AgentContext:
+    """
+    Represents the complete operational context for a single agent instance.
+    """
+    def __init__(self, agent_id: str, config: 'AgentConfig', state: 'AgentRuntimeState'):
+        from .agent_config import AgentConfig as AgentConfigClass 
+        from .agent_runtime_state import AgentRuntimeState as AgentRuntimeStateClass 
+
+        if not agent_id or not isinstance(agent_id, str):
+            raise ValueError("AgentContext requires a non-empty string 'agent_id'.")
+        if not isinstance(config, AgentConfigClass):
+            raise TypeError(f"AgentContext 'config' must be an AgentConfig instance. Got {type(config)}")
+        if not isinstance(state, AgentRuntimeStateClass):
+            raise TypeError(f"AgentContext 'state' must be an AgentRuntimeState instance. Got {type(state)}")
+        
+        if agent_id != state.agent_id: # pragma: no cover
+            logger.warning(f"AgentContext created with mismatched agent_id ('{agent_id}') and state's ID ('{state.agent_id}'). Using context's ID for logging.")
+
+        self.agent_id: str = agent_id
+        self.config: 'AgentConfig' = config
+        self.state: 'AgentRuntimeState' = state
+        
+        logger.info(f"AgentContext composed for agent_id '{self.agent_id}'. Config and State linked.")
+
+    @property
+    def tool_instances(self) -> Dict[str, 'BaseTool']:
+        return self.state.tool_instances if self.state.tool_instances is not None else {}
+
+    @property
+    def auto_execute_tools(self) -> bool:
+        return self.config.auto_execute_tools
+    
+    # llm_model_name property removed
+    # custom_llm_config property removed
+
+    @property
+    def llm_instance(self) -> Optional['BaseLLM']:
+        return self.state.llm_instance
+
+    @llm_instance.setter
+    def llm_instance(self, value: Optional['BaseLLM']):
+        self.state.llm_instance = value
+
+    @property
+    def input_event_queues(self) -> 'AgentInputEventQueueManager': 
+        if self.state.input_event_queues is None:
+            logger.critical(f"AgentContext for '{self.agent_id}': Attempted to access 'input_event_queues' before they were initialized by AgentWorker.")
+            raise RuntimeError(f"Agent '{self.agent_id}': Input event queues have not been initialized. This typically occurs during agent bootstrapping.")
+        return self.state.input_event_queues
+
+    @property
+    def current_phase(self) -> 'AgentOperationalPhase': 
+        return self.state.current_phase
+
+    @current_phase.setter
+    def current_phase(self, value: 'AgentOperationalPhase'): 
+        if not isinstance(value, AgentOperationalPhase): # pragma: no cover
+            raise TypeError(f"current_phase must be an AgentOperationalPhase instance. Got {type(value)}")
+        self.state.current_phase = value
+
+    @property
+    def phase_manager(self) -> Optional['AgentPhaseManager']: 
+        return self.state.phase_manager_ref
+
+    @property
+    def conversation_history(self) -> List[Dict[str, Any]]:
+        return self.state.conversation_history
+
+    @property
+    def pending_tool_approvals(self) -> Dict[str, 'ToolInvocation']:
+        return self.state.pending_tool_approvals
+
+    @property
+    def custom_data(self) -> Dict[str, Any]:
+        return self.state.custom_data
+        
+    @property
+    def workspace(self) -> Optional['BaseAgentWorkspace']:
+        return self.state.workspace
+    
+    @property
+    def processed_system_prompt(self) -> Optional[str]:
+        return self.state.processed_system_prompt
+    
+    @processed_system_prompt.setter
+    def processed_system_prompt(self, value: Optional[str]):
+        self.state.processed_system_prompt = value
+
+    # final_llm_config_for_creation property removed
+
+    def add_message_to_history(self, message: Dict[str, Any]) -> None:
+        self.state.add_message_to_history(message)
+
+    def get_tool(self, tool_name: str) -> Optional['BaseTool']:
+        tool = self.tool_instances.get(tool_name) 
+        if not tool: # pragma: no cover
+            logger.warning(f"Tool '{tool_name}' not found in AgentContext.state.tool_instances for agent '{self.agent_id}'. "
+                           f"Available tools: {list(self.tool_instances.keys())}")
+        return tool
+
+    def store_pending_tool_invocation(self, invocation: 'ToolInvocation') -> None:
+        self.state.store_pending_tool_invocation(invocation)
+
+    def retrieve_pending_tool_invocation(self, invocation_id: str) -> Optional['ToolInvocation']:
+        return self.state.retrieve_pending_tool_invocation(invocation_id)
+
+    def __repr__(self) -> str:
+        input_q_status = "Initialized" if self.state.input_event_queues is not None else "Pending Init"
+        return (f"AgentContext(agent_id='{self.agent_id}', "
+                f"current_phase='{self.state.current_phase.value}', " 
+                f"llm_initialized={self.state.llm_instance is not None}, "
+                f"tools_initialized={self.state.tool_instances is not None}, "
+                f"input_queues_status='{input_q_status}')")

autobyteus/agent/context/agent_phase_manager.py

@@ -0,0 +1,164 @@
+# file: autobyteus/autobyteus/agent/context/agent_phase_manager.py
+import asyncio
+import logging
+from typing import TYPE_CHECKING, Optional, Dict, Any
+
+from .phases import AgentOperationalPhase
+
+if TYPE_CHECKING:
+    from autobyteus.agent.context.agent_context import AgentContext
+    from autobyteus.agent.tool_invocation import ToolInvocation
+    from autobyteus.agent.events.notifiers import AgentExternalEventNotifier
+
+
+logger = logging.getLogger(__name__)
+
+class AgentPhaseManager:
+    """
+    Manages the operational phase of an agent, uses an AgentExternalEventNotifier
+    to signal phase changes externally, and executes phase transition hooks.
+    """
+    def __init__(self, context: 'AgentContext', notifier: 'AgentExternalEventNotifier'):
+        self.context: 'AgentContext' = context
+        self.notifier: 'AgentExternalEventNotifier' = notifier
+
+        self.context.current_phase = AgentOperationalPhase.UNINITIALIZED
+        
+        logger.debug(f"AgentPhaseManager initialized for agent_id '{self.context.agent_id}'. "
+                     f"Initial phase: {self.context.current_phase.value}. Uses provided notifier.")
+
+    async def _execute_hooks(self, old_phase: AgentOperationalPhase, new_phase: AgentOperationalPhase):
+        """Asynchronously executes hooks that match the given phase transition."""
+        hooks_to_run = [
+            hook for hook in self.context.config.phase_hooks
+            if hook.source_phase == old_phase and hook.target_phase == new_phase
+        ]
+
+        if not hooks_to_run:
+            return
+
+        hook_names = [hook.__class__.__name__ for hook in hooks_to_run]
+        logger.info(f"Agent '{self.context.agent_id}': Executing {len(hooks_to_run)} hooks for transition "
+                    f"'{old_phase.value}' -> '{new_phase.value}': {hook_names}")
+        
+        for hook in hooks_to_run:
+            try:
+                await hook.execute(self.context)
+                logger.debug(f"Agent '{self.context.agent_id}': Hook '{hook.__class__.__name__}' executed successfully.")
+            except Exception as e:
+                logger.error(f"Agent '{self.context.agent_id}': Error executing phase transition hook "
+                             f"'{hook.__class__.__name__}' for '{old_phase.value}' -> '{new_phase.value}': {e}",
+                             exc_info=True)
+                # We log the error but do not halt the agent's phase transition.
+
+    async def _transition_phase(self, new_phase: AgentOperationalPhase,
+                                notify_method_name: str,
+                                additional_data: Optional[Dict[str, Any]] = None):
+        """
+        Private async helper to change the agent's phase, execute hooks, and then
+        call the appropriate notifier method. Hooks are now awaited.
+        """
+        if not isinstance(new_phase, AgentOperationalPhase):
+            logger.error(f"AgentPhaseManager for '{self.context.agent_id}' received invalid type for new_phase: {type(new_phase)}. Must be AgentOperationalPhase.")
+            return
+
+        old_phase = self.context.current_phase
+        
+        if old_phase == new_phase:
+            logger.debug(f"AgentPhaseManager for '{self.context.agent_id}': already in phase {new_phase.value}. No transition.")
+            return
+
+        logger.info(f"Agent '{self.context.agent_id}' phase transitioning from {old_phase.value} to {new_phase.value}.")
+        self.context.current_phase = new_phase
+
+        # Execute and wait for hooks to complete *before* notifying externally.
+        await self._execute_hooks(old_phase, new_phase)
+
+        notifier_method = getattr(self.notifier, notify_method_name, None)
+        if notifier_method and callable(notifier_method):
+            notify_args = {"old_phase": old_phase}
+            if additional_data:
+                notify_args.update(additional_data)
+            
+            notifier_method(**notify_args)
+        else: 
+            logger.error(f"AgentPhaseManager for '{self.context.agent_id}': Notifier method '{notify_method_name}' not found or not callable on {type(self.notifier).__name__}.")
+
+    async def notify_runtime_starting_and_uninitialized(self) -> None:
+        if self.context.current_phase == AgentOperationalPhase.UNINITIALIZED:
+            await self._transition_phase(AgentOperationalPhase.UNINITIALIZED, "notify_phase_uninitialized_entered")
+        elif self.context.current_phase.is_terminal():
+             await self._transition_phase(AgentOperationalPhase.UNINITIALIZED, "notify_phase_uninitialized_entered")
+        else:
+             logger.warning(f"Agent '{self.context.agent_id}' notify_runtime_starting_and_uninitialized called in unexpected phase: {self.context.current_phase.value}")
+
+    async def notify_bootstrapping_started(self) -> None:
+        await self._transition_phase(AgentOperationalPhase.BOOTSTRAPPING, "notify_phase_bootstrapping_started")
+
+    async def notify_initialization_complete(self) -> None:
+        if self.context.current_phase.is_initializing() or self.context.current_phase == AgentOperationalPhase.UNINITIALIZED:
+            # This will now be a BOOTSTRAPPING -> IDLE transition
+            await self._transition_phase(AgentOperationalPhase.IDLE, "notify_phase_idle_entered")
+        else:
+            logger.warning(f"Agent '{self.context.agent_id}' notify_initialization_complete called in unexpected phase: {self.context.current_phase.value}")
+
+    async def notify_processing_input_started(self, trigger_info: Optional[str] = None) -> None:
+        if self.context.current_phase in [AgentOperationalPhase.IDLE, AgentOperationalPhase.ANALYZING_LLM_RESPONSE, AgentOperationalPhase.PROCESSING_TOOL_RESULT, AgentOperationalPhase.EXECUTING_TOOL]:
+            data = {"trigger_info": trigger_info} if trigger_info else {}
+            await self._transition_phase(AgentOperationalPhase.PROCESSING_USER_INPUT, "notify_phase_processing_user_input_started", additional_data=data)
+        elif self.context.current_phase == AgentOperationalPhase.PROCESSING_USER_INPUT:
+             logger.debug(f"Agent '{self.context.agent_id}' already in PROCESSING_USER_INPUT phase.")
+        else:
+             logger.warning(f"Agent '{self.context.agent_id}' notify_processing_input_started called in unexpected phase: {self.context.current_phase.value}")
+
+    async def notify_awaiting_llm_response(self) -> None:
+        await self._transition_phase(AgentOperationalPhase.AWAITING_LLM_RESPONSE, "notify_phase_awaiting_llm_response_started")
+
+    async def notify_analyzing_llm_response(self) -> None:
+        await self._transition_phase(AgentOperationalPhase.ANALYZING_LLM_RESPONSE, "notify_phase_analyzing_llm_response_started")
+
+    async def notify_tool_execution_pending_approval(self, tool_invocation: 'ToolInvocation') -> None:
+        # The notifier's notify_phase_awaiting_tool_approval_started method no longer takes tool_details.
+        # The phase event itself is the signal. Tool data comes via queue.
+        await self._transition_phase(AgentOperationalPhase.AWAITING_TOOL_APPROVAL, "notify_phase_awaiting_tool_approval_started")
+
+    async def notify_tool_execution_resumed_after_approval(self, approved: bool, tool_name: Optional[str]) -> None:
+        if approved and tool_name:
+            await self._transition_phase(AgentOperationalPhase.EXECUTING_TOOL, "notify_phase_executing_tool_started", additional_data={"tool_name": tool_name})
+        else:
+            logger.info(f"Agent '{self.context.agent_id}' tool execution denied for '{tool_name}'. Transitioning to allow LLM to process denial.")
+            await self._transition_phase(AgentOperationalPhase.ANALYZING_LLM_RESPONSE, "notify_phase_analyzing_llm_response_started", additional_data={"denial_for_tool": tool_name})
+
+    async def notify_tool_execution_started(self, tool_name: str) -> None:
+        await self._transition_phase(AgentOperationalPhase.EXECUTING_TOOL, "notify_phase_executing_tool_started", additional_data={"tool_name": tool_name})
+
+    async def notify_processing_tool_result(self, tool_name: str) -> None:
+        await self._transition_phase(AgentOperationalPhase.PROCESSING_TOOL_RESULT, "notify_phase_processing_tool_result_started", additional_data={"tool_name": tool_name})
+
+    async def notify_processing_complete_and_idle(self) -> None:
+        if not self.context.current_phase.is_terminal() and self.context.current_phase != AgentOperationalPhase.IDLE:
+            await self._transition_phase(AgentOperationalPhase.IDLE, "notify_phase_idle_entered")
+        elif self.context.current_phase == AgentOperationalPhase.IDLE:
+            logger.debug(f"Agent '{self.context.agent_id}' processing complete, already IDLE.")
+        else:
+            logger.warning(f"Agent '{self.context.agent_id}' notify_processing_complete_and_idle called in unexpected phase: {self.context.current_phase.value}")
+
+    async def notify_error_occurred(self, error_message: str, error_details: Optional[str] = None) -> None:
+        if self.context.current_phase != AgentOperationalPhase.ERROR:
+            data = {"error_message": error_message, "error_details": error_details}
+            await self._transition_phase(AgentOperationalPhase.ERROR, "notify_phase_error_entered", additional_data=data)
+        else:
+            logger.debug(f"Agent '{self.context.agent_id}' already in ERROR phase when another error notified: {error_message}")
+
+    async def notify_shutdown_initiated(self) -> None:
+        if not self.context.current_phase.is_terminal():
+             await self._transition_phase(AgentOperationalPhase.SHUTTING_DOWN, "notify_phase_shutting_down_started")
+        else:
+            logger.debug(f"Agent '{self.context.agent_id}' shutdown initiated but already in a terminal phase: {self.context.current_phase.value}")
+
+    async def notify_final_shutdown_complete(self) -> None:
+        final_phase = AgentOperationalPhase.ERROR if self.context.current_phase == AgentOperationalPhase.ERROR else AgentOperationalPhase.SHUTDOWN_COMPLETE
+        if final_phase == AgentOperationalPhase.ERROR:
+            await self._transition_phase(AgentOperationalPhase.ERROR, "notify_phase_error_entered", additional_data={"error_message": "Shutdown completed with agent in error state."})
+        else:
+            await self._transition_phase(AgentOperationalPhase.SHUTDOWN_COMPLETE, "notify_phase_shutdown_completed")

autobyteus/agent/context/agent_runtime_state.py

@@ -0,0 +1,89 @@
+# file: autobyteus/autobyteus/agent/context/agent_runtime_state.py
+import logging
+from typing import List, Dict, Any, Optional, TYPE_CHECKING
+
+from autobyteus.agent.events.agent_input_event_queue_manager import AgentInputEventQueueManager 
+# AgentOutputDataManager is no longer part of AgentRuntimeState
+# from autobyteus.agent.events.agent_output_data_manager import AgentOutputDataManager       
+
+from autobyteus.llm.base_llm import BaseLLM
+from .phases import AgentOperationalPhase 
+from autobyteus.agent.workspace.base_workspace import BaseAgentWorkspace
+from autobyteus.agent.tool_invocation import ToolInvocation
+# LLMConfig is no longer needed here
+# from autobyteus.llm.utils.llm_config import LLMConfig 
+
+if TYPE_CHECKING:
+    from autobyteus.agent.context.agent_phase_manager import AgentPhaseManager 
+    from autobyteus.tools.base_tool import BaseTool 
+
+logger = logging.getLogger(__name__)
+
+class AgentRuntimeState:
+    """
+    Encapsulates the dynamic, stateful data of an agent instance.
+    Input event queues are initialized by the AgentWorker via a bootstrap step.
+    Output data is now handled by emitting events via AgentExternalEventNotifier.
+    """
+    def __init__(self,
+                 agent_id: str, 
+                 workspace: Optional[BaseAgentWorkspace] = None,
+                 conversation_history: Optional[List[Dict[str, Any]]] = None,
+                 custom_data: Optional[Dict[str, Any]] = None):
+        if not agent_id or not isinstance(agent_id, str):
+            raise ValueError("AgentRuntimeState requires a non-empty string 'agent_id'.")
+        if workspace is not None and not isinstance(workspace, BaseAgentWorkspace): # pragma: no cover
+            raise TypeError(f"AgentRuntimeState 'workspace' must be a BaseAgentWorkspace or None. Got {type(workspace)}")
+
+        self.agent_id: str = agent_id 
+        self.current_phase: AgentOperationalPhase = AgentOperationalPhase.UNINITIALIZED 
+        self.llm_instance: Optional[BaseLLM] = None  
+        self.tool_instances: Optional[Dict[str, 'BaseTool']] = None 
+        
+        self.input_event_queues: Optional[AgentInputEventQueueManager] = None 
+        # REMOVED: self.output_data_queues attribute
+        
+        self.workspace: Optional[BaseAgentWorkspace] = workspace
+        self.conversation_history: List[Dict[str, Any]] = conversation_history or []
+        self.pending_tool_approvals: Dict[str, ToolInvocation] = {}
+        self.custom_data: Dict[str, Any] = custom_data or {}
+        
+        self.processed_system_prompt: Optional[str] = None
+        # self.final_llm_config_for_creation removed
+        
+        self.phase_manager_ref: Optional['AgentPhaseManager'] = None 
+         
+        logger.info(f"AgentRuntimeState initialized for agent_id '{self.agent_id}'. Initial phase: {self.current_phase.value}. Workspace linked. InputQueues pending initialization. Output data via notifier.")
+
+    def add_message_to_history(self, message: Dict[str, Any]) -> None:
+        if not isinstance(message, dict) or "role" not in message: # pragma: no cover
+            logger.warning(f"Attempted to add malformed message to history for agent '{self.agent_id}': {message}")
+            return
+        self.conversation_history.append(message)
+        logger.debug(f"Message added to history for agent '{self.agent_id}': role={message['role']}")
+
+    def store_pending_tool_invocation(self, invocation: ToolInvocation) -> None:
+        if not isinstance(invocation, ToolInvocation) or not invocation.id: # pragma: no cover
+            logger.error(f"Agent '{self.agent_id}': Attempted to store invalid ToolInvocation for approval: {invocation}")
+            return
+        self.pending_tool_approvals[invocation.id] = invocation
+        logger.info(f"Agent '{self.agent_id}': Stored pending tool invocation '{invocation.id}' ({invocation.name}).")
+
+    def retrieve_pending_tool_invocation(self, invocation_id: str) -> Optional[ToolInvocation]:
+        invocation = self.pending_tool_approvals.pop(invocation_id, None)
+        if invocation:
+            logger.info(f"Agent '{self.agent_id}': Retrieved pending tool invocation '{invocation_id}' ({invocation.name}).")
+        else: # pragma: no cover
+            logger.warning(f"Agent '{self.agent_id}': Pending tool invocation '{invocation_id}' not found.")
+        return invocation
+    
+    def __repr__(self) -> str:
+        phase_repr = self.current_phase.value
+        llm_status = "Initialized" if self.llm_instance else "Not Initialized"
+        tools_status = f"{len(self.tool_instances)} Initialized" if self.tool_instances is not None else "Not Initialized"
+        input_queues_status = "Initialized" if self.input_event_queues else "Not Initialized"
+        # REMOVED output_queues_status from repr
+        return (f"AgentRuntimeState(agent_id='{self.agent_id}', current_phase='{phase_repr}', "
+                f"llm_status='{llm_status}', tools_status='{tools_status}', "
+                f"input_queues_status='{input_queues_status}', "
+                f"pending_approvals={len(self.pending_tool_approvals)}, history_len={len(self.conversation_history)})")

autobyteus/agent/context/phases.py

@@ -0,0 +1,47 @@
+# file: autobyteus/autobyteus/agent/context/phases.py
+from enum import Enum
+
+class AgentOperationalPhase(str, Enum):
+    """
+    Defines the fine-grained operational phases of an agent.
+    This is the single source of truth for an agent's current state of operation.
+    """
+    UNINITIALIZED = "uninitialized"            # Agent object created, but runtime not started or fully set up.
+    BOOTSTRAPPING = "bootstrapping"            # Agent is running its internal initialization/bootstrap sequence.
+    IDLE = "idle"                              # Fully initialized and ready for new input.
+    
+    PROCESSING_USER_INPUT = "processing_user_input"     # Actively processing a user message, typically preparing for an LLM call.
+    AWAITING_LLM_RESPONSE = "awaiting_llm_response"     # Sent a request to LLM, waiting for the full response or stream.
+    ANALYZING_LLM_RESPONSE = "analyzing_llm_response"   # Received LLM response, analyzing it for next actions (e.g., tool use, direct reply).
+    
+    AWAITING_TOOL_APPROVAL = "awaiting_tool_approval"   # Paused, needs external (user) approval for a tool invocation.
+    EXECUTING_TOOL = "executing_tool"                   # Tool has been approved (or auto-approved) and is currently running.
+    PROCESSING_TOOL_RESULT = "processing_tool_result"   # Received a tool's result, actively processing it (often leading to another LLM call).
+    
+    SHUTTING_DOWN = "shutting_down"               # Shutdown sequence has been initiated.
+    SHUTDOWN_COMPLETE = "shutdown_complete"       # Agent has fully stopped and released resources.
+    ERROR = "error"                               # An unrecoverable error has occurred. Agent might be non-operational.
+
+    def __str__(self) -> str:
+        return self.value
+
+    def is_initializing(self) -> bool:
+        """Checks if the agent is in any of the initializing phases."""
+        return self in [
+            AgentOperationalPhase.BOOTSTRAPPING,
+        ]
+
+    def is_processing(self) -> bool:
+        """Checks if the agent is in any active processing phase (post-initialization, pre-shutdown)."""
+        return self in [
+            AgentOperationalPhase.PROCESSING_USER_INPUT,
+            AgentOperationalPhase.AWAITING_LLM_RESPONSE,
+            AgentOperationalPhase.ANALYZING_LLM_RESPONSE,
+            AgentOperationalPhase.AWAITING_TOOL_APPROVAL,
+            AgentOperationalPhase.EXECUTING_TOOL,
+            AgentOperationalPhase.PROCESSING_TOOL_RESULT,
+        ]
+    
+    def is_terminal(self) -> bool:
+        """Checks if the phase is a terminal state (shutdown or error)."""
+        return self in [AgentOperationalPhase.SHUTDOWN_COMPLETE, AgentOperationalPhase.ERROR]

autobyteus/agent/events/__init__.py

@@ -0,0 +1,63 @@
+# file: autobyteus/autobyteus/agent/events/__init__.py
+"""
+Event definitions and event queue management for agents.
+Also includes the WorkerEventDispatcher for routing events within an agent's worker loop.
+"""
+from .agent_input_event_queue_manager import AgentInputEventQueueManager
+from .worker_event_dispatcher import WorkerEventDispatcher 
+
+from .agent_events import (
+    BaseEvent,
+    # Categorical Base Events
+    LifecycleEvent,
+    AgentProcessingEvent,
+    # Agent Phase-Specific Base Events
+    AgentPreparationEvent, 
+    AgentOperationalEvent,
+    # Specific Lifecycle Events
+    AgentReadyEvent, 
+    AgentStoppedEvent,
+    AgentErrorEvent,
+    # DEPRECATED Initialization Events
+    CreateToolInstancesEvent, 
+    ProcessSystemPromptEvent,
+    FinalizeLLMConfigEvent,
+    CreateLLMInstanceEvent,
+    # Regular Agent Processing Events
+    UserMessageReceivedEvent, 
+    InterAgentMessageReceivedEvent, 
+    LLMUserMessageReadyEvent, 
+    LLMCompleteResponseReceivedEvent,
+    PendingToolInvocationEvent, 
+    ToolResultEvent,
+    ToolExecutionApprovalEvent,
+    ApprovedToolInvocationEvent,
+    # General Purpose Event
+    GenericEvent
+)
+
+__all__ = [
+    "AgentInputEventQueueManager", 
+    "WorkerEventDispatcher", 
+    "BaseEvent",
+    "LifecycleEvent",
+    "AgentProcessingEvent",
+    "AgentPreparationEvent", 
+    "AgentOperationalEvent", 
+    "AgentReadyEvent", 
+    "AgentStoppedEvent",
+    "AgentErrorEvent",
+    "CreateToolInstancesEvent", 
+    "ProcessSystemPromptEvent", 
+    "FinalizeLLMConfigEvent",   
+    "CreateLLMInstanceEvent",   
+    "UserMessageReceivedEvent",
+    "InterAgentMessageReceivedEvent",
+    "LLMUserMessageReadyEvent", 
+    "LLMCompleteResponseReceivedEvent",
+    "PendingToolInvocationEvent",
+    "ToolResultEvent",
+    "ToolExecutionApprovalEvent",
+    "ApprovedToolInvocationEvent",
+    "GenericEvent",
+]