autobyteus 1.1.9__py3-none-any.whl → 1.2.0__py3-none-any.whl

autobyteus/task_management/schemas/task_definition.py

@@ -13,7 +13,7 @@ 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.")
+    description: str = Field(..., description="A clear, detailed, and unambiguous description of what this task entails. Provide all necessary context for the assignee to complete the work. For example, if the task involves a file, specify its full, absolute path. If it requires creating a file, specify where it should be saved. Mention any specific requirements or expected outputs.")
     dependencies: List[str] = Field(
         default_factory=list,
         description="A list of 'task_name' values for tasks that must be completed first."

autobyteus/task_management/schemas/task_status_report.py

@@ -16,7 +16,7 @@ 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.")
+    description: str = Field(..., description="A clear, detailed, and unambiguous description of what this task entails. Provide all necessary context for the assignee to complete the work. For example, if the task involves a file, specify its full, absolute path. If it requires creating a file, specify where it should be saved. Mention any specific requirements or expected outputs.")
     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.")

autobyteus/task_management/tools/__init__.py

@@ -7,10 +7,12 @@ from .get_task_board_status import GetTaskBoardStatus
 from .publish_tasks import PublishTasks
 from .publish_task import PublishTask
 from .update_task_status import UpdateTaskStatus
+from .assign_task_to import AssignTaskTo
 
 __all__ = [
     "GetTaskBoardStatus",
     "PublishTasks",
     "PublishTask",
     "UpdateTaskStatus",
+    "AssignTaskTo",
 ]

autobyteus/task_management/tools/assign_task_to.py

@@ -0,0 +1,125 @@
+# file: autobyteus/autobyteus/task_management/tools/assign_task_to.py
+import logging
+from typing import TYPE_CHECKING, Optional, Any
+
+from pydantic import ValidationError
+
+from autobyteus.tools.base_tool import BaseTool
+from autobyteus.tools.tool_category import ToolCategory
+from autobyteus.utils.parameter_schema import ParameterSchema
+from autobyteus.tools.pydantic_schema_converter import pydantic_to_parameter_schema
+from autobyteus.task_management.schemas import TaskDefinitionSchema
+from autobyteus.task_management.task import Task
+
+if TYPE_CHECKING:
+    from autobyteus.agent.context import AgentContext
+    from autobyteus.agent_team.context import AgentTeamContext
+    from autobyteus.agent_team.context.team_manager import TeamManager
+
+logger = logging.getLogger(__name__)
+
+class AssignTaskTo(BaseTool):
+    """A tool for one agent to directly create and assign a single task to another agent."""
+
+    CATEGORY = ToolCategory.TASK_MANAGEMENT
+
+    @classmethod
+    def get_name(cls) -> str:
+        return "AssignTaskTo"
+
+    @classmethod
+    def get_description(cls) -> str:
+        return (
+            "Creates and assigns a single new task to a specific team member, and sends them a direct notification "
+            "with the task details. Use this to delegate a well-defined piece of work you have identified."
+        )
+
+    @classmethod
+    def get_argument_schema(cls) -> Optional[ParameterSchema]:
+        # The schema is the same as for defining a single task.
+        return pydantic_to_parameter_schema(TaskDefinitionSchema)
+
+    async def _execute(self, context: 'AgentContext', **kwargs: Any) -> str:
+        """
+        Executes the tool by adding the task to the central TaskBoard and then
+        sending a direct message to the assignee with the task's details.
+        """
+        agent_name = context.config.name
+        task_name = kwargs.get("task_name", "unnamed task")
+        assignee_name = kwargs.get("assignee_name")
+        logger.info(f"Agent '{agent_name}' is executing AssignTaskTo for task '{task_name}' assigned to '{assignee_name}'.")
+
+        # --- Get Team Context and Task Board ---
+        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 or send messages."
+            logger.error(f"Agent '{agent_name}': {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 '{agent_name}': {error_msg}")
+            return error_msg
+        
+        # --- Action 1: Add the task to the Task Board ---
+        try:
+            task_def_schema = TaskDefinitionSchema(**kwargs)
+            new_task = Task(**task_def_schema.model_dump())
+        except (ValidationError, ValueError) as e:
+            error_msg = f"Invalid task definition provided: {e}"
+            logger.warning(f"Agent '{agent_name}' provided an invalid definition for AssignTaskTo: {error_msg}")
+            return f"Error: {error_msg}"
+
+        if not task_board.add_task(new_task):
+            error_msg = f"Failed to publish task '{new_task.task_name}' to the board for an unknown reason."
+            logger.error(f"Agent '{agent_name}': {error_msg}")
+            return f"Error: {error_msg}"
+        
+        logger.info(f"Agent '{agent_name}' successfully published task '{new_task.task_name}' to the task board.")
+
+        # --- Action 2: Send a direct notification message to the assignee ---
+        team_manager: Optional['TeamManager'] = team_context.team_manager
+        if not team_manager:
+            # This is a degraded state, but the primary action (publishing) succeeded.
+            warning_msg = (f"Successfully published task '{new_task.task_name}', but could not send a direct notification "
+                           "because the TeamManager is not available.")
+            logger.warning(f"Agent '{agent_name}': {warning_msg}")
+            return warning_msg
+
+        try:
+            # Local import to break potential circular dependency at module load time.
+            from autobyteus.agent_team.events.agent_team_events import InterAgentMessageRequestEvent
+
+            notification_content = (
+                f"You have been assigned a new task directly from agent '{agent_name}'.\n\n"
+                f"**Task Name**: '{new_task.task_name}'\n"
+                f"**Description**: {new_task.description}\n"
+            )
+            if new_task.dependencies:
+                # Resolve dependency names for the message
+                id_to_name_map = {task.task_id: task.task_name for task in task_board.tasks}
+                dep_names = [id_to_name_map.get(dep_id, str(dep_id)) for dep_id in new_task.dependencies]
+                notification_content += f"**Dependencies**: {', '.join(dep_names)}\n"
+            
+            notification_content += "\nThis task has been logged on the team's task board. You can begin work when its dependencies are met."
+
+            event = InterAgentMessageRequestEvent(
+                sender_agent_id=context.agent_id,
+                recipient_name=new_task.assignee_name,
+                content=notification_content,
+                message_type="task_assignment"
+            )
+            
+            await team_manager.dispatch_inter_agent_message_request(event)
+            logger.info(f"Agent '{agent_name}' successfully dispatched a notification message for task '{new_task.task_name}' to '{new_task.assignee_name}'.")
+        
+        except Exception as e:
+            # Again, this is a degraded state. The main goal was achieved.
+            warning_msg = (f"Successfully published task '{new_task.task_name}', but failed to send the direct notification message. "
+                           f"Error: {e}")
+            logger.error(f"Agent '{agent_name}': {warning_msg}", exc_info=True)
+            return warning_msg
+            
+        success_msg = f"Successfully assigned task '{new_task.task_name}' to agent '{new_task.assignee_name}' and sent a notification."
+        return success_msg

autobyteus/tools/__init__.py

@@ -5,6 +5,8 @@ for creating tools within the AutoByteUs framework.
 It also contains implementations of various standard tools.
 """
 
+import logging
+
 # Core components for defining tools
 from .base_tool import BaseTool
 from .functional_tool import tool # The @tool decorator
@@ -13,33 +15,67 @@ from .tool_config import ToolConfig # Configuration data object, primarily for c
 from .tool_origin import ToolOrigin
 from .tool_category import ToolCategory
 
+logger = logging.getLogger(__name__)
+
 # --- Re-export specific tools for easier access ---
 
 # Functional tools (decorated functions are now instances)
-from .pdf_downloader import pdf_downloader
 from .bash.bash_executor import bash_executor
 from .file.file_reader import file_reader
 from .file.file_writer import file_writer
+from .file.file_editor import file_edit
 
 # General Class-based tools
-from .google_search import GoogleSearch 
-from .image_downloader import ImageDownloader
+try:
+    from .google_search import GoogleSearch
+except ModuleNotFoundError as import_err:
+    logger.warning("GoogleSearch tool not available: %s", import_err)
+    GoogleSearch = None
 from .timer import Timer
-from .multimedia.image_tools import GenerateImageTool, EditImageTool
-from .multimedia.media_reader_tool import ReadMediaFile
+try:
+    from .multimedia.image_tools import GenerateImageTool, EditImageTool
+except ModuleNotFoundError as import_err:
+    logger.warning("Image tools not available: %s", import_err)
+    GenerateImageTool = None
+    EditImageTool = None
+try:
+    from .multimedia.media_reader_tool import ReadMediaFile
+except ModuleNotFoundError as import_err:
+    logger.warning("Media reader tool not available: %s", import_err)
+    ReadMediaFile = None
+try:
+    from .download_media_tool import DownloadMediaTool
+except ModuleNotFoundError as import_err:
+    logger.warning("Download media tool not available: %s", import_err)
+    DownloadMediaTool = None
 
 # Standalone Browser tools
-from .browser.standalone.navigate_to import NavigateTo as StandaloneNavigateTo # Alias to avoid name clash
-from .browser.standalone.webpage_reader import WebPageReader as StandaloneWebPageReader # Alias
-from .browser.standalone.webpage_screenshot_taker import WebPageScreenshotTaker as StandaloneWebPageScreenshotTaker # Alias
-from .browser.standalone.webpage_image_downloader import WebPageImageDownloader
-from .browser.standalone.web_page_pdf_generator import WebPagePDFGenerator
+try:
+    from .browser.standalone.navigate_to import NavigateTo as StandaloneNavigateTo # Alias to avoid name clash
+    from .browser.standalone.webpage_reader import WebPageReader as StandaloneWebPageReader # Alias
+    from .browser.standalone.webpage_screenshot_taker import WebPageScreenshotTaker as StandaloneWebPageScreenshotTaker # Alias
+    from .browser.standalone.webpage_image_downloader import WebPageImageDownloader
+    from .browser.standalone.web_page_pdf_generator import WebPagePDFGenerator
+except ModuleNotFoundError as import_err:
+    logger.warning('Standalone browser tools not available: %s', import_err)
+    StandaloneNavigateTo = None
+    StandaloneWebPageReader = None
+    StandaloneWebPageScreenshotTaker = None
+    WebPageImageDownloader = None
+    WebPagePDFGenerator = None
 
 # Session-Aware Browser tools
-from .browser.session_aware.browser_session_aware_navigate_to import BrowserSessionAwareNavigateTo
-from .browser.session_aware.browser_session_aware_web_element_trigger import BrowserSessionAwareWebElementTrigger
-from .browser.session_aware.browser_session_aware_webpage_reader import BrowserSessionAwareWebPageReader
-from .browser.session_aware.browser_session_aware_webpage_screenshot_taker import BrowserSessionAwareWebPageScreenshotTaker
+try:
+    from .browser.session_aware.browser_session_aware_navigate_to import BrowserSessionAwareNavigateTo
+    from .browser.session_aware.browser_session_aware_web_element_trigger import BrowserSessionAwareWebElementTrigger
+    from .browser.session_aware.browser_session_aware_webpage_reader import BrowserSessionAwareWebPageReader
+    from .browser.session_aware.browser_session_aware_webpage_screenshot_taker import BrowserSessionAwareWebPageScreenshotTaker
+except ModuleNotFoundError as import_err:
+    logger.warning('Session-aware browser tools not available: %s', import_err)
+    BrowserSessionAwareNavigateTo = None
+    BrowserSessionAwareWebElementTrigger = None
+    BrowserSessionAwareWebPageReader = None
+    BrowserSessionAwareWebPageScreenshotTaker = None
 
 
 __all__ = [
@@ -54,18 +90,18 @@ __all__ = [
     "ToolCategory",
 
     # Re-exported functional tool instances
-    "pdf_downloader",
     "bash_executor",
     "file_reader",
     "file_writer",
+    "file_edit",
 
     # Re-exported general class-based tools
     "GoogleSearch",
-    "ImageDownloader",
     "Timer",
     "GenerateImageTool",
     "EditImageTool",
     "ReadMediaFile",
+    "DownloadMediaTool",
 
     # Re-exported Standalone Browser tools
     "StandaloneNavigateTo",

autobyteus/tools/download_media_tool.py

@@ -0,0 +1,136 @@
+import os
+import logging
+import mimetypes
+import aiohttp
+from typing import Optional, TYPE_CHECKING
+from urllib.parse import urlparse
+
+from autobyteus.tools.base_tool import BaseTool
+from autobyteus.tools.tool_category import ToolCategory
+from autobyteus.utils.file_utils import get_default_download_folder
+from autobyteus.utils.parameter_schema import ParameterSchema, ParameterDefinition, ParameterType
+
+if TYPE_CHECKING:
+    from autobyteus.agent.context import AgentContext
+
+logger = logging.getLogger(__name__)
+
+class DownloadMediaTool(BaseTool):
+    """
+    A unified tool to download any media file (e.g., image, PDF, audio) from a URL.
+    """
+    CATEGORY = ToolCategory.WEB
+
+    @classmethod
+    def get_name(cls) -> str:
+        return "DownloadMedia"
+
+    @classmethod
+    def get_description(cls) -> str:
+        return (
+            "Downloads various media files (e.g., images like PNG/JPG, documents like PDF, audio like MP3/WAV) "
+            "from a direct URL and saves them locally. It intelligently determines the correct file extension "
+            "based on the content type. Returns the absolute path to the downloaded file."
+        )
+
+    @classmethod
+    def get_argument_schema(cls) -> ParameterSchema:
+        schema = ParameterSchema()
+        schema.add_parameter(ParameterDefinition(
+            name="url",
+            param_type=ParameterType.STRING,
+            description="The direct URL of the media file to download.",
+            required=True
+        ))
+        schema.add_parameter(ParameterDefinition(
+            name="filename",
+            param_type=ParameterType.STRING,
+            description="The desired base name for the downloaded file (e.g., 'vacation_photo', 'annual_report'). The tool will automatically add the correct file extension.",
+            required=True
+        ))
+        schema.add_parameter(ParameterDefinition(
+            name="folder",
+            param_type=ParameterType.STRING,
+            description="Optional. A custom directory path to save the file. If not provided, the system's default download folder will be used.",
+            required=False
+        ))
+        return schema
+
+    async def _execute(self, context: 'AgentContext', url: str, filename: str, folder: Optional[str] = None) -> str:
+        # 1. Determine download directory
+        try:
+            if folder:
+                # Security: prevent path traversal attacks.
+                if ".." in folder:
+                     raise ValueError("Security error: 'folder' path cannot contain '..'.")
+                destination_dir = os.path.abspath(folder)
+            else:
+                destination_dir = get_default_download_folder()
+            
+            os.makedirs(destination_dir, exist_ok=True)
+        except Exception as e:
+            logger.error(f"Error preparing download directory '{folder or 'default'}': {e}", exc_info=True)
+            raise IOError(f"Failed to create or access download directory: {e}")
+
+        # 2. Sanitize filename provided by the LLM
+        if not filename or ".." in filename or os.path.isabs(filename) or "/" in filename or "\\" in filename:
+            raise ValueError("Invalid filename. It must be a simple name without any path characters ('..', '/', '\\').")
+
+        logger.info(f"Attempting to download from {url} to save as '{filename}' in '{destination_dir}'.")
+
+        # 3. Download and process file asynchronously
+        try:
+            async with aiohttp.ClientSession() as session:
+                async with session.get(url, timeout=60) as response:
+                    response.raise_for_status()
+
+                    # 4. Intelligently determine file extension from Content-Type header
+                    content_type = response.headers.get('Content-Type')
+                    correct_ext = ''
+                    if content_type:
+                        mime_type = content_type.split(';')[0].strip()
+                        guess = mimetypes.guess_extension(mime_type)
+                        if guess:
+                            correct_ext = guess
+                            logger.debug(f"Determined extension '{correct_ext}' from Content-Type: '{mime_type}'")
+
+                    # Fallback to URL extension if Content-Type is generic or missing
+                    if not correct_ext or correct_ext == '.bin':
+                        url_path = urlparse(url).path
+                        _, ext_from_url = os.path.splitext(os.path.basename(url_path))
+                        if ext_from_url and len(ext_from_url) > 1: # Ensure it's not just a dot
+                            logger.debug(f"Using fallback extension '{ext_from_url}' from URL.")
+                            correct_ext = ext_from_url
+                    
+                    if not correct_ext:
+                        logger.warning("Could not determine a file extension. The file will be saved without one.")
+                    
+                    # 5. Construct final filename and path
+                    base_filename, _ = os.path.splitext(filename)
+                    final_filename = f"{base_filename}{correct_ext}"
+                    save_path = os.path.join(destination_dir, final_filename)
+                    
+                    # Ensure filename is unique to avoid overwriting
+                    counter = 1
+                    while os.path.exists(save_path):
+                        final_filename = f"{base_filename}_{counter}{correct_ext}"
+                        save_path = os.path.join(destination_dir, final_filename)
+                        counter += 1
+                    
+                    # 6. Stream file content to disk
+                    with open(save_path, 'wb') as f:
+                        async for chunk in response.content.iter_chunked(8192):
+                            f.write(chunk)
+
+                    logger.info(f"Successfully downloaded and saved file to: {save_path}")
+                    return f"Successfully downloaded file to: {save_path}"
+
+        except aiohttp.ClientError as e:
+            logger.error(f"Network error while downloading from {url}: {e}", exc_info=True)
+            raise ConnectionError(f"Failed to download from {url}: {e}")
+        except IOError as e:
+            logger.error(f"Failed to write downloaded file to {destination_dir}: {e}", exc_info=True)
+            raise
+        except Exception as e:
+            logger.error(f"An unexpected error occurred during download from {url}: {e}", exc_info=True)
+            raise RuntimeError(f"An unexpected error occurred: {e}")

autobyteus/tools/file/file_editor.py

@@ -0,0 +1,200 @@
+import os
+import re
+import logging
+from typing import TYPE_CHECKING, List
+
+from autobyteus.tools.functional_tool import tool
+from autobyteus.tools.tool_category import ToolCategory
+
+if TYPE_CHECKING:
+    from autobyteus.agent.context import AgentContext
+
+logger = logging.getLogger(__name__)
+
+_HUNK_HEADER_RE = re.compile(r"^@@ -(?P<old_start>\d+)(?:,(?P<old_count>\d+))? \+(?P<new_start>\d+)(?:,(?P<new_count>\d+))? @@")
+
+class PatchApplicationError(ValueError):
+    """Raised when a unified diff patch cannot be applied to the target file."""
+
+
+def _resolve_file_path(context: 'AgentContext', path: str) -> str:
+    """Resolves an absolute path for the given input, using the agent workspace when needed."""
+    if os.path.isabs(path):
+        final_path = path
+        logger.debug("FileEdit: provided path '%s' is absolute.", path)
+    else:
+        if not context.workspace:
+            error_msg = ("Relative path '%s' provided, but no workspace is configured for agent '%s'. "
+                         "A workspace is required to resolve relative paths.")
+            logger.error(error_msg, path, context.agent_id)
+            raise ValueError(error_msg % (path, context.agent_id))
+        base_path = context.workspace.get_base_path()
+        if not base_path or not isinstance(base_path, str):
+            error_msg = ("Agent '%s' has a configured workspace, but it provided an invalid base path ('%s'). "
+                         "Cannot resolve relative path '%s'.")
+            logger.error(error_msg, context.agent_id, base_path, path)
+            raise ValueError(error_msg % (context.agent_id, base_path, path))
+        final_path = os.path.join(base_path, path)
+        logger.debug("FileEdit: resolved relative path '%s' against workspace base '%s' to '%s'.", path, base_path, final_path)
+
+    normalized_path = os.path.normpath(final_path)
+    logger.debug("FileEdit: normalized path to '%s'.", normalized_path)
+    return normalized_path
+
+
+def _apply_unified_diff(original_lines: List[str], patch: str) -> List[str]:
+    """Applies a unified diff patch to the provided original lines and returns the patched lines."""
+    if not patch or not patch.strip():
+        raise PatchApplicationError("Patch content is empty; nothing to apply.")
+
+    patched_lines: List[str] = []
+    orig_idx = 0
+    patch_lines = patch.splitlines(keepends=True)
+    line_idx = 0
+
+    while line_idx < len(patch_lines):
+        line = patch_lines[line_idx]
+
+        if line.startswith('---') or line.startswith('+++'):
+            logger.debug("FileEdit: skipping diff header line '%s'.", line.strip())
+            line_idx += 1
+            continue
+
+        if not line.startswith('@@'):
+            stripped = line.strip()
+            if stripped == '':
+                line_idx += 1
+                continue
+            raise PatchApplicationError(f"Unexpected content outside of hunk header: '{stripped}'.")
+
+        match = _HUNK_HEADER_RE.match(line)
+        if not match:
+            raise PatchApplicationError(f"Malformed hunk header: '{line.strip()}'.")
+
+        old_start = int(match.group('old_start'))
+        old_count = int(match.group('old_count') or '1')
+        new_start = int(match.group('new_start'))
+        new_count = int(match.group('new_count') or '1')
+        logger.debug("FileEdit: processing hunk old_start=%s old_count=%s new_start=%s new_count=%s.",
+                     old_start, old_count, new_start, new_count)
+
+        target_idx = old_start - 1 if old_start > 0 else 0
+        if target_idx > len(original_lines):
+            raise PatchApplicationError("Patch hunk starts beyond end of file.")
+        if target_idx < orig_idx:
+            raise PatchApplicationError("Patch hunks overlap or are out of order.")
+
+        patched_lines.extend(original_lines[orig_idx:target_idx])
+        orig_idx = target_idx
+
+        line_idx += 1
+        hunk_consumed = 0
+        removed = 0
+        added = 0
+
+        while line_idx < len(patch_lines):
+            hunk_line = patch_lines[line_idx]
+            if hunk_line.startswith('@@'):
+                break
+
+            if hunk_line.startswith('-'):
+                if orig_idx >= len(original_lines):
+                    raise PatchApplicationError("Patch attempts to remove lines beyond file length.")
+                if original_lines[orig_idx] != hunk_line[1:]:
+                    raise PatchApplicationError("Patch removal does not match file content.")
+                orig_idx += 1
+                hunk_consumed += 1
+                removed += 1
+            elif hunk_line.startswith('+'):
+                patched_lines.append(hunk_line[1:])
+                added += 1
+            elif hunk_line.startswith(' '):
+                if orig_idx >= len(original_lines):
+                    raise PatchApplicationError("Patch context exceeds file length.")
+                if original_lines[orig_idx] != hunk_line[1:]:
+                    raise PatchApplicationError("Patch context does not match file content.")
+                patched_lines.append(original_lines[orig_idx])
+                orig_idx += 1
+                hunk_consumed += 1
+            elif hunk_line.startswith('\\'):
+                if hunk_line.strip() == '\':
+                    if patched_lines:
+                        patched_lines[-1] = patched_lines[-1].rstrip('\n')
+                else:
+                    raise PatchApplicationError(f"Unsupported patch directive: '{hunk_line.strip()}'.")
+            elif hunk_line.strip() == '':
+                patched_lines.append(hunk_line)
+            else:
+                raise PatchApplicationError(f"Unsupported patch line: '{hunk_line.strip()}'.")
+
+            line_idx += 1
+
+        consumed_total = hunk_consumed
+        if old_count == 0:
+            if consumed_total != 0:
+                raise PatchApplicationError("Patch expects zero original lines but consumed some context.")
+        else:
+            if consumed_total != old_count:
+                raise PatchApplicationError(
+                    f"Patch expected to consume {old_count} original lines but consumed {consumed_total}.")
+
+        context_lines = consumed_total - removed
+        expected_new_lines = context_lines + added
+        if new_count == 0:
+            if expected_new_lines != 0:
+                raise PatchApplicationError("Patch declares zero new lines but produced changes.")
+        else:
+            if expected_new_lines != new_count:
+                raise PatchApplicationError(
+                    f"Patch expected to produce {new_count} new lines but produced {expected_new_lines}.")
+
+    patched_lines.extend(original_lines[orig_idx:])
+    return patched_lines
+
+
+@tool(name="FileEdit", category=ToolCategory.FILE_SYSTEM)
+async def file_edit(context: 'AgentContext', path: str, patch: str, create_if_missing: bool = False) -> str:
+    """Applies a unified diff patch to update a text file without overwriting unrelated content.
+
+    Args:
+        path: Path to the target file. Relative paths are resolved against the agent workspace when available.
+        patch: Unified diff patch describing the edits to apply.
+        create_if_missing: When True, allows applying a patch that introduces content to a non-existent file.
+
+    Raises:
+        FileNotFoundError: If the file does not exist and create_if_missing is False.
+        PatchApplicationError: If the patch content cannot be applied cleanly.
+        IOError: If file reading or writing fails.
+    """
+    logger.debug("FileEdit: requested edit for agent '%s' on path '%s'.", context.agent_id, path)
+    final_path = _resolve_file_path(context, path)
+
+    dir_path = os.path.dirname(final_path)
+    if dir_path and not os.path.exists(dir_path) and create_if_missing:
+        os.makedirs(dir_path, exist_ok=True)
+
+    file_exists = os.path.exists(final_path)
+    if not file_exists and not create_if_missing:
+        raise FileNotFoundError(f"The file at resolved path {final_path} does not exist.")
+
+    try:
+        original_lines: List[str]
+        if file_exists:
+            with open(final_path, 'r', encoding='utf-8') as source:
+                original_lines = source.read().splitlines(keepends=True)
+        else:
+            original_lines = []
+
+        patched_lines = _apply_unified_diff(original_lines, patch)
+
+        with open(final_path, 'w', encoding='utf-8') as destination:
+            destination.writelines(patched_lines)
+
+        logger.info("FileEdit: successfully applied patch to '%s'.", final_path)
+        return f"File edited successfully at {final_path}"
+    except PatchApplicationError as patch_err:
+        logger.error("FileEdit: failed to apply patch to '%s': %s", final_path, patch_err, exc_info=True)
+        raise patch_err
+    except Exception as exc:  # pragma: no cover - general safeguard
+        logger.error("FileEdit: unexpected error while editing '%s': %s", final_path, exc, exc_info=True)
+        raise IOError(f"Could not edit file at '{final_path}': {exc}")

autobyteus/tools/usage/parsers/_string_decoders.py

@@ -0,0 +1,18 @@
+# file: autobyteus/autobyteus/tools/usage/parsers/_string_decoders.py
+"""Utility helpers for normalizing string content inside parsed tool payloads."""
+
+from __future__ import annotations
+
+import html
+from typing import Any
+
+
+def decode_html_entities(data: Any) -> Any:
+    """Recursively decode HTML/XML entities in strings within a data structure."""
+    if isinstance(data, dict):
+        return {key: decode_html_entities(value) for key, value in data.items()}
+    if isinstance(data, list):
+        return [decode_html_entities(item) for item in data]
+    if isinstance(data, str):
+        return html.unescape(data)
+    return data

autobyteus/tools/usage/parsers/default_json_tool_usage_parser.py

@@ -3,6 +3,8 @@ import json
 import logging
 from typing import Dict, Any, TYPE_CHECKING, List
 
+from ._string_decoders import decode_html_entities
+
 from autobyteus.agent.tool_invocation import ToolInvocation
 from .base_parser import BaseToolUsageParser
 from .exceptions import ToolUsageParseException
@@ -53,9 +55,15 @@ class DefaultJsonToolUsageParser(BaseToolUsageParser):
                         logger.debug(f"Skipping tool block with invalid 'parameters' type ({type(arguments)}): {tool_block}")
                         continue
                     
+                    decoded_arguments = decode_html_entities(arguments)
+                    decoded_tool_name = decode_html_entities(tool_name)
                     try:
                         # Pass id=None to trigger deterministic ID generation.
-                        tool_invocation = ToolInvocation(name=tool_name, arguments=arguments, id=None)
+                        tool_invocation = ToolInvocation(
+                            name=decoded_tool_name,
+                            arguments=decoded_arguments,
+                            id=None,
+                        )
                         invocations.append(tool_invocation)
                         logger.info(f"Successfully parsed default JSON tool invocation for '{tool_name}'.")
                     except Exception as e: