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

autobyteus/agent/llm_response_processor/processor_registry.py

@@ -60,6 +60,25 @@ class LLMResponseProcessorRegistry(metaclass=SingletonMeta):
             logger.debug(f"LLM response processor definition with name '{name}' not found in registry.")
         return definition
 
+    def get_processor(self, name: str) -> Optional['BaseLLMResponseProcessor']:
+        """
+        Retrieves an instance of an LLM response processor by its name.
+
+        Args:
+            name: The name of the LLM response processor to retrieve.
+
+        Returns:
+            An instance of the BaseLLMResponseProcessor if found and instantiable, otherwise None.
+        """
+        definition = self.get_processor_definition(name)
+        if definition:
+            try:
+                return definition.processor_class()
+            except Exception as e:
+                logger.error(f"Failed to instantiate LLM response processor '{name}' from class '{definition.processor_class.__name__}': {e}", exc_info=True)
+                return None
+        return None
+
     def list_processor_names(self) -> List[str]:
         """
         Returns a list of names of all registered LLM response processor definitions.

autobyteus/agent/llm_response_processor/provider_aware_tool_usage_processor.py

@@ -24,7 +24,8 @@ class ProviderAwareToolUsageProcessor(BaseLLMResponseProcessor):
         self._parser = ProviderAwareToolUsageParser()
         logger.debug("ProviderAwareToolUsageProcessor initialized.")
 
-    def get_name(self) -> str:
+    @classmethod
+    def get_name(cls) -> str:
         return "provider_aware_tool_usage"
 
     async def process_response(self, response: 'CompleteResponse', context: 'AgentContext', triggering_event: 'LLMCompleteResponseReceivedEvent') -> bool:

autobyteus/agent/message/context_file_type.py

@@ -1,4 +1,3 @@
-# file: autobyteus/autobyteus/agent/message/context_file_type.py
 from enum import Enum
 import os
 
@@ -18,7 +17,7 @@ class ContextFileType(str, Enum):
     HTML = "html"          # .html, .htm
     PYTHON = "python"      # .py
     JAVASCRIPT = "javascript" # .js
-    IMAGE_CONTEXT = "image_context" # .png, .jpg, .jpeg, .gif, .webp (when image is for contextual analysis, not direct LLM vision input)
+    IMAGE = "image"        # .png, .jpg, .jpeg, .gif, .webp (when image is for contextual analysis, not direct LLM vision input)
     UNKNOWN = "unknown"    # Fallback for unrecognized types
 
     @classmethod
@@ -56,7 +55,7 @@ class ContextFileType(str, Enum):
         elif extension == ".js":
             return cls.JAVASCRIPT
         elif extension in [".png", ".jpg", ".jpeg", ".gif", ".webp"]:
-            return cls.IMAGE_CONTEXT 
+            return cls.IMAGE 
         else:
             return cls.UNKNOWN
 

autobyteus/agent/phases/__init__.py

@@ -0,0 +1,18 @@
+# file: autobyteus/autobyteus/agent/phases/__init__.py
+"""
+This package contains components for defining and describing agent operational phases
+and their transitions.
+"""
+from .phase_enum import AgentOperationalPhase
+from .transition_info import PhaseTransitionInfo
+from .transition_decorator import phase_transition
+from .discover import PhaseTransitionDiscoverer
+from .manager import AgentPhaseManager
+
+__all__ = [
+    "AgentOperationalPhase",
+    "PhaseTransitionInfo",
+    "phase_transition",
+    "PhaseTransitionDiscoverer",
+    "AgentPhaseManager",
+]

autobyteus/agent/phases/discover.py

@@ -0,0 +1,52 @@
+# file: autobyteus/autobyteus/agent/phases/discover.py
+import inspect
+import logging
+from typing import List, Optional
+
+from autobyteus.agent.context.agent_phase_manager import AgentPhaseManager
+from .transition_info import PhaseTransitionInfo
+
+logger = logging.getLogger(__name__)
+
+class PhaseTransitionDiscoverer:
+    """
+    A utility class to discover all valid phase transitions within the system.
+    
+    It works by introspecting the AgentPhaseManager and finding methods
+    that have been decorated with the `@phase_transition` decorator.
+    """
+    _cached_transitions: Optional[List[PhaseTransitionInfo]] = None
+
+    @classmethod
+    def discover(cls) -> List[PhaseTransitionInfo]:
+        """
+        Discovers and returns a list of all possible phase transitions.
+        
+        The result is cached after the first call for performance.
+        
+        Returns:
+            A list of PhaseTransitionInfo objects, each describing a valid transition.
+        """
+        if cls._cached_transitions is not None:
+            return cls._cached_transitions
+
+        logger.debug("Discovering phase transitions from AgentPhaseManager for the first time.")
+        transitions = []
+        for name, method in inspect.getmembers(AgentPhaseManager, predicate=inspect.isfunction):
+            if hasattr(method, '_transition_info'):
+                info = getattr(method, '_transition_info')
+                if isinstance(info, PhaseTransitionInfo):
+                    transitions.append(info)
+        
+        # Sort for deterministic output
+        transitions.sort(key=lambda t: (t.target_phase.value, t.triggering_method))
+        
+        cls._cached_transitions = transitions
+        logger.info(f"Discovered and cached {len(transitions)} phase transitions.")
+        return transitions
+
+    @classmethod
+    def clear_cache(cls) -> None:
+        """Clears the cached list of transitions."""
+        cls._cached_transitions = None
+        logger.info("Cleared cached phase transitions.")

autobyteus/agent/phases/manager.py

@@ -0,0 +1,265 @@
+# file: autobyteus/autobyteus/agent/phases/manager.py
+import asyncio
+import logging
+from typing import TYPE_CHECKING, Optional, Dict, Any
+
+from .phase_enum import AgentOperationalPhase
+from .transition_decorator import phase_transition
+
+if TYPE_CHECKING:
+    from autobyteus.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__}.")
+
+    @phase_transition(
+        source_phases=[AgentOperationalPhase.SHUTDOWN_COMPLETE, AgentOperationalPhase.ERROR],
+        target_phase=AgentOperationalPhase.UNINITIALIZED,
+        description="Triggered when the agent runtime is started or restarted after being in a terminal state."
+    )
+    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}")
+
+    @phase_transition(
+        source_phases=[AgentOperationalPhase.UNINITIALIZED],
+        target_phase=AgentOperationalPhase.BOOTSTRAPPING,
+        description="Occurs when the agent's internal bootstrapping process begins."
+    )
+    async def notify_bootstrapping_started(self) -> None:
+        await self._transition_phase(AgentOperationalPhase.BOOTSTRAPPING, "notify_phase_bootstrapping_started")
+
+    @phase_transition(
+        source_phases=[AgentOperationalPhase.BOOTSTRAPPING],
+        target_phase=AgentOperationalPhase.IDLE,
+        description="Occurs when the agent successfully completes bootstrapping and is ready for input."
+    )
+    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}")
+
+    @phase_transition(
+        source_phases=[
+            AgentOperationalPhase.IDLE, AgentOperationalPhase.ANALYZING_LLM_RESPONSE,
+            AgentOperationalPhase.PROCESSING_TOOL_RESULT, AgentOperationalPhase.EXECUTING_TOOL,
+            AgentOperationalPhase.TOOL_DENIED
+        ],
+        target_phase=AgentOperationalPhase.PROCESSING_USER_INPUT,
+        description="Fires when the agent begins processing a new user message or inter-agent message."
+    )
+    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, AgentOperationalPhase.TOOL_DENIED]:
+            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}")
+
+    @phase_transition(
+        source_phases=[AgentOperationalPhase.PROCESSING_USER_INPUT, AgentOperationalPhase.PROCESSING_TOOL_RESULT],
+        target_phase=AgentOperationalPhase.AWAITING_LLM_RESPONSE,
+        description="Occurs just before the agent makes a call to the LLM."
+    )
+    async def notify_awaiting_llm_response(self) -> None:
+        await self._transition_phase(AgentOperationalPhase.AWAITING_LLM_RESPONSE, "notify_phase_awaiting_llm_response_started")
+
+    @phase_transition(
+        source_phases=[AgentOperationalPhase.AWAITING_LLM_RESPONSE],
+        target_phase=AgentOperationalPhase.ANALYZING_LLM_RESPONSE,
+        description="Occurs after the agent has received a complete response from the LLM and begins to analyze it."
+    )
+    async def notify_analyzing_llm_response(self) -> None:
+        await self._transition_phase(AgentOperationalPhase.ANALYZING_LLM_RESPONSE, "notify_phase_analyzing_llm_response_started")
+
+    @phase_transition(
+        source_phases=[AgentOperationalPhase.ANALYZING_LLM_RESPONSE],
+        target_phase=AgentOperationalPhase.AWAITING_TOOL_APPROVAL,
+        description="Occurs if the agent proposes a tool use that requires manual user approval."
+    )
+    async def notify_tool_execution_pending_approval(self, tool_invocation: 'ToolInvocation') -> None:
+        await self._transition_phase(AgentOperationalPhase.AWAITING_TOOL_APPROVAL, "notify_phase_awaiting_tool_approval_started")
+
+    @phase_transition(
+        source_phases=[AgentOperationalPhase.AWAITING_TOOL_APPROVAL],
+        target_phase=AgentOperationalPhase.EXECUTING_TOOL,
+        description="Occurs after a pending tool use has been approved and is about to be executed."
+    )
+    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.notify_tool_denied(tool_name)
+
+    @phase_transition(
+        source_phases=[AgentOperationalPhase.AWAITING_TOOL_APPROVAL],
+        target_phase=AgentOperationalPhase.TOOL_DENIED,
+        description="Occurs after a pending tool use has been denied by the user."
+    )
+    async def notify_tool_denied(self, tool_name: Optional[str]) -> None:
+        """Notifies that a tool execution has been denied."""
+        await self._transition_phase(
+            AgentOperationalPhase.TOOL_DENIED,
+            "notify_phase_tool_denied_started",
+            additional_data={"tool_name": tool_name, "denial_for_tool": tool_name}
+        )
+
+    @phase_transition(
+        source_phases=[AgentOperationalPhase.ANALYZING_LLM_RESPONSE],
+        target_phase=AgentOperationalPhase.EXECUTING_TOOL,
+        description="Occurs when an agent with auto-approval executes a tool."
+    )
+    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})
+
+    @phase_transition(
+        source_phases=[AgentOperationalPhase.EXECUTING_TOOL],
+        target_phase=AgentOperationalPhase.PROCESSING_TOOL_RESULT,
+        description="Fires after a tool has finished executing and the agent begins processing its result."
+    )
+    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})
+
+    @phase_transition(
+        source_phases=[
+            AgentOperationalPhase.PROCESSING_USER_INPUT, AgentOperationalPhase.ANALYZING_LLM_RESPONSE,
+            AgentOperationalPhase.PROCESSING_TOOL_RESULT
+        ],
+        target_phase=AgentOperationalPhase.IDLE,
+        description="Occurs when an agent completes a processing cycle and is waiting for new input."
+    )
+    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}")
+
+    @phase_transition(
+        source_phases=[
+            AgentOperationalPhase.UNINITIALIZED, AgentOperationalPhase.BOOTSTRAPPING, AgentOperationalPhase.IDLE,
+            AgentOperationalPhase.PROCESSING_USER_INPUT, AgentOperationalPhase.AWAITING_LLM_RESPONSE,
+            AgentOperationalPhase.ANALYZING_LLM_RESPONSE, AgentOperationalPhase.AWAITING_TOOL_APPROVAL,
+            AgentOperationalPhase.TOOL_DENIED, AgentOperationalPhase.EXECUTING_TOOL,
+            AgentOperationalPhase.PROCESSING_TOOL_RESULT, AgentOperationalPhase.SHUTTING_DOWN
+        ],
+        target_phase=AgentOperationalPhase.ERROR,
+        description="A catch-all transition that can occur from any non-terminal state if an unrecoverable error happens."
+    )
+    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}")
+
+    @phase_transition(
+        source_phases=[
+            AgentOperationalPhase.UNINITIALIZED, AgentOperationalPhase.BOOTSTRAPPING, AgentOperationalPhase.IDLE,
+            AgentOperationalPhase.PROCESSING_USER_INPUT, AgentOperationalPhase.AWAITING_LLM_RESPONSE,
+            AgentOperationalPhase.ANALYZING_LLM_RESPONSE, AgentOperationalPhase.AWAITING_TOOL_APPROVAL,
+            AgentOperationalPhase.TOOL_DENIED, AgentOperationalPhase.EXECUTING_TOOL,
+            AgentOperationalPhase.PROCESSING_TOOL_RESULT
+        ],
+        target_phase=AgentOperationalPhase.SHUTTING_DOWN,
+        description="Fires when the agent begins its graceful shutdown sequence."
+    )
+    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}")
+
+    @phase_transition(
+        source_phases=[AgentOperationalPhase.SHUTTING_DOWN],
+        target_phase=AgentOperationalPhase.SHUTDOWN_COMPLETE,
+        description="The final transition when the agent has successfully shut down and released its resources."
+    )
+    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/phases/phase_enum.py

@@ -0,0 +1,49 @@
+# file: autobyteus/autobyteus/agent/context/phases/phase_enum.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.
+    TOOL_DENIED = "tool_denied"                         # A proposed tool execution was denied by the user. Agent is processing the denial.
+    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.TOOL_DENIED,
+            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/phases/transition_decorator.py

@@ -0,0 +1,40 @@
+# file: autobyteus/autobyteus/agent/phases/transition_decorator.py
+import functools
+from typing import List, Callable
+
+from .phase_enum import AgentOperationalPhase
+from .transition_info import PhaseTransitionInfo
+
+def phase_transition(
+    source_phases: List[AgentOperationalPhase],
+    target_phase: AgentOperationalPhase,
+    description: str
+) -> Callable:
+    """
+    A decorator to annotate methods in AgentPhaseManager that cause a phase transition.
+    
+    This decorator does not alter the method's execution. It attaches a
+    PhaseTransitionInfo object to the method, making the transition discoverable
+    via introspection.
+    
+    Args:
+        source_phases: A list of valid source phases from which this transition can occur.
+        target_phase: The phase the agent will be in after this transition.
+        description: A human-readable description of what causes this transition.
+    """
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            return func(*args, **kwargs)
+
+        # Attach the metadata to the function object itself.
+        # We sort source phases for consistent representation.
+        sorted_sources = tuple(sorted(source_phases, key=lambda p: p.value))
+        setattr(wrapper, '_transition_info', PhaseTransitionInfo(
+            source_phases=sorted_sources,
+            target_phase=target_phase,
+            description=description,
+            triggering_method=func.__name__
+        ))
+        return wrapper
+    return decorator

autobyteus/agent/phases/transition_info.py

@@ -0,0 +1,33 @@
+# file: autobyteus/autobyteus/agent/phases/transition_info.py
+import logging
+from dataclasses import dataclass
+from typing import List, Tuple
+
+from .phase_enum import AgentOperationalPhase
+
+logger = logging.getLogger(__name__)
+
+@dataclass(frozen=True)
+class PhaseTransitionInfo:
+    """
+    A dataclass representing a valid, discoverable phase transition.
+    
+    This object provides the necessary metadata for users to understand what
+    kinds of phase hooks they can create.
+    
+    Attributes:
+        source_phases: A list of possible source phases for this transition.
+        target_phase: The single target phase for this transition.
+        description: A human-readable description of when this transition occurs.
+        triggering_method: The name of the method in AgentPhaseManager that triggers this.
+    """
+    source_phases: Tuple[AgentOperationalPhase, ...]
+    target_phase: AgentOperationalPhase
+    description: str
+    triggering_method: str
+
+    def __repr__(self) -> str:
+        sources = ", ".join(f"'{p.value}'" for p in self.source_phases)
+        return (f"<PhaseTransitionInfo sources=[{sources}] -> "
+                f"target='{self.target_phase.value}' "
+                f"triggered_by='{self.triggering_method}'>")

autobyteus/agent/remote_agent.py

@@ -5,7 +5,7 @@ import uuid # For generating default request IDs if ProtocolMessage doesn't
 from typing import Optional, Dict, Any, AsyncIterator
 
 from autobyteus.agent.agent import Agent 
-from autobyteus.agent.context.phases import AgentOperationalPhase
+from autobyteus.agent.phases import AgentOperationalPhase
 from autobyteus.agent.message.agent_input_user_message import AgentInputUserMessage
 from autobyteus.agent.message.inter_agent_message import InterAgentMessage
 from autobyteus.rpc.client import default_client_connection_manager, AbstractClientConnection

autobyteus/agent/runtime/agent_runtime.py

@@ -5,11 +5,10 @@ import traceback
 import concurrent.futures 
 from typing import Optional, Any, Callable, Awaitable, TYPE_CHECKING 
 
-from autobyteus.agent.context.agent_context import AgentContext 
-from autobyteus.agent.context.phases import AgentOperationalPhase 
+from autobyteus.agent.context import AgentContext 
+from autobyteus.agent.phases import AgentOperationalPhase, AgentPhaseManager 
 from autobyteus.agent.events.notifiers import AgentExternalEventNotifier 
 from autobyteus.agent.events import BaseEvent
-from autobyteus.agent.context.agent_phase_manager import AgentPhaseManager 
 from autobyteus.agent.handlers import EventHandlerRegistry
 from autobyteus.agent.runtime.agent_worker import AgentWorker
 
@@ -85,9 +84,8 @@ class AgentRuntime:
             return
         
         logger.info(f"AgentRuntime for '{agent_id}': Starting worker.")
-        # Removed redundant phase notification. The first meaningful phase change to BOOTSTRAPPING
-        # is triggered by the AgentBootstrapper within the worker's async context.
-        # self.phase_manager.notify_runtime_starting_and_uninitialized()
+        # The first meaningful phase change to BOOTSTRAPPING is triggered by the AgentBootstrapper
+        # within the worker's async context.
         self._worker.start() 
         logger.info(f"AgentRuntime for '{agent_id}': Worker start command issued. Worker will initialize itself.")
 
@@ -122,10 +120,7 @@ class AgentRuntime:
         await self.phase_manager.notify_shutdown_initiated() 
         await self._worker.stop(timeout=timeout) 
         
-        if self.context.llm_instance and hasattr(self.context.llm_instance, 'cleanup'):
-            cleanup_func = self.context.llm_instance.cleanup
-            if asyncio.iscoroutinefunction(cleanup_func): await cleanup_func()
-            else: cleanup_func()
+        # LLM instance cleanup is now handled by the AgentWorker before its loop closes.
         
         await self.phase_manager.notify_final_shutdown_complete() 
         logger.info(f"AgentRuntime for '{agent_id}' stop() method completed.")