autobyteus 1.1.4__py3-none-any.whl → 1.1.5__py3-none-any.whl

autobyteus/task_management/converters/task_plan_converter.py

@@ -0,0 +1,48 @@
+"""
+Contains converters for translating LLM-friendly definition schemas into
+internal task management objects.
+"""
+import logging
+
+from autobyteus.task_management.task_plan import TaskPlan, Task
+from autobyteus.task_management.schemas import TaskPlanDefinitionSchema
+
+logger = logging.getLogger(__name__)
+
+class TaskPlanConverter:
+    """A converter to transform a TaskPlanDefinitionSchema into a system-ready TaskPlan."""
+
+    @staticmethod
+    def from_schema(plan_definition_schema: TaskPlanDefinitionSchema) -> TaskPlan:
+        """
+        Converts a TaskPlanDefinitionSchema object from an LLM into a fully-hydrated,
+        internal TaskPlan object.
+
+        This process involves:
+        1. Converting each TaskDefinitionSchema into a system Task object (which generates a unique task_id).
+        2. Assembling these Tasks into a TaskPlan (which generates a unique plan_id).
+        3. Hydrating the dependencies by replacing task_name references with the newly generated task_ids.
+
+        Args:
+            plan_definition_schema: The Pydantic model representing the LLM's output.
+
+        Returns:
+            A system-ready, internally consistent TaskPlan object.
+        """
+        logger.debug(f"Converting TaskPlanDefinitionSchema for goal: '{plan_definition_schema.overall_goal}'")
+        
+        # Step 1: Convert "TaskDefinitionSchema" objects into final, internal Task objects.
+        # This automatically generates the system-level 'task_id' for each.
+        final_tasks = [Task(**task_def.model_dump()) for task_def in plan_definition_schema.tasks]
+
+        # Step 2: Create the final TaskPlan object. This generates the 'plan_id'.
+        final_plan = TaskPlan(
+            overall_goal=plan_definition_schema.overall_goal,
+            tasks=final_tasks
+        )
+        
+        # Step 3: Hydrate dependencies: convert task_name references to system task_ids.
+        final_plan.hydrate_dependencies()
+        
+        logger.info(f"Successfully converted TaskPlanDefinitionSchema to internal TaskPlan with ID '{final_plan.plan_id}'.")
+        return final_plan

autobyteus/task_management/deliverable.py

@@ -0,0 +1,16 @@
+# file: autobyteus/autobyteus/task_management/deliverable.py
+"""
+Defines the core data model for a file deliverable.
+"""
+import datetime
+from pydantic import BaseModel, Field
+
+class FileDeliverable(BaseModel):
+    """
+    Represents the full, internal record of a file deliverable once it has been
+    submitted and attached to a task.
+    """
+    file_path: str
+    summary: str
+    author_agent_name: str
+    timestamp: datetime.datetime = Field(default_factory=datetime.datetime.utcnow)

autobyteus/task_management/deliverables/__init__.py

@@ -0,0 +1,8 @@
+"""
+Exposes the public components of the deliverables module.
+"""
+from .file_deliverable import FileDeliverable
+
+__all__ = [
+    "FileDeliverable",
+]

autobyteus/task_management/deliverables/file_deliverable.py

@@ -0,0 +1,15 @@
+"""
+Defines the data models for a file deliverable.
+"""
+import datetime
+from pydantic import BaseModel, Field
+
+class FileDeliverable(BaseModel):
+    """
+    Represents the full, internal record of a file deliverable once it has been
+    submitted and attached to a task.
+    """
+    file_path: str
+    summary: str
+    author_agent_name: str
+    timestamp: datetime.datetime = Field(default_factory=datetime.datetime.utcnow)

autobyteus/task_management/events.py

