Module error 

Common error utilities for agent tools

This module provides shared error handling infrastructure without replacing individual tool error types. Each tool keeps its own error type (e.g., ReadFileError, ShellError) but uses these utilities for consistent formatting.

Pattern

Tools should:

1. Keep their own error type deriving thiserror::Error
2. Use ToolErrorContext trait to add context when propagating errors
3. Use format_error_for_llm when returning error JSON to the agent

Example

use crate::agent::tools::error::{ToolErrorContext, ErrorCategory, format_error_for_llm};

fn read_config(&self, path: &Path) -> Result<String, ReadFileError> {
    fs::read_to_string(path)
        .with_tool_context("read_file", "reading configuration file")
        .map_err(|e| ReadFileError(e))
}

// In tool call, for JSON error responses:
let error_json = format_error_for_llm(
    "read_file",
    ErrorCategory::FileNotFound,
    "File not found: config.yaml",
    Some(vec!["Check if the file exists", "Verify the path is correct"]),
);

Enums

ErrorCategory

Common error categories for tool errors

Traits

ToolErrorContext

Extension trait for adding tool context to errors

Functions

detect_error_category

Helper to detect error category from common error patterns

format_error_for_llm

Format an error for LLM consumption

format_error_with_context

Format an error with additional context fields