camel-ai 0.2.75a5__py3-none-any.whl → 0.2.76__py3-none-any.whl

camel/societies/workforce/workforce.py

@@ -16,12 +16,15 @@ from __future__ import annotations
 import asyncio
 import concurrent.futures
 import json
+import os
 import time
 import uuid
 from collections import deque
 from enum import Enum
 from typing import (
+    TYPE_CHECKING,
     Any,
+    Callable,
     Coroutine,
     Deque,
     Dict,
@@ -31,8 +34,12 @@ from typing import (
     Set,
     Tuple,
     Union,
+    cast,
 )
 
+if TYPE_CHECKING:
+    from camel.utils.context_utils import ContextUtility
+
 from colorama import Fore
 
 from camel.agents import ChatAgent
@@ -43,19 +50,23 @@ from camel.societies.workforce.base import BaseNode
 from camel.societies.workforce.prompts import (
     ASSIGN_TASK_PROMPT,
     CREATE_NODE_PROMPT,
-    FAILURE_ANALYSIS_PROMPT,
+    FAILURE_ANALYSIS_RESPONSE_FORMAT,
+    QUALITY_EVALUATION_RESPONSE_FORMAT,
+    TASK_AGENT_SYSTEM_MESSAGE,
+    TASK_ANALYSIS_PROMPT,
     TASK_DECOMPOSE_PROMPT,
 )
 from camel.societies.workforce.role_playing_worker import RolePlayingWorker
-from camel.societies.workforce.single_agent_worker import SingleAgentWorker
+from camel.societies.workforce.single_agent_worker import (
+    SingleAgentWorker,
+)
 from camel.societies.workforce.structured_output_handler import (
     StructuredOutputHandler,
 )
 from camel.societies.workforce.task_channel import TaskChannel
 from camel.societies.workforce.utils import (
-    FailureContext,
-    RecoveryDecision,
     RecoveryStrategy,
+    TaskAnalysisResult,
     TaskAssignment,
     TaskAssignResult,
     WorkerConf,
@@ -70,6 +81,7 @@ from camel.tasks.task import (
 )
 from camel.toolkits import (
     CodeExecutionToolkit,
+    FunctionTool,
     SearchToolkit,
     TaskPlanningToolkit,
     ThinkingToolkit,
@@ -79,12 +91,20 @@ from camel.utils import dependencies_required
 
 from .workforce_logger import WorkforceLogger
 
-logger = get_logger(__name__)
+if os.environ.get("TRACEROOT_ENABLED", "False").lower() == "true":
+    try:
+        import traceroot  # type: ignore[import]
+
+        logger = traceroot.get_logger('camel')
+    except ImportError:
+        logger = get_logger(__name__)
+else:
+    logger = get_logger(__name__)
 
 # Constants for configuration values
 MAX_TASK_RETRIES = 3
 MAX_PENDING_TASKS_LIMIT = 20
-TASK_TIMEOUT_SECONDS = 480.0
+TASK_TIMEOUT_SECONDS = 600.0
 DEFAULT_WORKER_POOL_SIZE = 10
 
 
@@ -265,6 +285,7 @@ class Workforce(BaseNode):
         self._pause_event = asyncio.Event()
         self._pause_event.set()  # Initially not paused
         self._stop_requested = False
+        self._skip_requested = False
         self._snapshots: List[WorkforceSnapshot] = []
         self._completed_tasks: List[Task] = []
         self._loop: Optional[asyncio.AbstractEventLoop] = None
@@ -311,8 +332,7 @@ class Workforce(BaseNode):
             if coordinator_agent.system_message is not None:
                 user_sys_msg_content = coordinator_agent.system_message.content
                 combined_content = (
-                    f"{user_sys_msg_content}\n\n"
-                    f"{coord_agent_sys_msg.content}"
+                    f"{user_sys_msg_content}\n\n{coord_agent_sys_msg.content}"
                 )
                 combined_sys_msg = BaseMessage.make_assistant_message(
                     role_name=coordinator_agent.system_message.role_name,
@@ -336,10 +356,7 @@ class Workforce(BaseNode):
                     None,
                 ),
                 output_language=coordinator_agent.output_language,
-                tools=[
-                    tool.func
-                    for tool in coordinator_agent._internal_tools.values()
-                ],
+                tools=list(coordinator_agent._internal_tools.values()),
                 external_tools=[
                     schema
                     for schema in coordinator_agent._external_tool_schemas.values()  # noqa: E501
@@ -352,7 +369,7 @@ class Workforce(BaseNode):
         # Set up task agent with default system message and required tools
         task_sys_msg = BaseMessage.make_assistant_message(
             role_name="Task Planner",
-            content="You are going to handle tasks.",
+            content=TASK_AGENT_SYSTEM_MESSAGE,
         )
         task_planning_tools = TaskPlanningToolkit().get_tools()
 
@@ -377,8 +394,7 @@ class Workforce(BaseNode):
             if task_agent.system_message is not None:
                 user_task_sys_msg_content = task_agent.system_message.content
                 combined_task_content = (
-                    f"{user_task_sys_msg_content}\n\n"
-                    f"{task_sys_msg.content}"
+                    f"{user_task_sys_msg_content}\n\n{task_sys_msg.content}"
                 )
                 combined_task_sys_msg = BaseMessage.make_assistant_message(
                     role_name=task_agent.system_message.role_name,
@@ -389,9 +405,11 @@ class Workforce(BaseNode):
 
             # Since ChatAgent constructor uses a dictionary with
             # function names as keys, we don't need to manually deduplicate.
-            combined_tools = [
-                tool.func for tool in task_agent._internal_tools.values()
-            ] + [tool.func for tool in task_planning_tools]
+            combined_tools: List[Union[FunctionTool, Callable]] = cast(
+                List[Union[FunctionTool, Callable]],
+                list(task_agent._internal_tools.values())
+                + task_planning_tools,
+            )
 
             # Create a new agent with the provided agent's configuration
             # but with the combined system message and tools
@@ -438,10 +456,30 @@ class Workforce(BaseNode):
                 "better context continuity during task handoffs."
             )
 
+        # Shared context utility for workflow management (created lazily)
+        self._shared_context_utility: Optional["ContextUtility"] = None
+
         # ------------------------------------------------------------------
         # Helper for propagating pause control to externally supplied agents
         # ------------------------------------------------------------------
 
+    def _get_or_create_shared_context_utility(self) -> "ContextUtility":
+        r"""Get or create the shared context utility for workflow management.
+
+        This method creates the context utility only when needed, avoiding
+        unnecessary session folder creation during initialization.
+
+        Returns:
+            ContextUtility: The shared context utility instance.
+        """
+        if self._shared_context_utility is None:
+            from camel.utils.context_utils import ContextUtility
+
+            self._shared_context_utility = (
+                ContextUtility.get_workforce_shared()
+            )
+        return self._shared_context_utility
+
     def _validate_agent_compatibility(
         self, agent: ChatAgent, agent_context: str = "agent"
     ) -> None:
@@ -478,6 +516,9 @@ class Workforce(BaseNode):
                 "the Workforce."
             )
 
+    # ------------------------------------------------------------------
+    # Helper for propagating pause control to externally supplied agents
+    # ------------------------------------------------------------------
     def _attach_pause_event_to_agent(self, agent: ChatAgent) -> None:
         r"""Ensure the given ChatAgent shares this workforce's pause_event.
 
@@ -765,76 +806,124 @@ class Workforce(BaseNode):
                 self._update_dependencies_for_decomposition(task, subtasks)
             return subtasks
 
-    def _analyze_failure(
-        self, task: Task, error_message: str
-    ) -> RecoveryDecision:
-        r"""Analyze a task failure and decide on the best recovery strategy.
+    def _analyze_task(
+        self,
+        task: Task,
+        *,
+        for_failure: bool,
+        error_message: Optional[str] = None,
+    ) -> TaskAnalysisResult:
+        r"""Unified task analysis for both failures and quality evaluation.
+
+        This method consolidates the logic for analyzing task failures and
+        evaluating task quality, using the unified TASK_ANALYSIS_PROMPT.
 
         Args:
-            task (Task): The failed task
-            error_message (str): The error message from the failure
+            task (Task): The task to analyze
+            for_failure (bool): True for failure analysis, False for quality
+                evaluation
+            error_message (Optional[str]): Error message, required when
+                for_failure=True
 
         Returns:
-            RecoveryDecision: The decided recovery strategy with reasoning
+            TaskAnalysisResult: Unified analysis result with recovery strategy
+                and optional quality metrics
+
+        Raises:
+            ValueError: If for_failure=True but error_message is None
         """
-        # First, do a quick smart analysis based on error patterns
-        error_msg_lower = error_message.lower()
-        if any(
-            keyword in error_msg_lower
-            for keyword in [
-                'connection',
-                'network',
-                'server disconnected',
-                'timeout',
-                'apiconnectionerror',
+        # Validate required parameters
+        if for_failure and error_message is None:
+            raise ValueError("error_message is required when for_failure=True")
+
+        # Determine task result and issue-specific analysis based on context
+        if for_failure:
+            task_result = "N/A (task failed)"
+            issue_type = "Task Failure"
+            issue_analysis = f"**Error Message:** {error_message}"
+            response_format = FAILURE_ANALYSIS_RESPONSE_FORMAT
+            result_schema = TaskAnalysisResult
+            fallback_values: Dict[str, Any] = {
+                "reasoning": "Defaulting to retry due to parsing error",
+                "recovery_strategy": RecoveryStrategy.RETRY,
+                "modified_task_content": None,
+                "issues": [error_message] if error_message else [],
+            }
+            examples: List[Dict[str, Any]] = [
+                {
+                    "reasoning": "Temporary network error, worth retrying",
+                    "recovery_strategy": "retry",
+                    "modified_task_content": None,
+                    "issues": ["Network timeout"],
+                }
             ]
-        ):
-            return RecoveryDecision(
-                strategy=RecoveryStrategy.RETRY,
-                reasoning="Network/connection error detected, retrying task",
-                modified_task_content=None,
+        else:
+            # Quality evaluation
+            task_result = task.result or "No result available"
+            issue_type = "Quality Evaluation"
+            issue_analysis = (
+                "Provide a quality score (0-100) and list any specific "
+                "issues found."
             )
+            response_format = QUALITY_EVALUATION_RESPONSE_FORMAT
+            result_schema = TaskAnalysisResult
+            fallback_values = {
+                "reasoning": (
+                    "Defaulting to acceptable quality due to parsing error"
+                ),
+                "issues": [],
+                "recovery_strategy": None,
+                "modified_task_content": None,
+                "quality_score": 80,
+            }
+            examples = [
+                {
+                    "reasoning": (
+                        "Excellent implementation with comprehensive tests"
+                    ),
+                    "issues": [],
+                    "recovery_strategy": None,
+                    "modified_task_content": None,
+                    "quality_score": 98,
+                },
+                {
+                    "reasoning": (
+                        "Implementation incomplete with missing features"
+                    ),
+                    "issues": [
+                        "Incomplete implementation",
+                        "Missing error handling",
+                    ],
+                    "recovery_strategy": "replan",
+                    "modified_task_content": (
+                        "Previous attempt was incomplete. "
+                        "Please implement with: 1) Full feature "
+                        "coverage, 2) Proper error handling"
+                    ),
+                    "quality_score": 45,
+                },
+            ]
 
-        # Create failure context
-        failure_context = FailureContext(
+        # Format the unified analysis prompt
+        analysis_prompt = TASK_ANALYSIS_PROMPT.format(
             task_id=task.id,
             task_content=task.content,
+            task_result=task_result,
             failure_count=task.failure_count,
-            error_message=error_message,
-            worker_id=task.assigned_worker_id,
             task_depth=task.get_depth(),
-            additional_info=str(task.additional_info)
-            if task.additional_info
-            else None,
-        )
-
-        # Format the analysis prompt
-        analysis_prompt = FAILURE_ANALYSIS_PROMPT.format(
-            task_id=failure_context.task_id,
-            task_content=failure_context.task_content,
-            failure_count=failure_context.failure_count,
-            error_message=failure_context.error_message,
-            worker_id=failure_context.worker_id or "unknown",
-            task_depth=failure_context.task_depth,
-            additional_info=failure_context.additional_info or "None",
+            assigned_worker=task.assigned_worker_id or "unknown",
+            issue_type=issue_type,
+            issue_specific_analysis=issue_analysis,
+            response_format=response_format,
         )
 
         try:
-            # Check if we should use structured handler
             if self.use_structured_output_handler:
-                # Use structured handler
                 enhanced_prompt = (
                     self.structured_handler.generate_structured_prompt(
                         base_prompt=analysis_prompt,
-                        schema=RecoveryDecision,
-                        examples=[
-                            {
-                                "strategy": "RETRY",
-                                "reasoning": "Temporary network error, "
-                                "worth retrying",
-                                "modified_task_content": None,
-                            }
-                        ],
+                        schema=result_schema,
+                        examples=examples,
                     )
                 )
 
@@ -843,43 +932,220 @@ class Workforce(BaseNode):
 
                 result = self.structured_handler.parse_structured_response(
                     response.msg.content if response.msg else "",
-                    schema=RecoveryDecision,
-                    fallback_values={
-                        "strategy": RecoveryStrategy.RETRY,
-                        "reasoning": "Defaulting to retry due to parsing "
-                        "issues",
-                        "modified_task_content": None,
-                    },
+                    schema=result_schema,
+                    fallback_values=fallback_values,
                 )
-                # Ensure we return a RecoveryDecision instance
-                if isinstance(result, RecoveryDecision):
+
+                if isinstance(result, TaskAnalysisResult):
                     return result
                 elif isinstance(result, dict):
-                    return RecoveryDecision(**result)
+                    return result_schema(**result)
                 else:
-                    return RecoveryDecision(
-                        strategy=RecoveryStrategy.RETRY,
-                        reasoning="Failed to parse recovery decision",
-                        modified_task_content=None,
-                    )
+                    # Fallback based on context
+                    return TaskAnalysisResult(**fallback_values)
             else:
-                # Use existing native structured output code
                 self.task_agent.reset()
                 response = self.task_agent.step(
-                    analysis_prompt, response_format=RecoveryDecision
+                    analysis_prompt, response_format=result_schema
                 )
                 return response.msg.parsed
 
         except Exception as e:
             logger.warning(
-                f"Error during failure analysis: {e}, defaulting to RETRY"
+                f"Error during task analysis "
+                f"({'failure' if for_failure else 'quality'}): {e}, "
+                f"using fallback"
             )
-            return RecoveryDecision(
-                strategy=RecoveryStrategy.RETRY,
-                reasoning=f"Analysis failed due to error: {e!s}, "
-                f"defaulting to retry",
-                modified_task_content=None,
+            return TaskAnalysisResult(**fallback_values)
+
+    async def _apply_recovery_strategy(
+        self,
+        task: Task,
+        recovery_decision: TaskAnalysisResult,
+    ) -> bool:
+        r"""Apply the recovery strategy from a task analysis result.
+
+        This method centralizes the recovery logic for both execution failures
+        and quality-based failures.
+
+        Args:
+            task (Task): The task that needs recovery
+            recovery_decision (TaskAnalysisResult): The analysis result with
+                recovery strategy
+
+        Returns:
+            bool: True if workforce should halt (e.g., decompose needs
+                different handling), False otherwise
+        """
+        strategy = (
+            recovery_decision.recovery_strategy or RecoveryStrategy.RETRY
+        )
+        action_taken = ""
+
+        try:
+            if strategy == RecoveryStrategy.RETRY:
+                # Simply retry the task by reposting it to the same worker
+                # Check both _assignees dict and task.assigned_worker_id
+                assignee_id = (
+                    self._assignees.get(task.id) or task.assigned_worker_id
+                )
+
+                if assignee_id:
+                    # Retry with the same worker - no coordinator call needed
+                    await self._post_task(task, assignee_id)
+                    action_taken = f"retried with same worker {assignee_id}"
+                    logger.info(
+                        f"Task {task.id} retrying with same worker "
+                        f"{assignee_id} (no coordinator call)"
+                    )
+                else:
+                    # No previous assignment exists - find a new assignee
+                    logger.info(
+                        f"Task {task.id} has no previous assignee, "
+                        f"calling coordinator"
+                    )
+                    batch_result = await self._find_assignee([task])
+                    assignment = batch_result.assignments[0]
+                    self._assignees[task.id] = assignment.assignee_id
+                    await self._post_task(task, assignment.assignee_id)
+                    action_taken = (
+                        f"retried with new worker {assignment.assignee_id}"
+                    )
+
+            elif strategy == RecoveryStrategy.REPLAN:
+                # Modify the task content and retry
+                if recovery_decision.modified_task_content:
+                    task.content = recovery_decision.modified_task_content
+                    logger.info(f"Task {task.id} content modified for replan")
+
+                # Repost the modified task
+                if task.id in self._assignees:
+                    assignee_id = self._assignees[task.id]
+                    await self._post_task(task, assignee_id)
+                    action_taken = (
+                        f"replanned and retried with worker {assignee_id}"
+                    )
+                else:
+                    # Find a new assignee for the replanned task
+                    batch_result = await self._find_assignee([task])
+                    assignment = batch_result.assignments[0]
+                    self._assignees[task.id] = assignment.assignee_id
+                    await self._post_task(task, assignment.assignee_id)
+                    action_taken = (
+                        f"replanned and assigned to "
+                        f"worker {assignment.assignee_id}"
+                    )
+
+            elif strategy == RecoveryStrategy.REASSIGN:
+                # Reassign to a different worker
+                old_worker = task.assigned_worker_id
+                logger.info(
+                    f"Task {task.id} will be reassigned from worker "
+                    f"{old_worker}"
+                )
+
+                # Find a different worker
+                batch_result = await self._find_assignee([task])
+                assignment = batch_result.assignments[0]
+                new_worker = assignment.assignee_id
+
+                # If same worker, force find another
+                if new_worker == old_worker and len(self._children) > 1:
+                    logger.info("Same worker selected, finding alternative")
+                    # Try to find different worker by adding note to
+                    # task content
+                    task.content = (
+                        f"{task.content}\n\n"
+                        f"Note: Previous worker {old_worker} had quality "
+                        f"issues. Needs different approach."
+                    )
+                    batch_result = await self._find_assignee([task])
+                    assignment = batch_result.assignments[0]
+                    new_worker = assignment.assignee_id
+
+                self._assignees[task.id] = new_worker
+                await self._post_task(task, new_worker)
+                action_taken = f"reassigned from {old_worker} to {new_worker}"
+                logger.info(
+                    f"Task {task.id} reassigned from {old_worker} to "
+                    f"{new_worker}"
+                )
+
+            elif strategy == RecoveryStrategy.DECOMPOSE:
+                # Decompose the task into subtasks
+                reason = (
+                    "failure"
+                    if not recovery_decision.is_quality_evaluation
+                    else "quality issues"
+                )
+                logger.info(
+                    f"Task {task.id} will be decomposed due to {reason}"
+                )
+                subtasks_result = self._decompose_task(task)
+
+                # Handle both streaming and non-streaming results
+                if isinstance(subtasks_result, Generator):
+                    subtasks = []
+                    for new_tasks in subtasks_result:
+                        subtasks.extend(new_tasks)
+                else:
+                    subtasks = subtasks_result
+
+                if self.metrics_logger and subtasks:
+                    self.metrics_logger.log_task_decomposed(
+                        parent_task_id=task.id,
+                        subtask_ids=[st.id for st in subtasks],
+                    )
+                    for subtask in subtasks:
+                        self.metrics_logger.log_task_created(
+                            task_id=subtask.id,
+                            description=subtask.content,
+                            parent_task_id=task.id,
+                            task_type=subtask.type,
+                            metadata=subtask.additional_info,
+                        )
+
+                # Insert subtasks at the head of the queue
+                self._pending_tasks.extendleft(reversed(subtasks))
+                await self._post_ready_tasks()
+                action_taken = f"decomposed into {len(subtasks)} subtasks"
+
+                logger.info(
+                    f"Task {task.id} decomposed into {len(subtasks)} subtasks"
+                )
+
+                # Sync shared memory after task decomposition
+                if self.share_memory:
+                    logger.info(
+                        f"Syncing shared memory after task {task.id} "
+                        f"decomposition"
+                    )
+                    self._sync_shared_memory()
+
+                # For decompose, we return early with special handling
+                return True
+
+            elif strategy == RecoveryStrategy.CREATE_WORKER:
+                assignee = await self._create_worker_node_for_task(task)
+                await self._post_task(task, assignee.node_id)
+                action_taken = (
+                    f"created new worker {assignee.node_id} and assigned "
+                    f"task {task.id} to it"
+                )
+
+        except Exception as e:
+            logger.error(
+                f"Recovery strategy {strategy} failed for task {task.id}: {e}",
+                exc_info=True,
             )
+            raise
+
+        logger.debug(
+            f"Task {task.id} recovery: {action_taken}. "
+            f"Strategy: {strategy.value}"
+        )
+
+        return False
 
     # Human intervention methods
     async def _async_pause(self) -> None:
@@ -970,6 +1236,39 @@ class Workforce(BaseNode):
                 f"(event-loop not yet started)."
             )
 
+    async def _async_skip_gracefully(self) -> None:
+        r"""Async implementation of skip_gracefully to run on the event
+        loop.
+        """
+        self._skip_requested = True
+        if self._pause_event.is_set() is False:
+            self._pause_event.set()  # Resume if paused to process skip
+        logger.info(f"Workforce {self.node_id} skip requested.")
+
+    def skip_gracefully(self) -> None:
+        r"""Request workforce to skip current pending tasks and move to next
+        main task from the queue. If no main tasks exist, acts like
+        stop_gracefully.
+
+        This method clears the current pending subtasks and moves to the next
+        main task in the queue if available. Works both when the internal
+        event-loop is alive and when it has not yet been started.
+        """
+
+        if self._loop and not self._loop.is_closed():
+            self._submit_coro_to_loop(self._async_skip_gracefully())
+        else:
+            # Loop not yet created, set the flag synchronously so later
+            # startup will respect it.
+            self._skip_requested = True
+            # Ensure any pending pause is released so that when the loop does
+            # start it can see the skip request and exit.
+            self._pause_event.set()
+            logger.info(
+                f"Workforce {self.node_id} skip requested "
+                f"(event-loop not yet started)."
+            )
+
     def save_snapshot(self, description: str = "") -> None:
         r"""Save current state as a snapshot."""
         snapshot = WorkforceSnapshot(
@@ -1029,36 +1328,148 @@ class Workforce(BaseNode):
         content: str,
         task_id: Optional[str] = None,
         additional_info: Optional[Dict[str, Any]] = None,
+        as_subtask: bool = False,
         insert_position: int = -1,
     ) -> Task:
-        r"""Add a new task to the pending queue."""
-        new_task = Task(
+        r"""Add a new task to the workforce.
+
+        By default, this method adds a main task that will be decomposed into
+        subtasks. Set `as_subtask=True` to add a task directly to the pending
+        subtask queue without decomposition.
+
+        Args:
+            content (str): The content of the task.
+            task_id (Optional[str], optional): Optional ID for the task.
+                If not provided, a unique ID will be generated.
+            additional_info (Optional[Dict[str, Any]], optional): Optional
+                additional metadata for the task.
+            as_subtask (bool, optional): If True, adds the task directly to
+                the pending subtask queue. If False, adds as a main task that
+                will be decomposed. Defaults to False.
+            insert_position (int, optional): Position to insert the task in
+                the pending queue. Only applies when as_subtask=True.
+                Defaults to -1 (append to end).
+
+        Returns:
+            Task: The created task object.
+        """
+        if as_subtask:
+            new_task = Task(
+                content=content,
+                id=task_id or f"human_added_{len(self._pending_tasks)}",
+                additional_info=additional_info,
+            )
+
+            # Add directly to current pending subtasks
+            if insert_position == -1:
+                self._pending_tasks.append(new_task)
+            else:
+                # Convert deque to list, insert, then back to deque
+                tasks_list = list(self._pending_tasks)
+                tasks_list.insert(insert_position, new_task)
+                self._pending_tasks = deque(tasks_list)
+
+            logger.info(f"New subtask added to pending queue: {new_task.id}")
+            return new_task
+        else:
+            # Add as main task that needs decomposition
+            # Use additional_info to mark this task needs decomposition
+            # Make a copy to avoid modifying user's dict
+            info = additional_info.copy() if additional_info else {}
+            info['_needs_decomposition'] = True
+
+            task_count = sum(
+                1
+                for t in self._pending_tasks
+                if t.additional_info
+                and t.additional_info.get('_needs_decomposition')
+            )
+
+            new_task = Task(
+                content=content,
+                id=task_id or f"main_task_{task_count}",
+                additional_info=info,
+            )
+
+            self._pending_tasks.append(new_task)
+            logger.info(f"New main task added to pending queue: {new_task.id}")
+            return new_task
+
+    def add_main_task(
+        self,
+        content: str,
+        task_id: Optional[str] = None,
+        additional_info: Optional[Dict[str, Any]] = None,
+    ) -> Task:
+        r"""Add a new main task that will be decomposed into subtasks.
+
+        This is an alias for :meth:`add_task` with `as_subtask=False`.
+
+        Args:
+            content (str): The content of the main task.
+            task_id (Optional[str], optional): Optional ID for the task.
+            additional_info (Optional[Dict[str, Any]], optional): Optional
+                additional metadata.
+
+        Returns:
+            Task: The created main task object.
+        """
+        return self.add_task(
             content=content,
-            id=task_id or f"human_added_{len(self._pending_tasks)}",
+            task_id=task_id,
             additional_info=additional_info,
+            as_subtask=False,
         )
-        if insert_position == -1:
-            self._pending_tasks.append(new_task)
-        else:
-            # Convert deque to list, insert, then back to deque
-            tasks_list = list(self._pending_tasks)
-            tasks_list.insert(insert_position, new_task)
-            self._pending_tasks = deque(tasks_list)
 
-        logger.info(f"New task added: {new_task.id}")
-        return new_task
+    def add_subtask(
+        self,
+        content: str,
+        task_id: Optional[str] = None,
+        additional_info: Optional[Dict[str, Any]] = None,
+        insert_position: int = -1,
+    ) -> Task:
+        r"""Add a new subtask to the current pending queue.
+
+        This is an alias for :meth:`add_task` with `as_subtask=True`.
+
+        Args:
+            content (str): The content of the subtask.
+            task_id (Optional[str], optional): Optional ID for the task.
+            additional_info (Optional[Dict[str, Any]], optional): Optional
+                additional metadata.
+            insert_position (int, optional): Position to insert the task.
+                Defaults to -1 (append to end).
+
+        Returns:
+            Task: The created subtask object.
+        """
+        return self.add_task(
+            content=content,
+            task_id=task_id,
+            additional_info=additional_info,
+            as_subtask=True,
+            insert_position=insert_position,
+        )
 
     def remove_task(self, task_id: str) -> bool:
-        r"""Remove a task from the pending queue."""
-        # Convert to list to find and remove
-        tasks_list = list(self._pending_tasks)
-        for i, task in enumerate(tasks_list):
+        r"""Remove a task from the pending queue or main task queue.
+
+        Args:
+            task_id (str): The ID of the task to remove.
+
+        Returns:
+            bool: True if task was found and removed, False otherwise.
+        """
+        # Check main task queue first
+        pending_tasks_list = list(self._pending_tasks)
+        for i, task in enumerate(pending_tasks_list):
             if task.id == task_id:
-                tasks_list.pop(i)
-                self._pending_tasks = deque(tasks_list)
-                logger.info(f"Task {task_id} removed.")
+                pending_tasks_list.pop(i)
+                self._pending_tasks = deque(pending_tasks_list)
+                logger.info(f"Task {task_id} removed from pending queue.")
                 return True
-        logger.warning(f"Task {task_id} not found in pending tasks.")
+
+        logger.warning(f"Task {task_id} not found in any task queue.")
         return False
 
     def reorder_tasks(self, task_ids: List[str]) -> bool:
@@ -1173,26 +1584,21 @@ class Workforce(BaseNode):
             "main_task_id": self._task.id if self._task else None,
         }
 
-    @check_if_running(False)
-    async def process_task_async(
-        self, task: Task, interactive: bool = False
-    ) -> Task:
-        r"""Main entry point to process a task asynchronously.
+    async def handle_decompose_append_task(
+        self, task: Task, reset: bool = True
+    ) -> List[Task]:
+        r"""Handle task decomposition and validation with
+        workforce environment functions. Then append to
+        pending tasks if decomposition happened.
 
         Args:
             task (Task): The task to be processed.
-            interactive (bool, optional): If True, enables human-intervention
-                workflow (pause/resume/snapshot). Defaults to False, which
-                runs the task in a blocking one-shot manner.
+            reset (Bool): Should trigger workforce reset (Workforce must not
+                be running). Default: True
 
         Returns:
-            Task: The updated task.
+            List[Task]: The decomposed subtasks or the original task.
         """
-        # Delegate to intervention pipeline when requested to keep
-        # backward-compat.
-        if interactive:
-            return await self._process_task_with_snapshot(task)
-
         if not validate_task_content(task.content, task.id):
             task.state = TaskState.FAILED
             task.result = "Task failed: Invalid or empty content provided"
@@ -1200,10 +1606,16 @@ class Workforce(BaseNode):
                 f"Task {task.id} rejected: Invalid or empty content. "
                 f"Content preview: '{task.content}'"
             )
-            return task
+            return [task]
 
-        self.reset()
+        if reset and self._state != WorkforceState.RUNNING:
+            self.reset()
+            logger.info("Workforce reset before handling task.")
+
+        # Focus on the new task
         self._task = task
+        task.state = TaskState.FAILED
+
         if self.metrics_logger:
             self.metrics_logger.log_task_created(
                 task_id=task.id,
@@ -1211,7 +1623,6 @@ class Workforce(BaseNode):
                 task_type=task.type,
                 metadata=task.additional_info,
             )
-        task.state = TaskState.FAILED
         # The agent tend to be overconfident on the whole task, so we
         # decompose the task into subtasks first
         subtasks_result = self._decompose_task(task)
@@ -1237,20 +1648,46 @@ class Workforce(BaseNode):
                     task_type=subtask.type,
                     metadata=subtask.additional_info,
                 )
+
         if subtasks:
-            # If decomposition happened, the original task becomes a container.
-            # We only execute its subtasks.
+            # _pending_tasks will contain both undecomposed
+            # and decomposed tasks, so we use additional_info
+            # to mark the tasks that need decomposition instead
             self._pending_tasks.extendleft(reversed(subtasks))
         else:
             # If no decomposition, execute the original task.
             self._pending_tasks.append(task)
 
-        self.set_channel(TaskChannel())
-
-        await self.start()
+        return subtasks
 
-        if subtasks:
-            task.result = "\n\n".join(
+    @check_if_running(False)
+    async def process_task_async(
+        self, task: Task, interactive: bool = False
+    ) -> Task:
+        r"""Main entry point to process a task asynchronously.
+
+        Args:
+            task (Task): The task to be processed.
+            interactive (bool, optional): If True, enables human-intervention
+                workflow (pause/resume/snapshot). Defaults to False, which
+                runs the task in a blocking one-shot manner.
+
+        Returns:
+            Task: The updated task.
+        """
+        # Delegate to intervention pipeline when requested to keep
+        # backward-compat.
+        if interactive:
+            return await self._process_task_with_snapshot(task)
+
+        subtasks = await self.handle_decompose_append_task(task)
+
+        self.set_channel(TaskChannel())
+
+        await self.start()
+
+        if subtasks:
+            task.result = "\n\n".join(
                 f"--- Subtask {sub.id} Result ---\n{sub.result}"
                 for sub in task.subtasks
                 if sub.result
@@ -1326,39 +1763,8 @@ class Workforce(BaseNode):
             Task: The updated task.
         """
 
-        if not validate_task_content(task.content, task.id):
-            task.state = TaskState.FAILED
-            task.result = "Task failed: Invalid or empty content provided"
-            logger.warning(
-                f"Task {task.id} rejected: Invalid or empty content. "
-                f"Content preview: '{task.content}'"
-            )
-            return task
-
-        self.reset()
-        self._task = task
-        self._state = WorkforceState.RUNNING
-        task.state = TaskState.FAILED  # TODO: Add logic for OPEN
-
-        # Decompose the task into subtasks first
-        subtasks_result = self._decompose_task(task)
+        await self.handle_decompose_append_task(task)
 
-        # Handle both streaming and non-streaming results
-        if isinstance(subtasks_result, Generator):
-            # This is a generator (streaming mode)
-            subtasks = []
-            for new_tasks in subtasks_result:
-                subtasks.extend(new_tasks)
-        else:
-            # This is a regular list (non-streaming mode)
-            subtasks = subtasks_result
-        if subtasks:
-            # If decomposition happened, the original task becomes a container.
-            # We only execute its subtasks.
-            self._pending_tasks.extendleft(reversed(subtasks))
-        else:
-            # If no decomposition, execute the original task.
-            self._pending_tasks.append(task)
         self.set_channel(TaskChannel())
 
         # Save initial snapshot
@@ -1497,6 +1903,9 @@ class Workforce(BaseNode):
                         start_coroutine, self._loop
                     )
                 self._child_listening_tasks.append(child_task)
+            else:
+                # Close the coroutine to prevent RuntimeWarning
+                start_coroutine.close()
         else:
             # Close the coroutine to prevent RuntimeWarning
             start_coroutine.close()
@@ -1506,6 +1915,7 @@ class Workforce(BaseNode):
         description: str,
         worker: ChatAgent,
         pool_max_size: int = DEFAULT_WORKER_POOL_SIZE,
+        enable_workflow_memory: bool = False,
     ) -> Workforce:
         r"""Add a worker node to the workforce that uses a single agent.
         Can be called when workforce is paused to dynamically add workers.
@@ -1515,6 +1925,9 @@ class Workforce(BaseNode):
             worker (ChatAgent): The agent to be added.
             pool_max_size (int): Maximum size of the agent pool.
                 (default: :obj:`10`)
+            enable_workflow_memory (bool): Whether to enable workflow memory
+                accumulation. Set to True if you plan to call
+                save_workflow_memories(). (default: :obj:`False`)
 
         Returns:
             Workforce: The workforce node itself.
@@ -1541,6 +1954,8 @@ class Workforce(BaseNode):
             worker=worker,
             pool_max_size=pool_max_size,
             use_structured_output_handler=self.use_structured_output_handler,
+            context_utility=None,  # Will be set during save/load operations
+            enable_workflow_memory=enable_workflow_memory,
         )
         self._children.append(worker_node)
 
@@ -1696,6 +2111,7 @@ class Workforce(BaseNode):
         # Reset intervention state
         self._state = WorkforceState.IDLE
         self._stop_requested = False
+        self._skip_requested = False
         # Handle asyncio.Event in a thread-safe way
         if self._loop and not self._loop.is_closed():
             # If we have a loop, use it to set the event safely
@@ -1716,6 +2132,237 @@ class Workforce(BaseNode):
         else:
             self.metrics_logger = WorkforceLogger(workforce_id=self.node_id)
 
+    def save_workflow_memories(self) -> Dict[str, str]:
+        r"""Save workflow memories for all SingleAgentWorker instances in the
+        workforce.
+
+        This method iterates through all child workers and triggers workflow
+        saving for SingleAgentWorker instances using their
+        save_workflow_memories()
+        method.
+        Other worker types are skipped.
+
+        Returns:
+            Dict[str, str]: Dictionary mapping worker node IDs to save results.
+                Values are either file paths (success) or error messages
+                (failure).
+
+        Example:
+            >>> workforce = Workforce("My Team")
+            >>> # ... add workers and process tasks ...
+            >>> results = workforce.save_workflows()
+            >>> print(results)
+            {'worker_123': '/path/to/data_analyst_workflow_20250122.md',
+             'worker_456': 'error: No conversation context available'}
+        """
+        results = {}
+
+        # Get or create shared context utility for this save operation
+        shared_context_utility = self._get_or_create_shared_context_utility()
+
+        for child in self._children:
+            if isinstance(child, SingleAgentWorker):
+                try:
+                    # Set the shared context utility for this operation
+                    child._shared_context_utility = shared_context_utility
+                    child.worker.set_context_utility(shared_context_utility)
+
+                    result = child.save_workflow_memories()
+                    if result.get("status") == "success":
+                        results[child.node_id] = result.get(
+                            "file_path", "unknown_path"
+                        )
+                    else:
+                        # Error: check if there's a separate message field,
+                        # otherwise use the status itself
+                        error_msg = result.get(
+                            "message", result.get("status", "Unknown error")
+                        )
+                        results[child.node_id] = f"error: {error_msg}"
+
+                except Exception as e:
+                    results[child.node_id] = f"error: {e!s}"
+            else:
+                # Skip non-SingleAgentWorker types
+                results[child.node_id] = (
+                    f"skipped: {type(child).__name__} not supported"
+                )
+
+        logger.info(f"Workflow save completed for {len(results)} workers")
+        return results
+
+    def load_workflow_memories(
+        self,
+        max_files_to_load: int = 3,
+        session_id: Optional[str] = None,
+    ) -> Dict[str, bool]:
+        r"""Load workflow memories for all SingleAgentWorker instances in the
+        workforce.
+
+        This method iterates through all child workers and loads relevant
+        workflow files for SingleAgentWorker instances using their
+        load_workflow_memories()
+        method. Workers match files based on their description names.
+
+        Args:
+            max_files_to_load (int): Maximum number of workflow files to load
+                per worker. (default: :obj:`3`)
+            session_id (Optional[str]): Specific workforce session ID to load
+                from. If None, searches across all sessions.
+                (default: :obj:`None`)
+
+        Returns:
+            Dict[str, bool]: Dictionary mapping worker node IDs to load
+                success status.
+                True indicates successful loading, False indicates failure.
+
+        Example:
+            >>> workforce = Workforce("My Team")
+            >>> workforce.add_single_agent_worker(
+            ...     "data_analyst", analyst_agent
+            ... )
+            >>> success_status = workforce.load_workflows()
+            >>> print(success_status)
+            {'worker_123': True}  # Successfully loaded workflows for
+            # data_analyst
+        """
+        results = {}
+
+        # For loading, we don't create a new session - instead we search
+        # existing ones
+        # Each worker will search independently across all existing sessions
+
+        # First, load workflows for SingleAgentWorker instances
+        for child in self._children:
+            if isinstance(child, SingleAgentWorker):
+                try:
+                    # For loading, don't set shared context utility
+                    # Let each worker search across existing sessions
+                    success = child.load_workflow_memories(
+                        max_files_to_load=max_files_to_load,
+                        session_id=session_id,
+                    )
+                    results[child.node_id] = success
+
+                except Exception as e:
+                    logger.error(
+                        f"Failed to load workflow for {child.node_id}: {e!s}"
+                    )
+                    results[child.node_id] = False
+            else:
+                # Skip non-SingleAgentWorker types
+                results[child.node_id] = False
+
+        # Load aggregated workflow summaries for coordinator and task agents
+        self._load_management_agent_workflows(max_files_to_load, session_id)
+
+        logger.info(f"Workflow load completed for {len(results)} workers")
+        return results
+
+    def _load_management_agent_workflows(
+        self, max_files_to_load: int, session_id: Optional[str] = None
+    ) -> None:
+        r"""Load workflow summaries for coordinator and task planning agents.
+
+        This method loads aggregated workflow summaries to help:
+        - Coordinator agent: understand task assignment patterns and worker
+          capabilities
+        - Task agent: understand task decomposition patterns and
+          successful strategies
+
+        Args:
+            max_files_to_load (int): Maximum number of workflow files to load.
+            session_id (Optional[str]): Specific session ID to load from.
+                If None, searches across all sessions.
+        """
+        try:
+            import glob
+            import os
+            from pathlib import Path
+
+            from camel.utils.context_utils import ContextUtility
+
+            # For loading management workflows, search across all sessions
+            camel_workdir = os.environ.get("CAMEL_WORKDIR")
+            if camel_workdir:
+                base_dir = os.path.join(camel_workdir, "workforce_workflows")
+            else:
+                base_dir = "workforce_workflows"
+
+            # Search for workflow files in specified or all session directories
+            if session_id:
+                search_path = str(
+                    Path(base_dir) / session_id / "*_workflow*.md"
+                )
+            else:
+                search_path = str(Path(base_dir) / "*" / "*_workflow*.md")
+            workflow_files = glob.glob(search_path)
+
+            if not workflow_files:
+                logger.info(
+                    "No workflow files found for management agent context"
+                )
+                return
+
+            # Sort by modification time (most recent first)
+            workflow_files.sort(
+                key=lambda x: os.path.getmtime(x), reverse=True
+            )
+
+            # Load workflows for coordinator agent (up to 5 most recent)
+            coordinator_loaded = 0
+            for file_path in workflow_files[:max_files_to_load]:
+                try:
+                    filename = os.path.basename(file_path).replace('.md', '')
+                    session_dir = os.path.dirname(file_path)
+                    session_id = os.path.basename(session_dir)
+
+                    # Use shared context utility with specific session
+                    temp_utility = ContextUtility.get_workforce_shared(
+                        session_id
+                    )
+
+                    status = temp_utility.load_markdown_context_to_memory(
+                        self.coordinator_agent, filename
+                    )
+                    if "Context appended" in status:
+                        coordinator_loaded += 1
+                except Exception as e:
+                    logger.warning(
+                        f"Failed to load coordinator workflow {file_path}: {e}"
+                    )
+
+            # Load workflows for task agent (up to 3 most recent)
+            task_agent_loaded = 0
+            for file_path in workflow_files[:max_files_to_load]:
+                try:
+                    filename = os.path.basename(file_path).replace('.md', '')
+                    session_dir = os.path.dirname(file_path)
+                    session_id = os.path.basename(session_dir)
+
+                    # Use shared context utility with specific session
+                    temp_utility = ContextUtility.get_workforce_shared(
+                        session_id
+                    )
+
+                    status = temp_utility.load_markdown_context_to_memory(
+                        self.task_agent, filename
+                    )
+                    if "Context appended" in status:
+                        task_agent_loaded += 1
+                except Exception as e:
+                    logger.warning(
+                        f"Failed to load task agent workflow {file_path}: {e}"
+                    )
+
+            logger.info(
+                f"Loaded {coordinator_loaded} workflows for coordinator, "
+                f"{task_agent_loaded} workflows for task agent"
+            )
+
+        except Exception as e:
+            logger.error(f"Error loading management agent workflows: {e}")
+
     @check_if_running(False)
     def set_channel(self, channel: TaskChannel) -> None:
         r"""Set the channel for the node and all the child nodes under it."""
@@ -2063,8 +2710,40 @@ class Workforce(BaseNode):
             TaskAssignResult: Assignment result containing task assignments
                 with their dependencies.
         """
+        # Wait for workers to be ready before assignment with exponential
+        # backoff
+        worker_readiness_timeout = 2.0  # Maximum wait time in seconds
+        worker_readiness_check_interval = 0.05  # Initial check interval
+        start_time = time.time()
+        check_interval = worker_readiness_check_interval
+        backoff_multiplier = 1.5  # Exponential backoff factor
+        max_interval = 0.5  # Cap the maximum interval
+
+        while (time.time() - start_time) < worker_readiness_timeout:
+            valid_worker_ids = self._get_valid_worker_ids()
+            if len(valid_worker_ids) > 0:
+                elapsed = time.time() - start_time
+                logger.debug(
+                    f"Workers ready after {elapsed:.3f}s: "
+                    f"{len(valid_worker_ids)} workers available"
+                )
+                break
+
+            await asyncio.sleep(check_interval)
+            # Exponential backoff with cap
+            check_interval = min(
+                check_interval * backoff_multiplier, max_interval
+            )
+        else:
+            # Timeout reached, log warning but continue
+            logger.warning(
+                f"Worker readiness timeout after "
+                f"{worker_readiness_timeout}s, "
+                f"proceeding with {len(self._children)} children"
+            )
+            valid_worker_ids = self._get_valid_worker_ids()
+
         self.coordinator_agent.reset()
-        valid_worker_ids = self._get_valid_worker_ids()
 
         logger.debug(
             f"Sending batch assignment request to coordinator "
@@ -2098,7 +2777,24 @@ class Workforce(BaseNode):
                 invalid_assignments, tasks, valid_worker_ids
             )
         )
-        all_assignments = valid_assignments + retry_and_fallback_assignments
+
+        # Combine assignments with deduplication, prioritizing retry results
+        assignment_map = {a.task_id: a for a in valid_assignments}
+        assignment_map.update(
+            {a.task_id: a for a in retry_and_fallback_assignments}
+        )
+        all_assignments = list(assignment_map.values())
+
+        # Log any overwrites for debugging
+        valid_task_ids = {a.task_id for a in valid_assignments}
+        retry_task_ids = {a.task_id for a in retry_and_fallback_assignments}
+        overlap_task_ids = valid_task_ids & retry_task_ids
+
+        if overlap_task_ids:
+            logger.warning(
+                f"Retry assignments overrode {len(overlap_task_ids)} "
+                f"valid assignments for tasks: {sorted(overlap_task_ids)}"
+            )
 
         # Update Task.dependencies for all final assignments
         self._update_task_dependencies_from_assignments(all_assignments, tasks)
@@ -2176,8 +2872,7 @@ class Workforce(BaseNode):
                     "worker creation"
                 )
                 new_node_conf = WorkerConf(
-                    description=f"Fallback worker for task: "
-                    f"{task.content}",
+                    description=f"Fallback worker for task: {task.content}",
                     role="General Assistant",
                     sys_msg="You are a general assistant that can help "
                     "with various tasks.",
@@ -2187,7 +2882,7 @@ class Workforce(BaseNode):
                     response.msg.content,
                     schema=WorkerConf,
                     fallback_values={
-                        "description": f"Worker for task: " f"{task.content}",
+                        "description": f"Worker for task: {task.content}",
                         "role": "Task Specialist",
                         "sys_msg": f"You are a specialist for: {task.content}",
                     },
@@ -2215,8 +2910,7 @@ class Workforce(BaseNode):
                 )
                 # Create a fallback worker configuration
                 new_node_conf = WorkerConf(
-                    description=f"Fallback worker for "
-                    f"task: {task.content}",
+                    description=f"Fallback worker for task: {task.content}",
                     role="General Assistant",
                     sys_msg="You are a general assistant that can help "
                     "with various tasks.",
@@ -2310,6 +3004,9 @@ class Workforce(BaseNode):
         r"""Get the task that's published by this node and just get returned
         from the assignee. Includes timeout handling to prevent indefinite
         waiting.
+
+        Raises:
+            asyncio.TimeoutError: If waiting for task exceeds timeout
         """
         try:
             # Add timeout to prevent indefinite waiting
@@ -2317,6 +3014,17 @@ class Workforce(BaseNode):
                 self._channel.get_returned_task_by_publisher(self.node_id),
                 timeout=self.task_timeout_seconds,
             )
+        except asyncio.TimeoutError:
+            # Re-raise timeout errors to be handled by caller
+            # This prevents hanging when tasks are stuck
+            logger.warning(
+                f"Timeout waiting for task return in workforce "
+                f"{self.node_id}. "
+                f"Timeout: {self.task_timeout_seconds}s, "
+                f"Pending tasks: {len(self._pending_tasks)}, "
+                f"In-flight tasks: {self._in_flight_tasks}"
+            )
+            raise
         except Exception as e:
             error_msg = (
                 f"Error getting returned task {e} in "
@@ -2335,7 +3043,15 @@ class Workforce(BaseNode):
         tasks_to_assign = [
             task
             for task in self._pending_tasks
-            if task.id not in self._task_dependencies
+            if (
+                task.id not in self._task_dependencies
+                and (
+                    task.additional_info is None
+                    or not task.additional_info.get(
+                        "_needs_decomposition", False
+                    )
+                )
+            )
         ]
         if tasks_to_assign:
             logger.debug(
@@ -2371,21 +3087,141 @@ class Workforce(BaseNode):
         for task in self._pending_tasks:
             # A task must be assigned to be considered for posting
             if task.id in self._task_dependencies:
+                # Skip if task has already been posted to prevent duplicates
+                try:
+                    task_from_channel = await self._channel.get_task_by_id(
+                        task.id
+                    )
+                    # Check if task is already assigned to a worker
+                    if (
+                        task_from_channel
+                        and task_from_channel.assigned_worker_id
+                    ):
+                        logger.debug(
+                            f"Task {task.id} already assigned to "
+                            f"{task_from_channel.assigned_worker_id}, "
+                            f"skipping to prevent duplicate"
+                        )
+                        continue
+                except Exception as e:
+                    logger.info(
+                        f"Task {task.id} non existent in channel. "
+                        f"Assigning task: {e}"
+                    )
                 dependencies = self._task_dependencies[task.id]
-                # Check if all dependencies for this task are in the completed
-                # set and their state is DONE
-                if all(
-                    dep_id in completed_tasks_info
-                    and completed_tasks_info[dep_id] == TaskState.DONE
-                    for dep_id in dependencies
-                ):
-                    assignee_id = self._assignees[task.id]
-                    logger.debug(
-                        f"Posting task {task.id} to assignee {assignee_id}. "
-                        f"Dependencies met."
+
+                # Check if all dependencies are in completed state
+                all_deps_completed = all(
+                    dep_id in completed_tasks_info for dep_id in dependencies
+                )
+
+                # Only proceed with dependency checks if all deps are completed
+                if all_deps_completed:
+                    # Check if all dependencies succeeded (state is DONE)
+                    all_deps_done = all(
+                        completed_tasks_info[dep_id] == TaskState.DONE
+                        for dep_id in dependencies
                     )
-                    await self._post_task(task, assignee_id)
-                    posted_tasks.append(task)
+
+                    # Check if any dependency failed
+                    any_dep_failed = any(
+                        completed_tasks_info[dep_id] == TaskState.FAILED
+                        for dep_id in dependencies
+                    )
+
+                    if all_deps_done:
+                        # All dependencies completed successfully - post the
+                        # task
+                        assignee_id = self._assignees[task.id]
+                        logger.debug(
+                            f"Posting task {task.id} to "
+                            f"assignee {assignee_id}. "
+                            f"Dependencies met."
+                        )
+                        await self._post_task(task, assignee_id)
+                        posted_tasks.append(task)
+                    elif any_dep_failed:
+                        # Check if any failed dependencies can still be retried
+                        failed_deps = [
+                            dep_id
+                            for dep_id in dependencies
+                            if completed_tasks_info[dep_id] == TaskState.FAILED
+                        ]
+
+                        # Check if any failed dependency is still retryable
+                        failed_tasks_with_retry_potential = []
+                        permanently_failed_deps = []
+
+                        for dep_id in failed_deps:
+                            # Find the failed dependency task
+                            failed_task = next(
+                                (
+                                    t
+                                    for t in self._completed_tasks
+                                    if t.id == dep_id
+                                ),
+                                None,
+                            )
+                            if (
+                                failed_task
+                                and failed_task.failure_count
+                                < MAX_TASK_RETRIES
+                            ):
+                                failed_tasks_with_retry_potential.append(
+                                    dep_id
+                                )
+                            else:
+                                permanently_failed_deps.append(dep_id)
+
+                        # Only fail the task if ALL dependencies are
+                        # permanently failed
+                        if (
+                            permanently_failed_deps
+                            and not failed_tasks_with_retry_potential
+                        ):
+                            logger.error(
+                                f"Task {task.id} cannot proceed: dependencies "
+                                f"{permanently_failed_deps} have "
+                                f"permanently failed. "
+                                f"Marking task as failed."
+                            )
+                            task.state = TaskState.FAILED
+                            task.result = (
+                                f"Task failed due to permanently "
+                                f"failed dependencies: "
+                                f"{permanently_failed_deps}"
+                            )
+
+                            # Log the failure to metrics
+                            if self.metrics_logger:
+                                self.metrics_logger.log_task_failed(
+                                    task_id=task.id,
+                                    worker_id=task.assigned_worker_id
+                                    or "unknown",
+                                    error_message=task.result,
+                                    metadata={
+                                        'failure_reason': (
+                                            'dependency_failure'
+                                        ),
+                                        'failed_dependencies': (
+                                            permanently_failed_deps
+                                        ),
+                                    },
+                                )
+
+                            self._completed_tasks.append(task)
+                            self._cleanup_task_tracking(task.id)
+                            posted_tasks.append(task)  # Remove from pending
+                        else:
+                            # Some dependencies may still be retried, keep
+                            # task pending
+                            logger.debug(
+                                f"Task {task.id} waiting: dependencies "
+                                f"{failed_tasks_with_retry_potential} "
+                                f"failed but may be retried "
+                                f"(attempt < {MAX_TASK_RETRIES})"
+                            )
+                # else: Not all dependencies completed yet, skip this task
 
         # Step 3: Remove the posted tasks from the pending list
         for task in posted_tasks:
@@ -2397,21 +3233,30 @@ class Workforce(BaseNode):
                 pass
 
     async def _handle_failed_task(self, task: Task) -> bool:
+        r"""Handle a task that failed during execution.
+
+        Args:
+            task (Task): The failed task
+
+        Returns:
+            bool: True if workforce should halt, False otherwise
+        """
         task.failure_count += 1
 
         # Determine detailed failure information
-        # Use the actual error/result stored in task.result
         failure_reason = task.result or "Unknown error"
-
-        # Add context about the worker and task
         worker_id = task.assigned_worker_id or "unknown"
-        worker_info = f" (assigned to worker: {worker_id})"
-
-        detailed_error = f"{failure_reason}{worker_info}"
+        detailed_error = f"{failure_reason} (assigned to worker: {worker_id})"
 
         logger.error(
             f"Task {task.id} failed (attempt "
-            f"{task.failure_count}/3): {detailed_error}"
+            f"{task.failure_count}/{MAX_TASK_RETRIES}): {detailed_error}"
+        )
+
+        print(
+            f"{Fore.RED}❌ Task {task.id} failed "
+            f"(attempt {task.failure_count}/{MAX_TASK_RETRIES}): "
+            f"{failure_reason}{Fore.RESET}"
         )
 
         if self.metrics_logger:
@@ -2426,24 +3271,20 @@ class Workforce(BaseNode):
                 },
             )
 
-        # Check for immediate halt conditions - return immediately if we
-        # should halt
+        # Check for immediate halt conditions
         if task.failure_count >= MAX_TASK_RETRIES:
             logger.error(
                 f"Task {task.id} has exceeded maximum retry attempts "
-                f"({MAX_TASK_RETRIES}). Final failure "
-                f"reason: {detailed_error}. "
+                f"({MAX_TASK_RETRIES}). Final failure reason: "
+                f"{detailed_error}. "
                 f"Task content: '{task.content}'"
             )
             self._cleanup_task_tracking(task.id)
-            # Mark task as completed for dependency tracking before halting
             self._completed_tasks.append(task)
             if task.id in self._assignees:
                 await self._channel.archive_task(task.id)
             return True
 
-        # If too many tasks are failing rapidly, also halt to prevent infinite
-        # loops
         if len(self._pending_tasks) > MAX_PENDING_TASKS_LIMIT:
             logger.error(
                 f"Too many pending tasks ({len(self._pending_tasks)} > "
@@ -2451,18 +3292,24 @@ class Workforce(BaseNode):
                 f"explosion. Last failed task: {task.id}"
             )
             self._cleanup_task_tracking(task.id)
-            # Mark task as completed for dependency tracking before halting
             self._completed_tasks.append(task)
             if task.id in self._assignees:
                 await self._channel.archive_task(task.id)
             return True
 
         # Use intelligent failure analysis to decide recovery strategy
-        recovery_decision = self._analyze_failure(task, detailed_error)
+        recovery_decision = self._analyze_task(
+            task, for_failure=True, error_message=detailed_error
+        )
 
+        strategy_str = (
+            recovery_decision.recovery_strategy.value
+            if recovery_decision.recovery_strategy
+            else "none"
+        )
         logger.info(
             f"Task {task.id} failure "
-            f"analysis: {recovery_decision.strategy.value} - "
+            f"analysis: {strategy_str} - "
             f"{recovery_decision.reasoning}"
         )
 
@@ -2471,105 +3318,23 @@ class Workforce(BaseNode):
             await self._channel.archive_task(task.id)
         self._cleanup_task_tracking(task.id)
 
+        # Apply recovery strategy
         try:
-            if recovery_decision.strategy == RecoveryStrategy.RETRY:
-                # Simply retry the task by reposting it
-                if task.id in self._assignees:
-                    assignee_id = self._assignees[task.id]
-                    await self._post_task(task, assignee_id)
-                    action_taken = f"retried with same worker {assignee_id}"
-                else:
-                    # Find a new assignee and retry
-                    batch_result = await self._find_assignee([task])
-                    assignment = batch_result.assignments[0]
-                    self._assignees[task.id] = assignment.assignee_id
-                    await self._post_task(task, assignment.assignee_id)
-                    action_taken = (
-                        f"retried with new worker {assignment.assignee_id}"
-                    )
-
-            elif recovery_decision.strategy == RecoveryStrategy.REPLAN:
-                # Modify the task content and retry
-                if recovery_decision.modified_task_content:
-                    task.content = recovery_decision.modified_task_content
-                    logger.info(f"Task {task.id} content modified for replan")
-
-                # Repost the modified task
-                if task.id in self._assignees:
-                    assignee_id = self._assignees[task.id]
-                    await self._post_task(task, assignee_id)
-                    action_taken = (
-                        f"replanned and retried with worker {assignee_id}"
-                    )
-                else:
-                    # Find a new assignee for the replanned task
-                    batch_result = await self._find_assignee([task])
-                    assignment = batch_result.assignments[0]
-                    self._assignees[task.id] = assignment.assignee_id
-                    await self._post_task(task, assignment.assignee_id)
-                    action_taken = (
-                        f"replanned and assigned to "
-                        f"worker {assignment.assignee_id}"
-                    )
-
-            elif recovery_decision.strategy == RecoveryStrategy.DECOMPOSE:
-                # Decompose the task into subtasks
-                subtasks_result = self._decompose_task(task)
-
-                # Handle both streaming and non-streaming results
-                if isinstance(subtasks_result, Generator):
-                    # This is a generator (streaming mode)
-                    subtasks = []
-                    for new_tasks in subtasks_result:
-                        subtasks.extend(new_tasks)
-                else:
-                    # This is a regular list (non-streaming mode)
-                    subtasks = subtasks_result
-                if self.metrics_logger and subtasks:
-                    self.metrics_logger.log_task_decomposed(
-                        parent_task_id=task.id,
-                        subtask_ids=[st.id for st in subtasks],
-                    )
-                    for subtask in subtasks:
-                        self.metrics_logger.log_task_created(
-                            task_id=subtask.id,
-                            description=subtask.content,
-                            parent_task_id=task.id,
-                            task_type=subtask.type,
-                            metadata=subtask.additional_info,
-                        )
-                # Insert packets at the head of the queue
-                self._pending_tasks.extendleft(reversed(subtasks))
-
-                await self._post_ready_tasks()
-                action_taken = f"decomposed into {len(subtasks)} subtasks"
-
-                logger.debug(
-                    f"Task {task.id} failed and was {action_taken}. "
-                    f"Dependencies updated for subtasks."
-                )
-
-                # Sync shared memory after task decomposition
-                if self.share_memory:
-                    logger.info(
-                        f"Syncing shared memory after "
-                        f"task {task.id} decomposition"
-                    )
-                    self._sync_shared_memory()
+            is_decompose = await self._apply_recovery_strategy(
+                task, recovery_decision
+            )
 
-                # Check if any pending tasks are now ready to execute
-                await self._post_ready_tasks()
+            # For decompose, we handle it specially
+            if is_decompose:
+                # Task was decomposed, add to completed tasks
+                self._completed_tasks.append(task)
                 return False
 
-            elif recovery_decision.strategy == RecoveryStrategy.CREATE_WORKER:
-                assignee = await self._create_worker_node_for_task(task)
-                await self._post_task(task, assignee.node_id)
-                action_taken = (
-                    f"created new worker {assignee.node_id} and assigned "
-                    f"task {task.id} to it"
-                )
         except Exception as e:
-            logger.error(f"Recovery strategy failed for task {task.id}: {e}")
+            logger.error(
+                f"Recovery strategy failed for task {task.id}: {e}",
+                exc_info=True,
+            )
             # If max retries reached, halt the workforce
             if task.failure_count >= MAX_TASK_RETRIES:
                 self._completed_tasks.append(task)
@@ -2577,18 +3342,17 @@ class Workforce(BaseNode):
             self._completed_tasks.append(task)
             return False
 
+        # Task is being retried - don't add to completed tasks
+        # It will be added when it actually completes or permanently fails
         logger.debug(
-            f"Task {task.id} failed and was {action_taken}. "
-            f"Updating dependency state."
+            f"Task {task.id} is being retried (strategy: "
+            f"{recovery_decision.recovery_strategy}). "
+            f"Not adding to completed tasks until final outcome."
         )
-        # Mark task as completed for dependency tracking
-        self._completed_tasks.append(task)
 
-        # Sync shared memory after task completion to share knowledge
+        # Sync shared memory after task recovery
         if self.share_memory:
-            logger.info(
-                f"Syncing shared memory after task {task.id} completion"
-            )
+            logger.info(f"Syncing shared memory after task {task.id} recovery")
             self._sync_shared_memory()
 
         # Check if any pending tasks are now ready to execute
@@ -2793,6 +3557,124 @@ class Workforce(BaseNode):
         # Use logger.info or print, consistent with existing style
         logger.info(f"Workforce logs dumped to {file_path}")
 
+    async def _handle_skip_task(self) -> bool:
+        r"""Handle skip request by marking pending and in-flight tasks
+        as completed.
+
+        Returns:
+            bool: True if workforce should stop (no independent tasks),
+            False to continue.
+        """
+        logger.info("Skip requested, processing skip logic.")
+
+        # Mark all pending tasks as completed instead of just clearing
+        pending_tasks_to_complete = list(self._pending_tasks)
+        if pending_tasks_to_complete:
+            logger.info(
+                f"Marking {len(pending_tasks_to_complete)} pending tasks "
+                f"as completed."
+            )
+            for task in pending_tasks_to_complete:
+                # Don't remove tasks that need decomposition
+                if task.additional_info and task.additional_info.get(
+                    '_needs_decomposition', False
+                ):
+                    continue
+                # Set task state to DONE and add a completion message
+                task.state = TaskState.DONE
+                task.result = "Task marked as completed due to skip request"
+
+                # Use the existing handle completed task function
+                await self._handle_completed_task(task)
+
+        # Handle in-flight tasks if they exist
+        if self._in_flight_tasks > 0:
+            logger.info(
+                f"Found {self._in_flight_tasks} in-flight tasks. "
+                f"Retrieving and completing them."
+            )
+            try:
+                # Get all in-flight tasks for this publisher from the channel
+                in_flight_tasks = await self._channel.get_in_flight_tasks(
+                    self.node_id
+                )
+                logger.info(
+                    f"Retrieved {len(in_flight_tasks)} in-flight "
+                    f"tasks from channel."
+                )
+
+                for task in in_flight_tasks:
+                    # Set task state to DONE and add a completion message
+                    task.state = TaskState.DONE
+                    task.result = (
+                        "Task marked as completed due to skip request"
+                    )
+
+                    # Remove the task from the channel to avoid hanging
+                    await self._channel.remove_task(task.id)
+
+                    # Decrement in-flight counter
+                    self._decrement_in_flight_tasks(
+                        task.id, "skip request - removed from channel"
+                    )
+
+                    # Handle as completed task to update dependencies
+                    await self._handle_completed_task(task)
+
+                    logger.info(
+                        f"Completed in-flight task {task.id} due "
+                        f"to skip request."
+                    )
+
+            except Exception as e:
+                logger.error(
+                    f"Error handling in-flight tasks during skip: {e}",
+                    exc_info=True,
+                )
+                # Reset in-flight counter to prevent hanging
+                self._in_flight_tasks = 0
+
+        # Check if there are any pending tasks (including those needing
+        # decomposition)
+        if self._pending_tasks:
+            # Check if the first pending task needs decomposition
+            next_task = self._pending_tasks[0]
+            if next_task.additional_info and next_task.additional_info.get(
+                '_needs_decomposition'
+            ):
+                logger.info(
+                    f"Decomposing main task {next_task.id} after skip request."
+                )
+                try:
+                    # Remove the decomposition flag to avoid re-decomposition
+                    next_task.additional_info['_needs_decomposition'] = False
+
+                    # Decompose the task and append subtasks to _pending_tasks
+                    await self.handle_decompose_append_task(
+                        next_task, reset=False
+                    )
+
+                    # Mark the main task as completed and remove from pending
+                    await self._handle_completed_task(next_task)
+                    logger.info(
+                        f"Main task {next_task.id} decomposed after "
+                        f"skip request"
+                    )
+                except Exception as e:
+                    logger.error(
+                        f"Error decomposing main task {next_task.id} "
+                        f"after skip: {e}",
+                        exc_info=True,
+                    )
+
+            logger.info("Pending tasks available after skip, continuing.")
+            await self._post_ready_tasks()
+            return False  # Continue processing
+        else:
+            # No pending tasks available, act like stop
+            logger.info("No pending tasks available, acting like stop.")
+            return True  # Stop processing
+
     @check_if_running(False)
     async def _listen_to_channel(self) -> None:
         r"""Continuously listen to the channel, post task to the channel and
@@ -2821,6 +3703,75 @@ class Workforce(BaseNode):
                     logger.info("Stop requested, breaking execution loop.")
                     break
 
+                # Check for skip request after potential pause
+                if self._skip_requested:
+                    should_stop = await self._handle_skip_task()
+                    if should_stop:
+                        self._stop_requested = True
+                        break
+
+                    # Reset skip flag
+                    self._skip_requested = False
+                    continue
+
+                # Check if we should decompose a main task
+                # Only decompose when no tasks are in flight and pending queue
+                # is empty
+                if not self._pending_tasks and self._in_flight_tasks == 0:
+                    # All tasks completed, will exit loop
+                    break
+
+                # Check if the first pending task needs decomposition
+                # This happens when add_task(as_subtask=False) was called
+                if self._pending_tasks and self._in_flight_tasks == 0:
+                    next_task = self._pending_tasks[0]
+                    if (
+                        next_task.additional_info
+                        and next_task.additional_info.get(
+                            '_needs_decomposition'
+                        )
+                    ):
+                        logger.info(f"Decomposing main task: {next_task.id}")
+                        try:
+                            # Remove the decomposition flag to avoid
+                            # re-decomposition
+                            next_task.additional_info[
+                                '_needs_decomposition'
+                            ] = False
+
+                            # Decompose the task and append subtasks to
+                            # _pending_tasks
+                            await self.handle_decompose_append_task(
+                                next_task, reset=False
+                            )
+
+                            # Mark the main task as completed (decomposition
+                            # successful) and Remove it from pending tasks
+                            await self._handle_completed_task(next_task)
+                            logger.info(
+                                f"Main task {next_task.id} decomposed and "
+                                f"ready for processing"
+                            )
+                        except Exception as e:
+                            logger.error(
+                                f"Error decomposing main task {next_task.id}: "
+                                f"{e}",
+                                exc_info=True,
+                            )
+                            # Revert back to the queue for retry later if
+                            # decomposition failed
+                            if not self._pending_tasks:
+                                self._pending_tasks.appendleft(next_task)
+                            else:
+                                logger.warning(
+                                    "Pending tasks exist after decomposition "
+                                    "error."
+                                )
+
+                        # Immediately assign and post the transferred tasks
+                        await self._post_ready_tasks()
+                        continue
+
                 # Save snapshot before processing next task
                 if self._pending_tasks:
                     current_task = self._pending_tasks[0]
@@ -2835,9 +3786,24 @@ class Workforce(BaseNode):
                         self._last_snapshot_time = time.time()
 
                 # Get returned task
-                returned_task = await self._get_returned_task()
+                try:
+                    returned_task = await self._get_returned_task()
+                except asyncio.TimeoutError:
+                    # Handle timeout - check if we have tasks stuck in flight
+                    if self._in_flight_tasks > 0:
+                        logger.warning(
+                            f"Timeout waiting for {self._in_flight_tasks} "
+                            f"in-flight tasks. Breaking to prevent hanging."
+                        )
+                        # Break the loop to prevent indefinite hanging
+                        # The finally block will handle cleanup
+                        break
+                    else:
+                        # No tasks in flight, safe to continue
+                        await self._post_ready_tasks()
+                        continue
 
-                # If no task was returned, continue
+                # If no task was returned (other errors), continue
                 if returned_task is None:
                     logger.debug(
                         f"No task returned in workforce {self.node_id}. "
@@ -2896,11 +3862,88 @@ class Workforce(BaseNode):
                             )
                             continue
                     else:
-                        print(
-                            f"{Fore.CYAN}🎯 Task {returned_task.id} completed "
-                            f"successfully.{Fore.RESET}"
+                        quality_eval = self._analyze_task(
+                            returned_task, for_failure=False
                         )
-                        await self._handle_completed_task(returned_task)
+
+                        if not quality_eval.quality_sufficient:
+                            logger.info(
+                                f"Task {returned_task.id} quality check: "
+                                f"score={quality_eval.quality_score}, "
+                                f"issues={quality_eval.issues}, "
+                                f"strategy={quality_eval.recovery_strategy}"
+                            )
+
+                            # Check retry limit before attempting recovery
+                            if returned_task.failure_count >= 2:
+                                print(
+                                    f"{Fore.YELLOW}Task {returned_task.id} "
+                                    f"completed with low quality score: "
+                                    f"{quality_eval.quality_score} "
+                                    f"(retry limit reached){Fore.RESET}"
+                                )
+                                await self._handle_completed_task(
+                                    returned_task
+                                )
+                                continue
+
+                            # Print visual feedback for quality-failed tasks
+                            # with recovery strategy
+                            recovery_action = (
+                                quality_eval.recovery_strategy.value
+                                if quality_eval.recovery_strategy
+                                else ""
+                            )
+                            print(
+                                f"{Fore.YELLOW}⚠️ Task {returned_task.id} "
+                                f"failed quality check (score: "
+                                f"{quality_eval.quality_score}). "
+                                f"Issues: {', '.join(quality_eval.issues)}. "
+                                f"Recovery: {recovery_action}{Fore.RESET}"
+                            )
+
+                            # Mark as failed for recovery
+                            returned_task.failure_count += 1
+                            returned_task.state = TaskState.FAILED
+                            returned_task.result = (
+                                f"Quality insufficient (score: "
+                                f"{quality_eval.quality_score}). "
+                                f"Issues: {', '.join(quality_eval.issues)}"
+                            )
+
+                            # Clean up tracking before attempting recovery
+                            if returned_task.id in self._assignees:
+                                await self._channel.archive_task(
+                                    returned_task.id
+                                )
+                            self._cleanup_task_tracking(returned_task.id)
+
+                            # Apply LLM-recommended recovery strategy
+                            try:
+                                is_decompose = (
+                                    await self._apply_recovery_strategy(
+                                        returned_task, quality_eval
+                                    )
+                                )
+
+                                # For decompose, cleanup happens in the method
+                                if is_decompose:
+                                    continue
+
+                            except Exception as e:
+                                logger.error(
+                                    f"Error handling quality-failed task "
+                                    f"{returned_task.id}: {e}",
+                                    exc_info=True,
+                                )
+                                continue
+                        else:
+                            print(
+                                f"{Fore.CYAN}Task {returned_task.id} "
+                                f"completed successfully (quality score: "
+                                f"{quality_eval.quality_score}).{Fore.RESET}"
+                            )
+                            await self._handle_completed_task(returned_task)
                 elif returned_task.state == TaskState.FAILED:
                     try:
                         halt = await self._handle_failed_task(returned_task)