@@ -0,0 +1,27 @@
+# file: autobyteus/autobyteus/task_management/events.py
+"""
+Defines the Pydantic models for events emitted by a TaskBoard.
+"""
+from typing import List, Optional
+from pydantic import BaseModel
+
+from autobyteus.task_management.task_plan import TaskPlan
+from autobyteus.task_management.base_task_board import TaskStatus
+from .deliverable import FileDeliverable
+
+class BaseTaskBoardEvent(BaseModel):
+    """Base class for all task board events."""
+    team_id: str
+    plan_id: Optional[str]
+
+class TaskPlanPublishedEvent(BaseTaskBoardEvent):
+    """Payload for when a new task plan is published to the board."""
+    plan: TaskPlan
+
+class TaskStatusUpdatedEvent(BaseTaskBoardEvent):
+    """Payload for when a task's status is updated."""
+    task_id: str
+    new_status: TaskStatus
+    agent_name: str
+    # This field is added to ensure listeners get the full state, including deliverables.
+    deliverables: Optional[List[FileDeliverable]] = None

autobyteus/task_management/in_memory_task_board.py

@@ -0,0 +1,126 @@
+# file: autobyteus/autobyteus/task_management/in_memory_task_board.py
+"""
+An in-memory implementation of the BaseTaskBoard.
+It tracks task statuses in a simple dictionary and emits events on state changes.
+"""
+import logging
+from typing import Optional, List, Dict, Any
+from enum import Enum
+
+from autobyteus.events.event_types import EventType
+from .task_plan import TaskPlan, Task
+from .base_task_board import BaseTaskBoard, TaskStatus
+from .events import TaskPlanPublishedEvent, TaskStatusUpdatedEvent
+
+logger = logging.getLogger(__name__)
+
+class InMemoryTaskBoard(BaseTaskBoard):
+    """
+    An in-memory, dictionary-based implementation of the TaskBoard that emits
+    events on state changes.
+    """
+    def __init__(self, team_id: str):
+        """
+        Initializes the InMemoryTaskBoard.
+        """
+        # BaseTaskBoard now handles EventEmitter initialization
+        super().__init__(team_id=team_id)
+        self.current_plan: Optional[TaskPlan] = None
+        self.task_statuses: Dict[str, TaskStatus] = {}
+        self._task_map: Dict[str, Task] = {}
+        logger.info(f"InMemoryTaskBoard initialized for team '{self.team_id}'.")
+
+    def load_task_plan(self, plan: TaskPlan) -> bool:
+        """
+        Loads a new plan onto the board, resetting its state and emitting an event.
+        """
+        if not isinstance(plan, TaskPlan):
+            logger.error(f"Team '{self.team_id}': Failed to load task plan. Provided object is not a TaskPlan.")
+            return False
+
+        self.current_plan = plan
+        self.task_statuses = {task.task_id: TaskStatus.NOT_STARTED for task in plan.tasks}
+        self._task_map = {task.task_id: task for task in plan.tasks}
+        
+        logger.info(f"Team '{self.team_id}': New TaskPlan '{plan.plan_id}' loaded. Emitting event.")
+        
+        # Emit event
+        event_payload = TaskPlanPublishedEvent(
+            team_id=self.team_id,
+            plan_id=plan.plan_id,
+            plan=plan
+        )
+        self.emit(EventType.TASK_BOARD_PLAN_PUBLISHED, payload=event_payload)
+        
+        return True
+
+    def update_task_status(self, task_id: str, status: TaskStatus, agent_name: str) -> bool:
+        """
+        Updates the status of a specific task and emits an event.
+        """
+        if task_id not in self.task_statuses:
+            logger.warning(f"Team '{self.team_id}': Agent '{agent_name}' attempted to update status for non-existent task_id '{task_id}'.")
+            return False
+        
+        old_status = self.task_statuses.get(task_id, "N/A")
+        self.task_statuses[task_id] = status
+        log_msg = f"Team '{self.team_id}': Status of task '{task_id}' updated from '{old_status.value if isinstance(old_status, Enum) else old_status}' to '{status.value}' by agent '{agent_name}'."
+        logger.info(log_msg)
+        
+        # Find the task to get its deliverables for the event payload
+        task = self._task_map.get(task_id)
+        task_deliverables = task.file_deliverables if task else None
+
+        # Emit event
+        event_payload = TaskStatusUpdatedEvent(
+            team_id=self.team_id,
+            plan_id=self.current_plan.plan_id if self.current_plan else None,
+            task_id=task_id,
+            new_status=status,
+            agent_name=agent_name,
+            deliverables=task_deliverables
+        )
+        self.emit(EventType.TASK_BOARD_STATUS_UPDATED, payload=event_payload)
+
+        return True
+
+    def get_status_overview(self) -> Dict[str, Any]:
+        """
+        Returns a serializable dictionary of the board's current state.
+        """
+        if not self.current_plan:
+            return {
+                "plan_id": None,
+                "overall_goal": None,
+                "task_statuses": {},
+                "tasks": []
+            }
+        
+        return {
+            "plan_id": self.current_plan.plan_id,
+            "overall_goal": self.current_plan.overall_goal,
+            "task_statuses": {task_id: status.value for task_id, status in self.task_statuses.items()},
+            "tasks": [task.model_dump() for task in self.current_plan.tasks]
+        }
+
+    def get_next_runnable_tasks(self) -> List[Task]:
+        """
+        Calculates which tasks can be executed now based on dependencies and statuses.
+        """
+        runnable_tasks: List[Task] = []
+        if not self.current_plan:
+            return runnable_tasks
+
+        for task_id, status in self.task_statuses.items():
+            if status == TaskStatus.NOT_STARTED:
+                task = self._task_map.get(task_id)
+                if not task: continue
+                dependencies = task.dependencies
+                if not dependencies:
+                    runnable_tasks.append(task)
+                    continue
+                dependencies_met = all(self.task_statuses.get(dep_id) == TaskStatus.COMPLETED for dep_id in dependencies)
+                if dependencies_met:
+                    runnable_tasks.append(task)
+        
+        return runnable_tasks

