autobyteus 1.2.1__py3-none-any.whl → 1.2.3__py3-none-any.whl

autobyteus/utils/gemini_model_mapping.py

@@ -0,0 +1,71 @@
+"""Runtime-aware Gemini model name resolution (API key vs Vertex AI).
+
+Gemini uses different public names for some models between the Developer API
+(`gemini-*-*-preview` suffixes) and Vertex AI (no `-preview`). Keeping this
+logic separate lets clients stay focused on I/O while we centralize naming
+quirks.
+"""
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+# Maps Developer API model names to their Vertex AI equivalents by modality.
+# As of Dec 18, 2025 the public LLM and image IDs are aligned across runtimes,
+# while some TTS variants still differ.
+_MODEL_RUNTIME_MAP = {
+    "tts": {
+        "gemini-2.5-flash-preview-tts": {
+            "vertex": "gemini-2.5-flash-tts",
+            "api_key": "gemini-2.5-flash-preview-tts",
+        },
+        "gemini-2.5-pro-preview-tts": {
+            "vertex": "gemini-2.5-pro-tts",
+            "api_key": "gemini-2.5-pro-preview-tts",
+        },
+    },
+    # For LLM & image the names are currently uniform across runtimes,
+    # but the structure is ready should Google introduce divergent aliases.
+    "llm": {
+        "gemini-3-pro-preview": {
+            "vertex": "gemini-3-pro-preview",
+            "api_key": "gemini-3-pro-preview",
+        },
+        "gemini-3-flash-preview": {
+            "vertex": "gemini-3-flash-preview",
+            "api_key": "gemini-3-flash-preview",
+        },
+    },
+    "image": {
+        "gemini-3-pro-image-preview": {
+            "vertex": "gemini-3-pro-image-preview",
+            "api_key": "gemini-3-pro-image-preview",
+        },
+        "gemini-2.5-flash-image": {
+            "vertex": "gemini-2.5-flash-image",
+            "api_key": "gemini-2.5-flash-image",
+        },
+    },
+}
+
+
+def resolve_model_for_runtime(model_value: str, modality: str, *, runtime: str | None = None) -> str:
+    """Return the correct model name for the active Gemini runtime.
+
+    Args:
+        model_value: The requested model name (usually from AudioModel.value).
+        modality: One of "tts", "llm", "image".
+        runtime: Explicit runtime identifier ("vertex" or "api_key").
+    """
+    if not runtime:
+        return model_value
+
+    modality_map = _MODEL_RUNTIME_MAP.get(modality, {})
+    runtime_map = modality_map.get(model_value)
+    if runtime_map and runtime in runtime_map:
+        mapped = runtime_map[runtime]
+        if mapped != model_value:
+            logger.info("Adjusting Gemini model for runtime '%s': '%s' -> '%s'", runtime, model_value, mapped)
+        return mapped
+
+    return model_value

autobyteus/utils/llm_output_formatter.py

