fluers-core 0.6.0

//! Error types for the core crate.

use thiserror::Error;

/// A specialized [`Result`] for `fluers-core` operations.
pub type Result<T> = std::result::Result<T, CoreError>;

/// Errors raised by the core agent/model layer.
#[derive(Debug, Error)]
pub enum CoreError {
    /// A tool call referenced an unknown tool.
    #[error("unknown tool: {0}")]
    UnknownTool(String),

    /// Tool input failed JSON-schema validation.
    #[error("tool input validation failed: {0}")]
    ToolInputValidation(String),

    /// Tool output failed to serialize or validate.
    #[error("tool output invalid: {0}")]
    ToolOutput(String),

    /// The model provider rejected the request.
    #[error("model provider error: {0}")]
    ModelProvider(String),

    /// The model response could not be parsed.
    #[error("model response parse error: {0}")]
    ModelResponse(String),

    /// An I/O or transport error talking to a provider.
    #[error("transport error: {0}")]
    Transport(String),

    /// A caller cancelled the operation (e.g. SIGINT, token triggered).
    ///
    /// Distinct from [`CoreError::TurnTimeout`]: a *caller-initiated* abort,
    /// not a deadline elapsing. Keeping the two separate lets the CLI map a
    /// turn-budget timeout to exit code `124` without string-matching the
    /// message (the headless runner contract distinguishes them).
    #[error("operation cancelled: {0}")]
    Cancelled(String),

    /// A per-turn deadline elapsed (the agent loop's `turn_timeout_ms`).
    ///
    /// Mapped to exit code `124` by the CLI headless runner (matching the
    /// `timeout(1)` convention used by the bash tool). This is a *deadline*
    /// event, not caller-initiated cancellation — see [`CoreError::Cancelled`].
    #[error("turn timed out after {ms}ms")]
    TurnTimeout {
        /// The per-turn deadline that was exceeded, in milliseconds.
        ms: u64,
    },
}