autobyteus/task_management/schemas/__init__.py

@@ -0,0 +1,15 @@
+# file: autobyteus/autobyteus/task_management/schemas/__init__.py
+"""
+Exposes the public schema models for the task management module.
+"""
+from .plan_definition import TaskPlanDefinitionSchema, TaskDefinitionSchema
+from .task_status_report import TaskStatusReportSchema, TaskStatusReportItemSchema
+from .deliverable_schema import FileDeliverableSchema
+
+__all__ = [
+    "TaskPlanDefinitionSchema",
+    "TaskDefinitionSchema",
+    "TaskStatusReportSchema",
+    "TaskStatusReportItemSchema",
+    "FileDeliverableSchema",
+]

autobyteus/task_management/schemas/deliverable_schema.py

@@ -0,0 +1,13 @@
+# file: autobyteus/autobyteus/task_management/schemas/deliverable_schema.py
+"""
+Defines the Pydantic schema for submitting a file deliverable.
+"""
+from pydantic import BaseModel, Field
+
+class FileDeliverableSchema(BaseModel):
+    """
+    A Pydantic model representing the arguments for submitting a single
+    file deliverable. This is used as an input schema for tools.
+    """
+    file_path: str = Field(..., description="The relative path to the file being submitted.")
+    summary: str = Field(..., description="A summary of the work done on this file, explaining what is new or what was updated.")

autobyteus/task_management/schemas/plan_definition.py