@@ -0,0 +1,75 @@
+from typing import Any, Dict, List
+import dataclasses
+
+def format_to_clean_string(data: Any, indent: int = 0) -> str:
+    """
+    Formats complex data structures into a clean, human-readable string optimized for LLM consumption.
+    Avoids JSON syntax noise (braces, quotes) and YAML markers.
+    Supports Dicts, Lists, Dataclasses, and Pydantic models.
+    
+    Args:
+        data: The data to format.
+        indent: Current indentation level (spaces).
+        
+    Returns:
+        A formatted string representation of the data.
+    """
+    indent_str = " " * indent
+    
+    # Handle Dataclasses
+    if dataclasses.is_dataclass(data) and not isinstance(data, type):
+        data = dataclasses.asdict(data)
+    
+    # Handle Pydantic Models (v1: dict(), v2: model_dump())
+    elif hasattr(data, 'model_dump'):
+        data = data.model_dump()
+    elif hasattr(data, 'dict') and callable(getattr(data, 'dict')):
+        # Fallback for Pydantic V1 or similar
+        data = data.dict()
+
+    if isinstance(data, dict):
+        if not data:
+            return f"{indent_str}(empty dict)"
+        
+        lines = []
+        for key, value in data.items():
+            value_str = format_to_clean_string(value, indent + 2)
+            
+            if isinstance(value, (dict, list)) and value:
+                lines.append(f"{indent_str}{key}:\n{value_str}")
+            elif dataclasses.is_dataclass(value) or hasattr(value, 'model_dump') or hasattr(value, 'dict'):
+                 # Treat complex objects similarly to nested dicts
+                 lines.append(f"{indent_str}{key}:\n{value_str}")
+            elif isinstance(value, str) and '\n' in value:
+                # Multiline strings should also be on a new line for readability
+                lines.append(f"{indent_str}{key}:\n{value_str}")
+            else:
+                lines.append(f"{indent_str}{key}: {value_str.lstrip()}")
+        return "\n".join(lines)
+
+    elif isinstance(data, list):
+        if not data:
+            return f"{indent_str}(empty list)"
+        
+        lines = []
+        for item in data:
+            item_str = format_to_clean_string(item, indent + 2)
+            if isinstance(item, (dict, list)) or dataclasses.is_dataclass(item) or hasattr(item, 'model_dump'):
+                 lines.append(f"{indent_str}- \n{item_str}")
+            else:
+                lines.append(f"{indent_str}- {item_str.lstrip()}")
+        return "\n".join(lines)
+
+    elif isinstance(data, str):
+        lines = data.splitlines()
+        if not lines:
+            return f"{indent_str}\"\"" # Represent empty string explicitely or just empty? Let's use empty quotes for clarity if needed, or just nothing.
+            # Actually, user wants clean text. Empty string usually implies no content.
+            # Let's return "" if empty, but if it has content, indent it.
+            return ""
+        
+        formatted_lines = [f"{indent_str}{line}" for line in lines]
+        return "\n".join(formatted_lines)
+
+    else:
+        return f"{indent_str}{str(data)}"

autobyteus/utils/tool_call_format.py

@@ -0,0 +1,36 @@
+"""
+Helpers for resolving tool-call format selection.
+"""
+from __future__ import annotations
+
+import os
+
+
+ENV_TOOL_CALL_FORMAT = "AUTOBYTEUS_STREAM_PARSER"
+_VALID_FORMATS = {"xml", "json", "sentinel", "api_tool_call"}
+
+
+def resolve_tool_call_format() -> str:
+    """
+    Resolve the tool-call format from environment.
+
+    Returns one of: "xml", "json", "sentinel", "api_tool_call".
+    Defaults to "api_tool_call" when unset/invalid.
+    """
+    value = os.getenv(ENV_TOOL_CALL_FORMAT)
+    if not value:
+        return "api_tool_call"
+    value = value.strip().lower()
+    if value in _VALID_FORMATS:
+        return value
+    return "api_tool_call"
+
+
+def is_xml_tool_format() -> bool:
+    """Return True if tool-call format is forced to XML by environment."""
+    return resolve_tool_call_format() == "xml"
+
+
+def is_json_tool_format() -> bool:
+    """Return True if tool-call format is forced to JSON by environment."""
+    return resolve_tool_call_format() == "json"

autobyteus/workflow/agentic_workflow.py

@@ -5,7 +5,7 @@ from typing import Optional
 from autobyteus.workflow.runtime.workflow_runtime import WorkflowRuntime
 from autobyteus.workflow.events.workflow_events import ProcessUserMessageEvent, ToolApprovalWorkflowEvent
 from autobyteus.agent.message.agent_input_user_message import AgentInputUserMessage
-from autobyteus.workflow.phases.workflow_operational_phase import WorkflowOperationalPhase
+from autobyteus.workflow.status.workflow_status import WorkflowStatus
 
 logger = logging.getLogger(__name__)
 
@@ -89,5 +89,5 @@ class AgenticWorkflow:
         """Checks if the workflow's worker is running."""
         return self._runtime.is_running
         
-    def get_current_phase(self) -> WorkflowOperationalPhase: 
-        return self._runtime.context.state.current_phase
+    def get_current_status(self) -> WorkflowStatus: 
+        return self._runtime.context.state.current_status

autobyteus/workflow/bootstrap_steps/agent_tool_injection_step.py

