wcode_errors.py

"""Unified exception hierarchy for the Wcode agent.

All Wcode-specific exceptions inherit from :class:`WcodeError`.  Tool functions
**raise** these exceptions instead of returning ``"Error: ..."`` strings.  The
tool execution layer (:meth:`ToolRegistry.execute`) catches them uniformly and
converts them to user-facing tool result strings.

Usage::

    from wcode_errors import WcodeError, ToolError, ConfigError, CronError

    raise ToolError("File not found: src/main.py")
    raise CronError("Invalid cron expression: 5 fields expected, got 6")
    raise ConfigError("Missing required env var: API_KEY")
"""


class WcodeError(Exception):
    """Base exception for all Wcode errors.

    All domain-specific exceptions inherit from this class so that the tool
    execution layer can catch ``WcodeError`` uniformly.
    """


class ToolError(WcodeError):
    """Raised when a tool function encounters an error during execution.

    Examples: file not found, shell command timeout, invalid arguments,
    permission denied, unknown tool name.
    """


class ConfigError(WcodeError):
    """Raised for configuration or environment errors.

    Examples: missing required env vars, invalid config values,
    unreadable config files.
    """


class CronError(WcodeError):
    """Raised for cron expression validation or scheduling errors.

    Examples: malformed cron expression, out-of-bounds field values,
    duplicate job IDs.
    """