@@ -0,0 +1,35 @@
+"""
+Defines the Pydantic models for task plan "definitions".
+
+These models represent the exact structure that an LLM is expected to generate.
+They serve as a blueprint or definition for a plan, which the system then uses
+to construct the final, internal TaskPlan object. They are used for input
+validation and for programmatically generating a JSON schema for tool descriptions.
+"""
+from typing import List
+from pydantic import BaseModel, Field, field_validator
+
+class TaskDefinitionSchema(BaseModel):
+    """A Pydantic model representing a single task as defined by an LLM."""
+    task_name: str = Field(..., description="A short, unique, descriptive name for this task within the plan (e.g., 'setup_project', 'implement_scraper'). Used for defining dependencies.")
+    assignee_name: str = Field(..., description="The name of the agent or sub-team assigned to this task.")
+    description: str = Field(..., description="A detailed description of the task.")
+    dependencies: List[str] = Field(
+        default_factory=list,
+        description="A list of 'task_name' values for tasks that must be completed first."
+    )
+
+class TaskPlanDefinitionSchema(BaseModel):
+    """A Pydantic model representing a full task plan as generated by an LLM."""
+    overall_goal: str = Field(..., description="The high-level objective of the entire plan.")
+    tasks: List[TaskDefinitionSchema] = Field(..., description="The list of tasks that make up this plan.")
+
+    @field_validator('tasks')
+    def task_names_must_be_unique(cls, tasks: List[TaskDefinitionSchema]) -> List[TaskDefinitionSchema]:
+        """Ensures that the LLM-provided task_names are unique within the plan."""
+        seen_names = set()
+        for task in tasks:
+            if task.task_name in seen_names:
+                raise ValueError(f"Duplicate task_name '{task.task_name}' found in task list. Each task_name must be unique.")
+            seen_names.add(task.task_name)
+        return tasks

autobyteus/task_management/schemas/task_status_report.py

@@ -0,0 +1,27 @@
+# file: autobyteus/autobyteus/task_management/schemas/task_status_report.py
+"""
+Defines the Pydantic models for LLM-friendly status reports.
+
+These models are designed to be returned by tools to the LLM, providing a
+clear and consistent structure that mirrors the input schemas (like TaskPlanDefinitionSchema)
+but includes dynamic state information (like task status).
+"""
+from typing import List, Optional
+from pydantic import BaseModel, Field
+
+from autobyteus.task_management.base_task_board import TaskStatus
+from autobyteus.task_management.deliverable import FileDeliverable
+
+class TaskStatusReportItemSchema(BaseModel):
+    """Represents the status of a single task in an LLM-friendly format."""
+    task_name: str = Field(..., description="The unique, descriptive name for this task.")
+    assignee_name: str = Field(..., description="The name of the agent or sub-team assigned to this task.")
+    description: str = Field(..., description="A detailed description of the task.")
+    dependencies: List[str] = Field(..., description="A list of 'task_name' values for tasks that must be completed first.")
+    status: TaskStatus = Field(..., description="The current status of this task.")
+    file_deliverables: List[FileDeliverable] = Field(default_factory=list, description="A list of files submitted as deliverables for this task.")
+
+class TaskStatusReportSchema(BaseModel):
+    """Represents a full task board status report in an LLM-friendly format."""
+    overall_goal: str = Field(..., description="The high-level objective of the entire plan.")
+    tasks: List[TaskStatusReportItemSchema] = Field(..., description="The list of tasks and their current statuses.")

autobyteus/task_management/task_plan.py