@@ -10,7 +10,7 @@ from autobyteus.tools.registry import default_tool_registry
 
 if TYPE_CHECKING:
     from autobyteus.workflow.context.workflow_context import WorkflowContext
-    from autobyteus.workflow.phases.workflow_phase_manager import WorkflowPhaseManager
+    from autobyteus.workflow.status.workflow_status_manager import WorkflowStatusManager
 
 logger = logging.getLogger(__name__)
 
@@ -23,7 +23,7 @@ class AgentToolInjectionStep(BaseWorkflowBootstrapStep):
     The primary logic of applying the coordinator prompt has been moved to the TeamManager
     to ensure it happens just before the coordinator is created.
     """
-    async def execute(self, context: 'WorkflowContext', phase_manager: 'WorkflowPhaseManager') -> bool:
+    async def execute(self, context: 'WorkflowContext', status_manager: 'WorkflowStatusManager') -> bool:
         workflow_id = context.workflow_id
         logger.info(f"Workflow '{workflow_id}': Executing AgentToolInjectionStep (now a placeholder).")
         # The logic for injecting SendMessageTo and setting the coordinator prompt is now

autobyteus/workflow/bootstrap_steps/base_workflow_bootstrap_step.py

@@ -5,7 +5,7 @@ from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
     from autobyteus.workflow.context.workflow_context import WorkflowContext
-    from autobyteus.workflow.phases.workflow_phase_manager import WorkflowPhaseManager
+    from autobyteus.workflow.status.workflow_status_manager import WorkflowStatusManager
 
 logger = logging.getLogger(__name__)
 
@@ -13,7 +13,7 @@ class BaseWorkflowBootstrapStep(ABC):
     """Abstract base class for individual steps in the workflow bootstrapping process."""
 
     @abstractmethod
-    async def execute(self, context: 'WorkflowContext', phase_manager: 'WorkflowPhaseManager') -> bool:
+    async def execute(self, context: 'WorkflowContext', status_manager: 'WorkflowStatusManager') -> bool:
         """
         Executes the bootstrap step.
 

autobyteus/workflow/bootstrap_steps/coordinator_initialization_step.py

@@ -6,7 +6,7 @@ from autobyteus.workflow.bootstrap_steps.base_workflow_bootstrap_step import Bas
 
 if TYPE_CHECKING:
     from autobyteus.workflow.context.workflow_context import WorkflowContext
-    from autobyteus.workflow.phases.workflow_phase_manager import WorkflowPhaseManager
+    from autobyteus.workflow.status.workflow_status_manager import WorkflowStatusManager
 
 logger = logging.getLogger(__name__)
 
@@ -16,7 +16,7 @@ class CoordinatorInitializationStep(BaseWorkflowBootstrapStep):
     using the TeamManager. This ensures the coordinator is ready before the
     workflow becomes idle.
     """
-    async def execute(self, context: 'WorkflowContext', phase_manager: 'WorkflowPhaseManager') -> bool:
+    async def execute(self, context: 'WorkflowContext', status_manager: 'WorkflowStatusManager') -> bool:
         workflow_id = context.workflow_id
         logger.info(f"Workflow '{workflow_id}': Executing CoordinatorInitializationStep.")
         

autobyteus/workflow/bootstrap_steps/coordinator_prompt_preparation_step.py

@@ -9,7 +9,7 @@ from autobyteus.workflow.context.workflow_config import WorkflowConfig
 
 if TYPE_CHECKING:
     from autobyteus.workflow.context.workflow_context import WorkflowContext
-    from autobyteus.workflow.phases.workflow_phase_manager import WorkflowPhaseManager
+    from autobyteus.workflow.status.workflow_status_manager import WorkflowStatusManager
 
 logger = logging.getLogger(__name__)
 
@@ -18,7 +18,7 @@ class CoordinatorPromptPreparationStep(BaseWorkflowBootstrapStep):
     Bootstrap step to dynamically generate the coordinator's system prompt
     based on the workflow's structure and store it in the workflow's state.
     """
