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

autobyteus/tools/browser/session_aware/browser_session_aware_webpage_screenshot_taker.py

@@ -32,11 +32,11 @@ class BrowserSessionAwareWebPageScreenshotTaker(BrowserSessionAwareTool):
             if self.image_format not in ["png", "jpeg"]:
                 logger.warning(f"Invalid image_format '{self.image_format}' in config. Defaulting to 'png'.")
                 self.image_format = "png"
-        logger.debug(f"BrowserSessionAwareWebPageScreenshotTaker initialized. Full page: {self.full_page}, Format: {self.image_format}")
+        logger.debug(f"take_webpage_screenshot (session-aware) initialized. Full page: {self.full_page}, Format: {self.image_format}")
 
     @classmethod
     def get_name(cls) -> str: 
-        return "WebPageScreenshotTaker" 
+        return "take_webpage_screenshot" 
 
     @classmethod
     def get_description(cls) -> str:
@@ -87,7 +87,7 @@ class BrowserSessionAwareWebPageScreenshotTaker(BrowserSessionAwareTool):
         file_name: str, 
         webpage_url: str 
     ) -> str: 
-        logger.info(f"BrowserSessionAwareWebPageScreenshotTaker performing action. Saving to '{file_name}'. Current page: {shared_session.page.url}")
+        logger.info(f"take_webpage_screenshot (session-aware) performing action. Saving to '{file_name}'. Current page: {shared_session.page.url}")
 
         output_dir = os.path.dirname(file_name)
         if output_dir: 

autobyteus/tools/browser/standalone/navigate_to.py

@@ -23,7 +23,11 @@ class NavigateTo(BaseTool, UIIntegrator):
     def __init__(self, config: Optional[ToolConfig] = None):
         BaseTool.__init__(self, config=config)
         UIIntegrator.__init__(self)
-        logger.debug("NavigateTo (standalone) tool initialized.")
+        logger.debug("navigate_to (standalone) tool initialized.")
+
+    @classmethod
+    def get_name(cls) -> str:
+        return "navigate_to"
 
     @classmethod
     def get_description(cls) -> str:
@@ -41,33 +45,33 @@ class NavigateTo(BaseTool, UIIntegrator):
         return schema
 
     async def _execute(self, context: 'AgentContext', url: str) -> str:
-        logger.info(f"NavigateTo (standalone) for agent {context.agent_id} navigating to: {url}")
+        logger.info(f"navigate_to (standalone) for agent {context.agent_id} navigating to: {url}")
 
         if not self._is_valid_url(url):
             error_msg = f"Invalid URL format: {url}. Must include scheme (e.g., http, https) and netloc."
-            logger.warning(f"NavigateTo (standalone) validation error for agent {context.agent_id}: {error_msg}")
+            logger.warning(f"navigate_to (standalone) validation error for agent {context.agent_id}: {error_msg}")
             raise ValueError(error_msg)
 
         try:
             await self.initialize()
             if not self.page:
-                 logger.error("Playwright page not initialized in NavigateTo (standalone).")
-                 raise RuntimeError("Playwright page not available for NavigateTo.")
+                 logger.error("Playwright page not initialized in navigate_to (standalone).")
+                 raise RuntimeError("Playwright page not available for navigate_to.")
 
             response = await self.page.goto(url, wait_until="domcontentloaded", timeout=60000) 
             
             if response and response.ok:
                 success_msg = f"Successfully navigated to {url}"
-                logger.info(f"NavigateTo (standalone) for agent {context.agent_id}: {success_msg}")
+                logger.info(f"navigate_to (standalone) for agent {context.agent_id}: {success_msg}")
                 return success_msg
             else:
                 status = response.status if response else "Unknown"
                 failure_msg = f"Navigation to {url} failed with status {status}"
-                logger.warning(f"NavigateTo (standalone) for agent {context.agent_id}: {failure_msg}")
+                logger.warning(f"navigate_to (standalone) for agent {context.agent_id}: {failure_msg}")
                 return failure_msg
         except Exception as e:
-            logger.error(f"Error during NavigateTo (standalone) for URL '{url}', agent {context.agent_id}: {e}", exc_info=True)
-            raise RuntimeError(f"NavigateTo (standalone) failed for URL '{url}': {str(e)}")
+            logger.error(f"Error during navigate_to (standalone) for URL '{url}', agent {context.agent_id}: {e}", exc_info=True)
+            raise RuntimeError(f"navigate_to (standalone) failed for URL '{url}': {str(e)}")
         finally:
             await self.close()
 