@@ -0,0 +1,110 @@
+# file: autobyteus/autobyteus/task_management/task_plan.py
+"""
+Defines the data structures for a task plan and its constituent tasks.
+These models represent the static, intended structure of a plan of action.
+"""
+import logging
+import uuid
+from typing import List, Dict, Any
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+# To avoid circular import, we use a string forward reference.
+from typing import TYPE_CHECKING
+if TYPE_CHECKING:
+    from autobyteus.task_management.deliverable import FileDeliverable
+
+logger = logging.getLogger(__name__)
+
+def generate_task_id():
+    """Generates a unique task identifier."""
+    return f"task_{uuid.uuid4().hex}"
+
+def generate_plan_id():
+    """Generates a unique plan identifier."""
+    return f"plan_{uuid.uuid4().hex}"
+
+class Task(BaseModel):
+    """
+    Represents a single, discrete unit of work within a larger TaskPlan.
+    """
+    task_name: str = Field(..., description="A short, unique, descriptive name for this task within the plan (e.g., 'setup_project', 'implement_scraper'). Used for defining dependencies.")
+    
+    task_id: str = Field(default_factory=generate_task_id, description="A unique system-generated identifier for this task within the plan.")
+    
+    assignee_name: str = Field(..., description="The unique name of the agent or sub-team responsible for executing this task (e.g., 'SoftwareEngineer', 'ResearchTeam').")
+    description: str = Field(..., description="A clear and concise description of what this task entails.")
+    
+    dependencies: List[str] = Field(
+        default_factory=list,
+        description="A list of 'task_name' values for tasks that must be completed before this one can be started."
+    )
+    
+    # This is the updated field as per user request.
+    file_deliverables: List["FileDeliverable"] = Field(
+        default_factory=list,
+        description="A list of file deliverables that were produced as a result of completing this task."
+    )
+
+    @model_validator(mode='before')
+    @classmethod
+    def handle_local_id_compatibility(cls, data: Any) -> Any:
+        """Handles backward compatibility for the 'local_id' field."""
+        if isinstance(data, dict) and 'local_id' in data:
+            data['task_name'] = data.pop('local_id')
+        # Compatibility for old artifact field
+        if isinstance(data, dict) and 'produced_artifact_ids' in data:
+            del data['produced_artifact_ids']
+        return data
+
+    def model_post_init(self, __context: Any) -> None:
+        """Called after the model is initialized and validated."""
+        logger.debug(f"Task created: Name='{self.task_name}', SystemID='{self.task_id}', Assignee='{self.assignee_name}'")
+
+
+class TaskPlan(BaseModel):
+    """
+    Represents a complete, static plan for achieving a high-level goal.
+    It is composed of a list of interconnected tasks.
+    """
+    plan_id: str = Field(default_factory=generate_plan_id, description="A unique system-generated identifier for this entire plan.")
+    
+    overall_goal: str = Field(..., description="The high-level objective that this plan is designed to achieve.")
+    tasks: List[Task] = Field(..., description="The list of tasks that make up this plan.")
+
+    @field_validator('tasks')
+    def task_names_must_be_unique(cls, tasks: List[Task]) -> List[Task]:
+        """Ensures that the LLM-provided task_names are unique within the plan."""
+        seen_names = set()
+        for task in tasks:
+            if task.task_name in seen_names:
+                raise ValueError(f"Duplicate task_name '{task.task_name}' found in task list. Each task_name must be unique within the plan.")
+            seen_names.add(task.task_name)
+        return tasks
+
+    def hydrate_dependencies(self) -> 'TaskPlan':
+        """
+        Converts the dependency list of task_names to system-generated task_ids.
+        This makes the plan internally consistent and ready for execution.
+        """
+        name_to_system_id_map = {task.task_name: task.task_id for task in self.tasks}
+        
+        for task in self.tasks:
+            # Create a new list for the resolved dependency IDs
+            resolved_deps = []
+            for dep_name in task.dependencies:
+                if dep_name not in name_to_system_id_map:
+                    raise ValueError(f"Task '{task.task_name}' has an invalid dependency: '{dep_name}' does not correspond to any task's name.")
+                resolved_deps.append(name_to_system_id_map[dep_name])
+            # Replace the old list of names with the new list of system_ids
+            task.dependencies = resolved_deps
+        
+        logger.debug(f"TaskPlan '{self.plan_id}' successfully hydrated dependencies.")
+        return self
+
+    def model_post_init(self, __context: Any) -> None:
+        """Called after the model is initialized and validated."""
+        logger.debug(f"TaskPlan created: ID='{self.plan_id}', Tasks={len(self.tasks)}")
+
+# This is necessary for Pydantic v2 to correctly handle the recursive model
+from autobyteus.task_management.deliverable import FileDeliverable
+Task.model_rebuild()

autobyteus/task_management/tools/__init__.py

@@ -0,0 +1,14 @@
+# file: autobyteus/autobyteus/task_management/tools/__init__.py
+"""
+This package contains the class-based tools related to task and project
+management within an agent team.
+"""
+from .get_task_board_status import GetTaskBoardStatus
+from .publish_task_plan import PublishTaskPlan
+from .update_task_status import UpdateTaskStatus
+
+__all__ = [
+    "GetTaskBoardStatus",
+    "PublishTaskPlan",
+    "UpdateTaskStatus",
+]