-    async def execute(self, context: 'WorkflowContext', phase_manager: 'WorkflowPhaseManager') -> bool:
+    async def execute(self, context: 'WorkflowContext', status_manager: 'WorkflowStatusManager') -> bool:
         workflow_id = context.workflow_id
         logger.info(f"Workflow '{workflow_id}': Executing CoordinatorPromptPreparationStep.")
         try:
@@ -51,11 +51,7 @@ class CoordinatorPromptPreparationStep(BaseWorkflowBootstrapStep):
     def _generate_prompt(self, context: 'WorkflowContext', member_node_ids: Dict[WorkflowNodeConfig, str]) -> str:
         prompt_parts: List[str] = []
 
-        tools_section = (
-            "### Your Tools\n"
-            "To accomplish your goal, you have access to the following tools. You should use them as needed.\n"
-            "{{tools}}"
-        )
+
 
         if member_node_ids:
             role_and_goal = (
@@ -89,7 +85,6 @@ class CoordinatorPromptPreparationStep(BaseWorkflowBootstrapStep):
                 rules_section = "### Execution Rules\n" + "\n".join(rules_list)
                 prompt_parts.append(rules_section)
 
-            prompt_parts.append(tools_section)
                 
             final_instruction = "### Your Task\nAnalyze the user's request, formulate a plan, and use the `send_message_to` tool to delegate tasks to your team. Address team members by their unique ID as listed under 'Your Team'."
             prompt_parts.append(final_instruction)
@@ -100,7 +95,6 @@ class CoordinatorPromptPreparationStep(BaseWorkflowBootstrapStep):
             )
             prompt_parts.append(role_and_goal)
             prompt_parts.append("### Your Team\nYou are working alone on this task.")
-            prompt_parts.append(tools_section)
             final_instruction = "### Your Task\nAnalyze the user's request, formulate a plan, and use your available tools to achieve the goal."
             prompt_parts.append(final_instruction)
 

autobyteus/workflow/bootstrap_steps/workflow_bootstrapper.py

@@ -11,7 +11,7 @@ from autobyteus.workflow.events.workflow_events import WorkflowReadyEvent
 
 if TYPE_CHECKING:
     from autobyteus.workflow.context.workflow_context import WorkflowContext
-    from autobyteus.workflow.phases.workflow_phase_manager import WorkflowPhaseManager
+    from autobyteus.workflow.status.workflow_status_manager import WorkflowStatusManager
 
 logger = logging.getLogger(__name__)
 
@@ -25,18 +25,18 @@ class WorkflowBootstrapper:
             CoordinatorInitializationStep(),
         ]
 
-    async def run(self, context: 'WorkflowContext', phase_manager: 'WorkflowPhaseManager') -> bool:
+    async def run(self, context: 'WorkflowContext', status_manager: 'WorkflowStatusManager') -> bool:
         workflow_id = context.workflow_id
-        await phase_manager.notify_bootstrapping_started()
+        await status_manager.notify_bootstrapping_started()
         logger.info(f"Workflow '{workflow_id}': Bootstrapper starting.")
 
         for step in self.bootstrap_steps:
             step_name = step.__class__.__name__
             logger.debug(f"Workflow '{workflow_id}': Executing bootstrap step: {step_name}")
-            if not await step.execute(context, phase_manager):
+            if not await step.execute(context, status_manager):
                 error_message = f"Bootstrap step {step_name} failed."
                 logger.error(f"Workflow '{workflow_id}': {error_message}")
-                await phase_manager.notify_error_occurred(error_message, f"Failed during bootstrap step '{step_name}'.")
+                await status_manager.notify_error_occurred(error_message, f"Failed during bootstrap step '{step_name}'.")
                 return False
         
         logger.info(f"Workflow '{workflow_id}': All bootstrap steps completed successfully.")
@@ -44,7 +44,7 @@ class WorkflowBootstrapper:
             await context.state.input_event_queues.enqueue_internal_system_event(WorkflowReadyEvent())
         else:
             logger.critical(f"Workflow '{workflow_id}': Bootstrap succeeded but queues not available.")
-            await phase_manager.notify_error_occurred("Queues unavailable after bootstrap.", "")
+            await status_manager.notify_error_occurred("Queues unavailable after bootstrap.", "")
             return False
             
         return True

autobyteus/workflow/bootstrap_steps/workflow_runtime_queue_initialization_step.py