autobyteus/tools/browser/standalone/web_page_pdf_generator.py

@@ -24,7 +24,11 @@ class WebPagePDFGenerator(BaseTool, UIIntegrator):
     def __init__(self, config: Optional[ToolConfig] = None): 
         BaseTool.__init__(self, config=config)
         UIIntegrator.__init__(self)
-        logger.debug("WebPagePDFGenerator (standalone) tool initialized.")
+        logger.debug("generate_webpage_pdf (standalone) tool initialized.")
+
+    @classmethod
+    def get_name(cls) -> str:
+        return "generate_webpage_pdf"
 
     @classmethod
     def get_description(cls) -> str:
@@ -49,7 +53,7 @@ class WebPagePDFGenerator(BaseTool, UIIntegrator):
         return schema
 
     async def _execute(self, context: 'AgentContext', url: str, save_dir: str) -> str: 
-        logger.info(f"WebPagePDFGenerator for agent {context.agent_id} generating PDF for '{url}', saving to directory '{save_dir}'.")
+        logger.info(f"generate_webpage_pdf for agent {context.agent_id} generating PDF for '{url}', saving to directory '{save_dir}'.")
 
         if not self._is_valid_page_url(url):
             raise ValueError(f"Invalid page URL format: {url}. Must be a full URL (e.g., http/https).")
@@ -73,8 +77,8 @@ class WebPagePDFGenerator(BaseTool, UIIntegrator):
         try:
             await self.initialize()
             if not self.page:
-                 logger.error("Playwright page not initialized in WebPagePDFGenerator.")
-                 raise RuntimeError("Playwright page not available for WebPagePDFGenerator.")
+                 logger.error("Playwright page not initialized in generate_webpage_pdf.")
+                 raise RuntimeError("Playwright page not available for generate_webpage_pdf.")
 
             await self.page.goto(url, wait_until="networkidle", timeout=60000)
             
@@ -85,7 +89,7 @@ class WebPagePDFGenerator(BaseTool, UIIntegrator):
             return absolute_file_path
         except Exception as e:
             logger.error(f"Error generating PDF for URL '{url}': {e}", exc_info=True)
-            raise RuntimeError(f"WebPagePDFGenerator failed for URL '{url}': {str(e)}")
+            raise RuntimeError(f"generate_webpage_pdf failed for URL '{url}': {str(e)}")
         finally:
             await self.close() 
 

autobyteus/tools/browser/standalone/webpage_image_downloader.py

@@ -24,7 +24,11 @@ class WebPageImageDownloader(BaseTool, UIIntegrator):
     def __init__(self, config: Optional[ToolConfig] = None): 
         BaseTool.__init__(self, config=config)
         UIIntegrator.__init__(self)
-        logger.debug("WebPageImageDownloader tool initialized.")
+        logger.debug("download_webpage_images tool initialized.")
+
+    @classmethod
+    def get_name(cls) -> str:
+        return "download_webpage_images"
 
     @classmethod
     def get_description(cls) -> str:
@@ -49,7 +53,7 @@ class WebPageImageDownloader(BaseTool, UIIntegrator):
         return schema
 
     async def _execute(self, context: 'AgentContext', url: str, save_dir: str) -> List[str]: 
-        logger.info(f"WebPageImageDownloader for agent {context.agent_id} downloading images from '{url}' to '{save_dir}'.")
+        logger.info(f"download_webpage_images for agent {context.agent_id} downloading images from '{url}' to '{save_dir}'.")
         
         if not self._is_valid_page_url(url):
             raise ValueError(f"Invalid page URL format: {url}. Must be a full URL (e.g., http/https).")
@@ -60,8 +64,8 @@ class WebPageImageDownloader(BaseTool, UIIntegrator):
         try:
             await self.initialize()
             if not self.page:
-                 logger.error("Playwright page not initialized in WebPageImageDownloader.")
-                 raise RuntimeError("Playwright page not available for WebPageImageDownloader.")
+                 logger.error("Playwright page not initialized in download_webpage_images.")
+                 raise RuntimeError("Playwright page not available for download_webpage_images.")
 
             await self.page.goto(url, wait_until="networkidle", timeout=60000)
             
@@ -104,8 +108,8 @@ class WebPageImageDownloader(BaseTool, UIIntegrator):
             return saved_paths
 
         except Exception as e:
-            logger.error(f"Error in WebPageImageDownloader for URL '{url}': {e}", exc_info=True)
-            raise RuntimeError(f"WebPageImageDownloader failed for URL '{url}': {str(e)}")
+            logger.error(f"Error in download_webpage_images for URL '{url}': {e}", exc_info=True)
+            raise RuntimeError(f"download_webpage_images failed for URL '{url}': {str(e)}")
         finally:
             await self.close()
 

autobyteus/tools/browser/standalone/webpage_reader.py

@@ -1,6 +1,6 @@
 """
 File: autobyteus/tools/browser/standalone/webpage_reader.py
-This module provides a WebPageReader tool for reading and cleaning HTML content from webpages.
+This module provides a read_webpage tool for reading and cleaning HTML content from webpages.
 """
 
 import logging
@@ -35,15 +35,19 @@ class WebPageReader(BaseTool, UIIntegrator):
                     try:
                         cleaning_mode_to_use = CleaningMode(cleaning_mode_value.upper())
                     except ValueError:
-                        logger.warning(f"Invalid cleaning_mode string '{cleaning_mode_value}' in config for WebPageReader. Using THOROUGH.")
+                        logger.warning(f"Invalid cleaning_mode string '{cleaning_mode_value}' in config for read_webpage. Using THOROUGH.")
                         cleaning_mode_to_use = CleaningMode.THOROUGH
                 elif isinstance(cleaning_mode_value, CleaningMode):
                     cleaning_mode_to_use = cleaning_mode_value
                 else:
-                     logger.warning(f"Invalid type for cleaning_mode in config for WebPageReader. Using THOROUGH.")
+                     logger.warning(f"Invalid type for cleaning_mode in config for read_webpage. Using THOROUGH.")
         
         self.cleaning_mode = cleaning_mode_to_use
-        logger.debug(f"WebPageReader initialized with cleaning_mode: {self.cleaning_mode}")
+        logger.debug(f"read_webpage initialized with cleaning_mode: {self.cleaning_mode}")
+
+    @classmethod
+    def get_name(cls) -> str:
+        return "read_webpage"
 
     @classmethod
     def get_description(cls) -> str:
@@ -63,7 +67,7 @@ class WebPageReader(BaseTool, UIIntegrator):
         
     @classmethod
     def get_config_schema(cls) -> Optional[ParameterSchema]:
-        """Schema for parameters to configure the WebPageReader instance itself."""
+        """Schema for parameters to configure the read_webpage instance itself."""
         schema = ParameterSchema()
         schema.add_parameter(ParameterDefinition(
             name="cleaning_mode",
@@ -76,13 +80,13 @@ class WebPageReader(BaseTool, UIIntegrator):
         return schema
 
     async def _execute(self, context: 'AgentContext', url: str) -> str:
-        logger.info(f"WebPageReader executing for agent {context.agent_id} with URL: '{url}'")
+        logger.info(f"read_webpage executing for agent {context.agent_id} with URL: '{url}'")
 
         try:
             await self.initialize()
             if not self.page:
-                 logger.error("Playwright page not initialized in WebPageReader.")
-                 raise RuntimeError("Playwright page not available for WebPageReader.")
+                 logger.error("Playwright page not initialized in read_webpage.")
+                 raise RuntimeError("Playwright page not available for read_webpage.")
 
             await self.page.goto(url, timeout=60000, wait_until="domcontentloaded")
             page_content = await self.page.content()
@@ -96,6 +100,6 @@ class WebPageReader(BaseTool, UIIntegrator):
 '''
         except Exception as e:
             logger.error(f"Error reading webpage at URL '{url}': {e}", exc_info=True)
-            raise RuntimeError(f"WebPageReader failed for URL '{url}': {str(e)}")
+            raise RuntimeError(f"read_webpage failed for URL '{url}': {str(e)}")
         finally:
             await self.close()

autobyteus/tools/browser/standalone/webpage_screenshot_taker.py

@@ -31,7 +31,11 @@ class WebPageScreenshotTaker(BaseTool, UIIntegrator):
             if self.image_format not in ["png", "jpeg"]:
                 logger.warning(f"Invalid image_format '{self.image_format}' in config. Defaulting to 'png'.")
                 self.image_format = "png"
-        logger.debug(f"WebPageScreenshotTaker initialized. Full page: {self.full_page}, Format: {self.image_format}")
+        logger.debug(f"take_webpage_screenshot initialized. Full page: {self.full_page}, Format: {self.image_format}")
+
+    @classmethod
+    def get_name(cls) -> str:
+        return "take_webpage_screenshot"
 
     @classmethod
     def get_description(cls) -> str:
@@ -75,7 +79,7 @@ class WebPageScreenshotTaker(BaseTool, UIIntegrator):
         return schema
 
     async def _execute(self, context: 'AgentContext', url: str, file_path: str) -> str: 
-        logger.info(f"WebPageScreenshotTaker for agent {context.agent_id} taking screenshot of '{url}', saving to '{file_path}'.")
+        logger.info(f"take_webpage_screenshot for agent {context.agent_id} taking screenshot of '{url}', saving to '{file_path}'.")
         
         output_dir = os.path.dirname(file_path)
         if output_dir: 
@@ -84,8 +88,8 @@ class WebPageScreenshotTaker(BaseTool, UIIntegrator):
         try:
             await self.initialize() 
             if not self.page:
-                 logger.error("Playwright page not initialized in WebPageScreenshotTaker.")
-                 raise RuntimeError("Playwright page not available for WebPageScreenshotTaker.")
+                 logger.error("Playwright page not initialized in take_webpage_screenshot.")
+                 raise RuntimeError("Playwright page not available for take_webpage_screenshot.")
 
             await self.page.goto(url, wait_until="networkidle", timeout=60000) 
             
@@ -96,6 +100,6 @@ class WebPageScreenshotTaker(BaseTool, UIIntegrator):
             return absolute_file_path
         except Exception as e:
             logger.error(f"Error taking screenshot of URL '{url}': {e}", exc_info=True)
-            raise RuntimeError(f"WebPageScreenshotTaker failed for URL '{url}': {str(e)}")
+            raise RuntimeError(f"take_webpage_screenshot failed for URL '{url}': {str(e)}")
         finally:
             await self.close()

autobyteus/tools/file/__init__.py

@@ -0,0 +1,13 @@
+from .edit_file import edit_file
+from .read_file import read_file
+from .write_file import write_file
+from .search_files import search_files
+from .list_directory import list_directory
+
+__all__ = [
+    "edit_file",
+    "read_file",
+    "write_file",
+    "search_files",
+    "list_directory",
+]

autobyteus/tools/file/edit_file.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("edit_file: 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("edit_file: resolved relative path '%s' against workspace base '%s' to '%s'.", path, base_path, final_path)
+
+    normalized_path = os.path.normpath(final_path)
+    logger.debug("edit_file: 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("edit_file: 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("edit_file: 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="edit_file", category=ToolCategory.FILE_SYSTEM)
+async def edit_file(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("edit_file: 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("edit_file: successfully applied patch to '%s'.", final_path)
+        return f"File edited successfully at {final_path}"
+    except PatchApplicationError as patch_err:
+        logger.error("edit_file: 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("edit_file: 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/file/list_directory.py

@@ -0,0 +1,168 @@
+# file: autobyteus/autobyteus/tools/file/list_directory.py
+"""
+This module provides a tool for listing directory contents in a structured,
+tree-like format, mirroring the behavior of the Codex Rust implementation.
+"""
+
+import asyncio
+import logging
+import os
+from pathlib import Path
+from collections import deque
+from dataclasses import dataclass
+from typing import List, Deque, Tuple, Optional, TYPE_CHECKING
+
+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__)
+
+# Constants from the design document
+INDENTATION_SPACES = 2
+MAX_ENTRY_LENGTH = 500
+
+@dataclass
+class DirEntry:
+    """Represents a collected directory entry for sorting and formatting."""
+    name: str
+    kind: str
+    depth: int
+
+@tool(name="list_directory", category=ToolCategory.FILE_SYSTEM)
+async def list_directory(
+    context: 'AgentContext',
+    path: str,
+    depth: int = 2,
+    limit: int = 25,
+    offset: int = 1
+) -> str:
+    """
+    Lists the contents of a directory in a structured, tree-like format.
+
+    This tool performs a breadth-first traversal of the specified directory up to a
+    given depth. It returns a deterministic, lexicographically sorted list of entries,
+    formatted with indentation and tree glyphs to represent the hierarchy.
+
+    Args:
+        path: The path to the directory to list. Relative paths are resolved against the agent's workspace.
+        depth: The maximum directory depth to traverse. Must be > 0.
+        limit: The maximum number of entries to return in the output. Must be > 0.
+        offset: The 1-indexed entry number to start from, for pagination. Must be > 0.
+    """
+    # --- 1. Argument Validation ---
+    logger.debug(f"list_directory for agent {context.agent_id}, initial path: {path}")
+
+    final_path: str
+    if os.path.isabs(path):
+        final_path = path
+        logger.debug(f"Path '{path}' is absolute. Using it directly.")
+    else:
+        if not context.workspace:
+            error_msg = f"Relative path '{path}' provided, but no workspace is configured for agent '{context.agent_id}'. A workspace is required to resolve relative paths."
+            logger.error(error_msg)
+            raise ValueError(error_msg)
+
+        base_path = context.workspace.get_base_path()
+        if not base_path or not isinstance(base_path, str):
+            error_msg = f"Agent '{context.agent_id}' has a configured workspace, but it provided an invalid base path ('{base_path}'). Cannot resolve relative path '{path}'."
+            logger.error(error_msg)
+            raise ValueError(error_msg)
+
+        final_path = os.path.join(base_path, path)
+        logger.debug(f"Path '{path}' is relative. Resolved to '{final_path}' using workspace base path '{base_path}'.")
+
+    final_path = os.path.normpath(final_path)
+
+    if not Path(final_path).is_dir():
+        raise FileNotFoundError(f"Directory not found at path: {final_path}")
+    if depth <= 0 or limit <= 0 or offset <= 0:
+        raise ValueError("depth, limit, and offset must all be greater than zero.")
+
+    # --- 2. Asynchronous Traversal ---
+    loop = asyncio.get_running_loop()
+    all_entries = await loop.run_in_executor(
+        None, _traverse_directory_bfs, Path(final_path), depth
+    )
+
+    # --- 3. Slicing ---
+    total_found = len(all_entries)
+    start_index = offset - 1
+    end_index = start_index + limit
+    sliced_entries = all_entries[start_index:end_index]
+
+    # --- 4. Formatting ---
+    output_lines = [f"Absolute path: {final_path}"]
+    
+    # To correctly apply tree glyphs, we need to know which entry is the last in its directory
+    # This is complex with BFS. A simpler, visually acceptable approach is taken here.
+    # For a more accurate glyph representation like the Rust version, we would need to
+    # process entries directory by directory after collection.
+    for i, entry in enumerate(sliced_entries):
+        # A simplified glyph logic: last item in the slice gets the closing glyph
+        is_last = (i == len(sliced_entries) - 1)
+        output_lines.append(_format_entry_line(entry, is_last))
+
+    if total_found > end_index:
+        output_lines.append(f"More than {limit} entries found.")
+
+    return "\n".join(output_lines)
+
+
+def _traverse_directory_bfs(start_path: Path, max_depth: int) -> List[DirEntry]:
+    """
+    Performs a breadth-first traversal of a directory. This is a synchronous function
+    designed to be run in a thread pool executor.
+    """
+    collected: List[DirEntry] = []
+    queue: Deque[Tuple[Path, int]] = deque([(start_path, 0)])
+
+    while queue:
+        current_path, current_depth = queue.popleft()
+
+        if current_depth >= max_depth:
+            continue
+
+        try:
+            # Use os.scandir for efficiency as it fetches file type info
+            entries_at_level = []
+            for entry in os.scandir(current_path):
+                kind = "[unknown]"
+                if entry.is_dir():
+                    kind = "[dir]"
+                    queue.append((Path(entry.path), current_depth + 1))
+                elif entry.is_file():
+                    kind = "[file]"
+                elif entry.is_symlink():
+                    kind = "[link]"
+
+                # Truncate long filenames
+                display_name = entry.name
+                if len(display_name) > MAX_ENTRY_LENGTH:
+                    display_name = display_name[:MAX_ENTRY_LENGTH] + "..."
+                
+                entries_at_level.append(DirEntry(name=display_name, kind=kind, depth=current_depth + 1))
+            
+            # Sort entries at the current level before adding to the main list
+            entries_at_level.sort(key=lambda e: e.name)
+            collected.extend(entries_at_level)
+
+        except (PermissionError, OSError) as e:
+            logger.warning(f"Could not read directory '{current_path}': {e}")
+            continue
+    
+    return collected
+
+
+def _format_entry_line(entry: DirEntry, is_last_in_slice: bool) -> str:
+    """Formats a single directory entry into its final string representation."""
+    # This simplified glyph logic doesn't know about siblings, just the slice.
+    # A full implementation would require grouping by parent path after collection.
+    prefix = "└─ " if is_last_in_slice else "├─ "
+    
+    # Indentation is based on depth from the root search path
+    indentation = " " * INDENTATION_SPACES * (entry.depth -1)
+    
+    return f"{indentation}{prefix}{entry.kind} {entry.name}"