autobyteus/task_management/tools/get_task_board_status.py

@@ -0,0 +1,68 @@
+# file: autobyteus/autobyteus/task_management/tools/get_task_board_status.py
+import json
+import logging
+from typing import TYPE_CHECKING, Optional
+
+from autobyteus.tools.base_tool import BaseTool
+from autobyteus.tools.tool_category import ToolCategory
+from autobyteus.task_management.converters import TaskBoardConverter
+
+if TYPE_CHECKING:
+    from autobyteus.agent.context import AgentContext
+    from autobyteus.agent_team.context import AgentTeamContext
+
+logger = logging.getLogger(__name__)
+
+class GetTaskBoardStatus(BaseTool):
+    """A tool for agents to get a current snapshot of the team's TaskBoard."""
+
+    CATEGORY = ToolCategory.TASK_MANAGEMENT
+
+    @classmethod
+    def get_name(cls) -> str:
+        return "GetTaskBoardStatus"
+
+    @classmethod
+    def get_description(cls) -> str:
+        return (
+            "Retrieves the current status of the team's task board, including the overall goal "
+            "and the status of all individual tasks. Returns the status as a structured, LLM-friendly JSON string."
+        )
+
+    @classmethod
+    def get_argument_schema(cls) -> Optional[None]:
+        # This tool takes no arguments.
+        return None
+
+    async def _execute(self, context: 'AgentContext') -> str:
+        """
+        Executes the tool by fetching the task board and using a converter to
+        generate an LLM-friendly report.
+        """
+        logger.info(f"Agent '{context.agent_id}' is executing GetTaskBoardStatus.")
+        
+        team_context: Optional['AgentTeamContext'] = context.custom_data.get("team_context")
+        if not team_context:
+            error_msg = "Error: Team context is not available to the agent. Cannot access the task board."
+            logger.error(f"Agent '{context.agent_id}': {error_msg}")
+            return error_msg
+
+        task_board = getattr(team_context.state, 'task_board', None)
+        if not task_board:
+            error_msg = "Error: Task board has not been initialized for this team."
+            logger.error(f"Agent '{context.agent_id}': {error_msg}")
+            return error_msg
+        
+        try:
+            status_report_schema = TaskBoardConverter.to_schema(task_board)
+            
+            if not status_report_schema:
+                return "The task board is currently empty. No plan has been published."
+            
+            logger.info(f"Agent '{context.agent_id}' successfully retrieved and formatted task board status.")
+            return status_report_schema.model_dump_json(indent=2)
+            
+        except Exception as e:
+            error_msg = f"An unexpected error occurred while retrieving or formatting task board status: {e}"
+            logger.error(f"Agent '{context.agent_id}': {error_msg}", exc_info=True)
+            return error_msg

autobyteus/task_management/tools/publish_task_plan.py