@@ -7,13 +7,13 @@ from autobyteus.workflow.events.workflow_input_event_queue_manager import Workfl
 
 if TYPE_CHECKING:
     from autobyteus.workflow.context.workflow_context import WorkflowContext
-    from autobyteus.workflow.phases.workflow_phase_manager import WorkflowPhaseManager
+    from autobyteus.workflow.status.workflow_status_manager import WorkflowStatusManager
 
 logger = logging.getLogger(__name__)
 
 class WorkflowRuntimeQueueInitializationStep(BaseWorkflowBootstrapStep):
     """Bootstrap step for initializing the workflow's runtime event queues."""
-    async def execute(self, context: 'WorkflowContext', phase_manager: 'WorkflowPhaseManager') -> bool:
+    async def execute(self, context: 'WorkflowContext', status_manager: 'WorkflowStatusManager') -> bool:
         workflow_id = context.workflow_id
         logger.info(f"Workflow '{workflow_id}': Executing WorkflowRuntimeQueueInitializationStep.")
         try:

autobyteus/workflow/context/workflow_context.py

@@ -6,7 +6,7 @@ if TYPE_CHECKING:
     from autobyteus.workflow.context.workflow_config import WorkflowConfig
     from autobyteus.workflow.context.workflow_runtime_state import WorkflowRuntimeState
     from autobyteus.agent.agent import Agent
-    from autobyteus.workflow.phases.workflow_phase_manager import WorkflowPhaseManager
+    from autobyteus.workflow.status.workflow_status_manager import WorkflowStatusManager
     from autobyteus.workflow.context.team_manager import TeamManager
     from autobyteus.workflow.streaming.agent_event_multiplexer import AgentEventMultiplexer
     from autobyteus.agent.context import AgentConfig
@@ -49,8 +49,8 @@ class WorkflowContext:
         return None
 
     @property
-    def phase_manager(self) -> Optional['WorkflowPhaseManager']:
-        return self.state.phase_manager_ref
+    def status_manager(self) -> Optional['WorkflowStatusManager']:
+        return self.state.status_manager_ref
 
     @property
     def team_manager(self) -> Optional['TeamManager']:

autobyteus/workflow/context/workflow_runtime_state.py

@@ -2,13 +2,13 @@
 import logging
 from typing import List, Optional, TYPE_CHECKING, Dict
 
-from autobyteus.workflow.phases.workflow_operational_phase import WorkflowOperationalPhase
+from autobyteus.workflow.status.workflow_status import WorkflowStatus
 from autobyteus.agent.context import AgentConfig
 
 if TYPE_CHECKING:
     from autobyteus.agent.agent import Agent
     from autobyteus.workflow.events.workflow_input_event_queue_manager import WorkflowInputEventQueueManager
-    from autobyteus.workflow.phases.workflow_phase_manager import WorkflowPhaseManager
+    from autobyteus.workflow.status.workflow_status_manager import WorkflowStatusManager
     from autobyteus.workflow.context.workflow_node_config import WorkflowNodeConfig
     from autobyteus.workflow.context.team_manager import TeamManager
     from autobyteus.workflow.streaming.agent_event_multiplexer import AgentEventMultiplexer
@@ -22,7 +22,7 @@ class WorkflowRuntimeState:
             raise ValueError("WorkflowRuntimeState requires a non-empty string 'workflow_id'.")
 
         self.workflow_id: str = workflow_id
-        self.current_phase: WorkflowOperationalPhase = WorkflowOperationalPhase.UNINITIALIZED
+        self.current_status: WorkflowStatus = WorkflowStatus.UNINITIALIZED
         
         # State populated by bootstrap steps
         self.prepared_coordinator_prompt: Optional[str] = None
@@ -34,7 +34,7 @@ class WorkflowRuntimeState:
 
         # Runtime components and references
         self.input_event_queues: Optional['WorkflowInputEventQueueManager'] = None
-        self.phase_manager_ref: Optional['WorkflowPhaseManager'] = None
+        self.status_manager_ref: Optional['WorkflowStatusManager'] = None
         self.multiplexer_ref: Optional['AgentEventMultiplexer'] = None
 
         logger.info(f"WorkflowRuntimeState initialized for workflow_id '{self.workflow_id}'.")