@@ -0,0 +1,113 @@
+# file: autobyteus/autobyteus/task_management/tools/publish_task_plan.py
+import json
+import logging
+from typing import TYPE_CHECKING, Optional, Dict, Any
+
+from pydantic import ValidationError
+# No longer need GenerateJsonSchema from pydantic.json_schema
+# from pydantic.json_schema import GenerateJsonSchema
+
+from autobyteus.tools.base_tool import BaseTool
+from autobyteus.tools.tool_category import ToolCategory
+from autobyteus.tools.parameter_schema import ParameterSchema, ParameterDefinition, ParameterType
+from autobyteus.task_management.schemas import TaskPlanDefinitionSchema
+from autobyteus.task_management.converters import TaskPlanConverter, TaskBoardConverter
+
+if TYPE_CHECKING:
+    from autobyteus.agent.context import AgentContext
+    from autobyteus.agent_team.context import AgentTeamContext
+
+logger = logging.getLogger(__name__)
+
+class PublishTaskPlan(BaseTool):
+    """A tool for the coordinator to parse and load a generated plan into the TaskBoard."""
+
+    CATEGORY = ToolCategory.TASK_MANAGEMENT
+
+    # The failing custom InlineSchemaGenerator has been removed.
+
+    @classmethod
+    def get_name(cls) -> str:
+        return "PublishTaskPlan"
+
+    @classmethod
+    def get_description(cls) -> str:
+        return (
+            "Parses a structured object representing a complete task plan, converts it into a "
+            "system-ready format, and loads it onto the team's shared task board. "
+            "This action resets the task board with the new plan. Upon success, it returns "
+            "the initial status of the newly loaded task board. "
+            "This tool should typically only be used by the team coordinator."
+        )
+
+    @classmethod
+    def get_argument_schema(cls) -> Optional[ParameterSchema]:
+        schema = ParameterSchema()
+        
+        # CORRECTED IMPLEMENTATION:
+        # A direct, standard call to model_json_schema(). This generates a valid
+        # JSON schema with $refs, which the framework handles correctly.
+        # This completely avoids the TypeError caused by the unsupported 'ref_strategy' argument.
+        object_json_schema = TaskPlanDefinitionSchema.model_json_schema()
+        
+        schema.add_parameter(ParameterDefinition(
+            name="plan",
+            param_type=ParameterType.OBJECT,
+            description=(
+                "A structured object representing a complete task plan. This object defines the overall goal "
+                "and a list of tasks with their assignees, descriptions, and dependencies. "
+                "Each task must have a unique name within the plan."
+            ),
+            required=True,
+            object_schema=object_json_schema
+        ))
+        return schema
+
+    async def _execute(self, context: 'AgentContext', plan: Dict[str, Any]) -> str:
+        """
+        Executes the tool by validating the plan object, using a converter to create a TaskPlan,
+        and loading it onto the task board.
+        """
+        logger.info(f"Agent '{context.agent_id}' is executing PublishTaskPlan.")
+        
+        team_context: Optional['AgentTeamContext'] = context.custom_data.get("team_context")
+        if not team_context:
+            error_msg = "Error: Team context is not available. Cannot access the task board."
+            logger.error(f"Agent '{context.agent_id}': {error_msg}")
+            return error_msg
+            
+        task_board = getattr(team_context.state, 'task_board', None)
+        if not task_board:
+            error_msg = "Error: Task board has not been initialized for this team."
+            logger.error(f"Agent '{context.agent_id}': {error_msg}")
+            return error_msg
+            
+        try:
+            # Step 1: The input is now a dictionary, so we can directly validate it.
+            plan_definition_schema = TaskPlanDefinitionSchema(**plan)
+
+            # Step 2: Use the dedicated converter to create the internal TaskPlan object.
+            final_plan = TaskPlanConverter.from_schema(plan_definition_schema)
+
+        except (ValidationError, ValueError) as e:
+            error_msg = f"Invalid or inconsistent task plan provided: {e}"
+            logger.warning(f"Agent '{context.agent_id}' provided an invalid plan for PublishTaskPlan: {error_msg}")
+            return f"Error: {error_msg}"
+        except Exception as e:
+            error_msg = f"An unexpected error occurred during plan parsing or conversion: {e}"
+            logger.error(f"Agent '{context.agent_id}': {error_msg}", exc_info=True)
+            return f"Error: {error_msg}"
+
+        if task_board.load_task_plan(final_plan):
+            logger.info(f"Agent '{context.agent_id}': Task plan published successfully. Returning new board status.")
+            # Convert the new state of the board back to an LLM-friendly schema and return it.
+            status_report_schema = TaskBoardConverter.to_schema(task_board)
+            if status_report_schema:
+                return status_report_schema.model_dump_json(indent=2)
+            else:
+                # This is a fallback case, shouldn't happen right after a successful load.
+                return "Task plan published successfully, but could not generate status report."
+        else:
+            error_msg = "Failed to load task plan onto the board. This can happen if the board implementation rejects the plan."
+            logger.error(f"Agent '{context.agent_id}': {error_msg}")
+            return f"Error: {error_msg}"