@@ -48,6 +48,6 @@ class WorkflowRuntimeState:
     def __repr__(self) -> str:
         agents_count = len(self.team_manager.get_all_agents()) if self.team_manager else 0
         coordinator_set = self.team_manager.coordinator_agent is not None if self.team_manager else False
-        return (f"<WorkflowRuntimeState id='{self.workflow_id}', phase='{self.current_phase.value}', "
+        return (f"<WorkflowRuntimeState id='{self.workflow_id}', status='{self.current_status.value}', "
                 f"agents_count={agents_count}, coordinator_set={coordinator_set}, "
                 f"team_manager_set={self.team_manager is not None}>")

autobyteus/workflow/events/workflow_event_dispatcher.py

@@ -8,7 +8,7 @@ from autobyteus.workflow.events.workflow_events import BaseWorkflowEvent, Workfl
 if TYPE_CHECKING:
     from autobyteus.workflow.context.workflow_context import WorkflowContext
     from autobyteus.workflow.handlers.workflow_event_handler_registry import WorkflowEventHandlerRegistry
-    from autobyteus.workflow.phases.workflow_phase_manager import WorkflowPhaseManager
+    from autobyteus.workflow.status.workflow_status_manager import WorkflowStatusManager
 
 logger = logging.getLogger(__name__)
 
@@ -17,9 +17,9 @@ class WorkflowEventDispatcher:
 
     def __init__(self,
                  event_handler_registry: 'WorkflowEventHandlerRegistry',
-                 phase_manager: 'WorkflowPhaseManager'):
+                 status_manager: 'WorkflowStatusManager'):
         self.registry = event_handler_registry
-        self.phase_manager = phase_manager
+        self.status_manager = status_manager
 
     async def dispatch(self, event: BaseWorkflowEvent, context: 'WorkflowContext'):
         handler = self.registry.get_handler(type(event))
@@ -32,8 +32,8 @@ class WorkflowEventDispatcher:
         try:
             await handler.handle(event, context)
             if isinstance(event, WorkflowReadyEvent):
-                await self.phase_manager.notify_initialization_complete()
+                await self.status_manager.notify_initialization_complete()
         except Exception as e:
             error_msg = f"Error handling '{type(event).__name__}' in workflow '{workflow_id}': {e}"
             logger.error(error_msg, exc_info=True)
-            await self.phase_manager.notify_error_occurred(error_msg, traceback.format_exc())
+            await self.status_manager.notify_error_occurred(error_msg, traceback.format_exc())

autobyteus/workflow/handlers/lifecycle_workflow_event_handler.py

@@ -14,14 +14,14 @@ class LifecycleWorkflowEventHandler(BaseWorkflowEventHandler):
     """Logs various lifecycle events for a workflow."""
     async def handle(self, event: BaseWorkflowEvent, context: 'WorkflowContext') -> None:
         workflow_id = context.workflow_id
-        current_phase = context.state.current_phase.value
+        current_status = context.state.current_status.value
 
         if isinstance(event, WorkflowReadyEvent):
-            logger.info(f"Workflow '{workflow_id}' Logged WorkflowReadyEvent. Current phase: {current_phase}")
+            logger.info(f"Workflow '{workflow_id}' Logged WorkflowReadyEvent. Current status: {current_status}")
         elif isinstance(event, WorkflowErrorEvent):
             logger.error(
                 f"Workflow '{workflow_id}' Logged WorkflowErrorEvent: {event.error_message}. "
-                f"Details: {event.exception_details}. Current phase: {current_phase}"
+                f"Details: {event.exception_details}. Current status: {current_status}"
             )
         else:
             logger.warning(f"LifecycleWorkflowEventHandler received unhandled event type: {type(event).__name__}")

autobyteus/workflow/handlers/process_user_message_event_handler.py

@@ -15,13 +15,13 @@ logger = logging.getLogger(__name__)
 class ProcessUserMessageEventHandler(BaseWorkflowEventHandler):
     """Handles user messages by routing them to the specified target agent or sub-workflow."""
     async def handle(self, event: ProcessUserMessageEvent, context: 'WorkflowContext') -> None:
-        await context.phase_manager.notify_processing_started()
+        await context.status_manager.notify_processing_started()
         
         team_manager = context.team_manager
         if not team_manager:
             msg = f"Workflow '{context.workflow_id}': TeamManager not found. Cannot route message."
             logger.error(msg)
-            await context.phase_manager.notify_error_occurred(msg, "TeamManager is not initialized.")
+            await context.status_manager.notify_error_occurred(msg, "TeamManager is not initialized.")
             return
 
         try:
@@ -29,7 +29,7 @@ class ProcessUserMessageEventHandler(BaseWorkflowEventHandler):
         except Exception as e:
             msg = f"Workflow '{context.workflow_id}': Node '{event.target_agent_name}' not found or failed to start. Cannot route message. Error: {e}"
             logger.error(msg, exc_info=True)
-            await context.phase_manager.notify_error_occurred(msg, f"Node '{event.target_agent_name}' not found or failed to start.")
+            await context.status_manager.notify_error_occurred(msg, f"Node '{event.target_agent_name}' not found or failed to start.")
             return
 
         if isinstance(target_node, Agent):
@@ -41,6 +41,6 @@ class ProcessUserMessageEventHandler(BaseWorkflowEventHandler):
         else:
             msg = f"Target node '{event.target_agent_name}' is of an unsupported type: {type(target_node).__name__}"
             logger.error(f"Workflow '{context.workflow_id}': {msg}")
-            await context.phase_manager.notify_error_occurred(msg, "")
+            await context.status_manager.notify_error_occurred(msg, "")
 
-        await context.phase_manager.notify_processing_complete_and_idle()
+        await context.status_manager.notify_processing_complete_and_idle()

autobyteus/workflow/handlers/tool_approval_workflow_event_handler.py

@@ -21,14 +21,14 @@ class ToolApprovalWorkflowEventHandler(BaseWorkflowEventHandler):
         if not team_manager:
             msg = f"Workflow '{workflow_id}': TeamManager not found. Cannot route approval for agent '{event.agent_name}'."
             logger.error(msg)
-            await context.phase_manager.notify_error_occurred(msg, "TeamManager is not initialized.")
+            await context.status_manager.notify_error_occurred(msg, "TeamManager is not initialized.")
             return
 
         target_agent = await team_manager.ensure_agent_is_ready(event.agent_name)
         if not target_agent:
             msg = f"Workflow '{workflow_id}': Target agent '{event.agent_name}' for approval not found or failed to start."
             logger.error(msg)
-            await context.phase_manager.notify_error_occurred(msg, f"Agent '{event.agent_name}' not found or failed to start.")
+            await context.status_manager.notify_error_occurred(msg, f"Agent '{event.agent_name}' not found or failed to start.")
             return
 
         logger.info(f"Workflow '{workflow_id}': Posting tool approval (Approved: {event.is_approved}) to agent '{event.agent_name}' for invocation '{event.tool_invocation_id}'.")

autobyteus/workflow/runtime/workflow_runtime.py

@@ -4,7 +4,7 @@ import logging
 from typing import TYPE_CHECKING, Callable, Optional
 
 from autobyteus.workflow.context.workflow_context import WorkflowContext
-from autobyteus.workflow.phases.workflow_phase_manager import WorkflowPhaseManager
+from autobyteus.workflow.status.workflow_status_manager import WorkflowStatusManager
 from autobyteus.workflow.runtime.workflow_worker import WorkflowWorker
 from autobyteus.workflow.events.workflow_events import BaseWorkflowEvent
 from autobyteus.workflow.streaming.workflow_event_notifier import WorkflowExternalEventNotifier
@@ -20,10 +20,10 @@ class WorkflowRuntime:
     def __init__(self, context: WorkflowContext, event_handler_registry: 'WorkflowEventHandlerRegistry'):
         self.context = context
         self.notifier = WorkflowExternalEventNotifier(workflow_id=self.context.workflow_id, runtime_ref=self)
-        self.phase_manager = WorkflowPhaseManager(context=self.context, notifier=self.notifier)
+        self.status_manager = WorkflowStatusManager(context=self.context, notifier=self.notifier)
         
-        # --- FIX: Set the phase_manager_ref on the context's state BEFORE creating the worker ---
-        self.context.state.phase_manager_ref = self.phase_manager
+        # --- FIX: Set the status_manager_ref on the context's state BEFORE creating the worker ---
+        self.context.state.status_manager_ref = self.status_manager
         
         self._worker = WorkflowWorker(self.context, event_handler_registry)
         
@@ -50,8 +50,8 @@ class WorkflowRuntime:
             logger.info(f"WorkflowRuntime '{workflow_id}': Worker thread completed.")
         except Exception as e:
             logger.error(f"WorkflowRuntime '{workflow_id}': Worker thread terminated with exception: {e}", exc_info=True)
-        if not self.context.state.current_phase.is_terminal():
-             asyncio.run(self.phase_manager.notify_final_shutdown_complete())
+        if not self.context.state.current_status.is_terminal():
+             asyncio.run(self.status_manager.notify_final_shutdown_complete())
         
     def start(self):
         if self._worker.is_alive:
@@ -59,9 +59,9 @@ class WorkflowRuntime:
         self._worker.start()
 
     async def stop(self, timeout: float = 10.0):
-        await self.phase_manager.notify_shutdown_initiated()
+        await self.status_manager.notify_shutdown_initiated()
         await self._worker.stop(timeout=timeout)
-        await self.phase_manager.notify_final_shutdown_complete()
+        await self.status_manager.notify_final_shutdown_complete()
 
     async def submit_event(self, event: BaseWorkflowEvent):
         if not self._worker.is_alive:

autobyteus/workflow/runtime/workflow_worker.py

@@ -19,8 +19,8 @@ class WorkflowWorker:
     """Encapsulates the core event processing loop for a workflow."""
     def __init__(self, context: 'WorkflowContext', event_handler_registry: 'WorkflowEventHandlerRegistry'):
         self.context = context
-        self.phase_manager = self.context.phase_manager
-        self.event_dispatcher = WorkflowEventDispatcher(event_handler_registry, self.phase_manager)
+        self.status_manager = self.context.status_manager
+        self.event_dispatcher = WorkflowEventDispatcher(event_handler_registry, self.status_manager)
         
         self._thread_pool_manager = AgentThreadPoolManager()
         self._thread_future: Optional[concurrent.futures.Future] = None
@@ -70,7 +70,7 @@ class WorkflowWorker:
 
     async def async_run(self):
         bootstrapper = WorkflowBootstrapper()
-        if not await bootstrapper.run(self.context, self.phase_manager):
+        if not await bootstrapper.run(self.context, self.status_manager):
             logger.critical(f"Workflow '{self.context.workflow_id}' failed to initialize. Shutting down.")
             return
 

autobyteus/workflow/status/__init__.py

@@ -0,0 +1,11 @@
+# file: autobyteus/autobyteus/workflow/status/__init__.py
+"""
+This package contains components for defining and managing workflow operational statuses.
+"""
+from autobyteus.workflow.status.workflow_status import WorkflowStatus
+from autobyteus.workflow.status.workflow_status_manager import WorkflowStatusManager
+
+__all__ = [
+    "WorkflowStatus",
+    "WorkflowStatusManager",
+]

autobyteus/workflow/status/workflow_status.py

@@ -0,0 +1,19 @@
+# file: autobyteus/autobyteus/workflow/status/workflow_status.py
+from enum import Enum
+
+class WorkflowStatus(str, Enum):
+    """Defines the operational status of an AgenticWorkflow."""
+    UNINITIALIZED = "uninitialized"
+    BOOTSTRAPPING = "bootstrapping"
+    IDLE = "idle"
+    PROCESSING = "processing"
+    SHUTTING_DOWN = "shutting_down"
+    SHUTDOWN_COMPLETE = "shutdown_complete"
+    ERROR = "error"
+
+    def is_terminal(self) -> bool:
+        """Checks if the status is a terminal state."""
+        return self in [WorkflowStatus.SHUTDOWN_COMPLETE, WorkflowStatus.ERROR]
+
+    def __str__(self) -> str:
+        return self.value