gglib_core/domain/agent/

config.rs

//! [`AgentConfig`] — configuration for a single agentic loop run.
//!
//! This module also defines the public ceiling constants used by HTTP and CLI
//! callers to clamp untrusted user input to safe values.  Centralising them
//! here ensures a single source of truth across all entry points.

use serde::Serialize;
use thiserror::Error;

// =============================================================================
// Ceiling constants — shared across HTTP and CLI callers
// =============================================================================

/// Hard ceiling on `max_iterations` accepted from external callers.
///
/// 50 iterations is generous for real workloads.  Prevents a crafted request
/// from running an unbounded loop at server expense.
pub const MAX_ITERATIONS_CEILING: usize = 50;

/// Hard ceiling on `max_parallel_tools` accepted from external callers.
///
/// 50 concurrent tools per iteration is far beyond any practical need and
/// prevents thread-pool saturation from crafted requests.  Modern reasoning
/// models occasionally request large parallel batches (10–25 calls); the
/// ceiling must comfortably exceed the default to leave headroom for users
/// who legitimately want to raise the limit.
pub const MAX_PARALLEL_TOOLS_CEILING: usize = 50;

/// Hard ceiling on `tool_timeout_ms` accepted from external callers (60 s).
///
/// Prevents a crafted request from holding server connections open
/// indefinitely via slow or stalled tool calls.
pub const MAX_TOOL_TIMEOUT_MS_CEILING: u64 = 60_000;

/// Hard floor on `tool_timeout_ms` accepted from external callers (100 ms).
///
/// A value of 0 would silently time out every tool call immediately, making
/// tool calling unusable without a clear error.  100 ms is still very tight
/// but allows intentionally fast tools (health checks, no-ops in tests).
pub const MIN_TOOL_TIMEOUT_MS: u64 = 100;

/// Hard floor on `context_budget_chars` (100 characters).
///
/// A budget below this threshold would cause the pruner to discard virtually
/// all context, leaving the LLM with no meaningful history to reason about.
pub const MIN_CONTEXT_BUDGET_CHARS: usize = 100;

/// Default value for [`AgentConfig::max_iterations`].
///
/// Mirrors `DEFAULT_MAX_TOOL_ITERS = 25` from the TypeScript frontend.
/// Used both in [`AgentConfig::default`] and in [`super::events::AGENT_EVENT_CHANNEL_CAPACITY`]
/// so the channel size automatically scales with the iteration ceiling.
pub const DEFAULT_MAX_ITERATIONS: usize = 25;

/// Default value for [`AgentConfig::max_parallel_tools`].
///
/// Set to 25 to comfortably accommodate modern reasoning models (Qwen3-MoE,
/// DeepSeek-R1, etc.) that routinely request 6–10 parallel tool calls per
/// turn during exploration-heavy tasks (e.g. codebase reviews).  An overflow
/// is no longer fatal — the loop now soft-recovers by injecting a synthetic
/// tool error and asking the model to retry with a smaller batch — but a
/// generous default avoids triggering that recovery path under normal load.
///
/// Used both in [`AgentConfig::default`] and in [`super::events::AGENT_EVENT_CHANNEL_CAPACITY`]
/// so the channel size accounts for the correct number of concurrent tool events.
pub const DEFAULT_MAX_PARALLEL_TOOLS: usize = 25;

/// Default value for [`AgentConfig::max_stagnation_steps`].
///
/// The agent loop aborts when the same assistant text has been seen more
/// than this many times, preventing infinite stagnant output.
pub const DEFAULT_MAX_STAGNATION_STEPS: usize = 5;

/// Hard ceiling on [`AgentConfig::max_stagnation_steps`] accepted from
/// external callers.
///
/// Prevents a persisted setting or API caller from setting
/// `max_stagnation_steps` to an arbitrarily large value, which would
/// silently neutralise the stagnation guard and let a stuck model repeat
/// the same response indefinitely.  Mirrors
/// [`MAX_OBSERVATION_STEPS_CEILING`].
pub const MAX_STAGNATION_STEPS_CEILING: usize = 100;

/// Hard ceiling on [`AgentConfig::max_observation_steps`] accepted from
/// external callers.
///
/// Prevents an API or CLI caller from setting `max_observation_steps` to an
/// arbitrarily large value, which would silently neutralise the observation
/// guard and allow a confused agent to call observation tools indefinitely.
/// 100 observation-only iterations is far more than any legitimate browsing
/// task requires.
pub const MAX_OBSERVATION_STEPS_CEILING: usize = 100;

/// Default value for [`AgentConfig::max_observation_steps`].
///
/// An exploratory-tool-only batch (every call matches a pattern in
/// [`AgentConfig::observation_tools`]) may repeat up to this many times
/// before loop detection fires.  15 is generous for multi-page browsing,
/// multi-directory walking, and paginated API tasks while still catching
/// a genuinely confused agent within a reasonable token budget.
pub const DEFAULT_MAX_OBSERVATION_STEPS: usize = 15;

/// Configuration that governs a single agentic loop run.
///
/// All fields have sensible defaults via [`Default`]. These used to mirror
/// TypeScript constants in the frontend's own agent loop; that loop is
/// backend-driven now, and `streamAgentChat.ts` records these fields as
/// deliberately absent from it, so nothing in the frontend's loop competes with
/// the values here. What the settings UI still carries are the *ceilings and
/// floors* it clamps user input to (`MAX_PARALLEL_TOOLS_CEILING`,
/// `TOOL_TIMEOUT_MS_FLOOR` and friends), and its own copies of the two defaults
/// a person can edit — `MAX_TOOL_ITERATIONS`, pinned against this file by
/// `settingsBounds.test.ts`, and `MAX_STAGNATION_STEPS`, pinned by
/// `settingsParity.test.ts`.
///
/// # Serialisation
///
/// `AgentConfig` is intentionally **not** `Deserialize`.  External callers
/// (HTTP, future config files) must go through a dedicated DTO that exposes
/// only the safe subset of fields.  This prevents accidental exposure of
/// internal tuning knobs (pruning parameters, strike limits, etc.) to
/// untrusted callers.
#[derive(Debug, Clone, Serialize)]
#[non_exhaustive]
pub struct AgentConfig {
    /// Maximum number of LLM→tool→LLM iterations before the loop is aborted.
    pub max_iterations: usize,

    /// Maximum number of tool calls that may be executed in parallel per iteration.
    ///
    /// **Dual-purpose:** this value is used both as the `Semaphore` concurrency
    /// cap in `tool_execution` (limiting simultaneous in-flight calls) *and* as
    /// an upper bound on the batch size the model may request in a single turn.
    /// If the model emits more tool calls than this limit, the loop terminates
    /// with [`AgentError::ParallelToolLimitExceeded`](crate::ports::AgentError::ParallelToolLimitExceeded)
    /// rather than silently
    /// serialising them.  Setting this to `1` means the model may only request
    /// **one** tool call per turn; two calls in a single response will abort the
    /// loop, not run them sequentially.
    pub max_parallel_tools: usize,

    /// Per-tool execution timeout in milliseconds.
    pub tool_timeout_ms: u64,

    /// Maximum total character budget across all messages before context pruning
    /// is applied.
    pub context_budget_chars: usize,

    /// Maximum number of times the same tool-call batch signature may repeat
    /// **back to back and answered the same way** before the loop is declared
    /// stuck and aborted with [`crate::ports::AgentError::LoopDetected`].
    ///
    /// Consecutive, not session-wide: a batch with a different signature
    /// resets the run. So does an answer that differs from the previous
    /// occurrence's — the same call with a different result is progress that
    /// happens to look alike, and is not a strike. Contrast
    /// [`Self::max_stagnation_steps`] below, which is windowed and reads
    /// nothing but prose turns. See the `loop_detection` module docs for why
    /// the three differ.
    ///
    /// Set to `None` to disable loop detection entirely (useful in tests that
    /// deliberately repeat the same tool call).
    pub max_repeated_batch_steps: Option<usize>,

    /// Occurrence limit for identical assistant text within a sliding window,
    /// before the loop is considered stagnant and aborted with
    /// [`crate::ports::AgentError::StagnationDetected`].
    ///
    /// **Semantics:** Occurrences of the same response text are counted within
    /// the last `max_stagnation_steps × 4` recorded turns.  The error fires
    /// when that count exceeds `max_stagnation_steps`.  With the default value
    /// of `5`, stagnation triggers on the **sixth** identical occurrence.
    /// With `max_stagnation_steps = 0`, the error fires on the **very first**
    /// occurrence of any repeated text.
    ///
    /// Only turns that called **no tools** are recorded: narration alongside a
    /// tool call is not stagnation, and the loop detector judges that work.
    /// A → B → A → B oscillation in the prose is still caught. See ADR 0011.
    ///
    /// Set to `None` to disable stagnation detection entirely (useful in tests
    /// that return a fixed LLM response across many iterations).
    pub max_stagnation_steps: Option<usize>,

    /// Number of most-recent tool-result messages preserved during the first
    /// pass of context pruning.
    ///
    /// Not exposed as a user-facing option because the value is calibrated
    /// to balance context retention against token budget; changing it
    /// independently of `context_budget_chars` can produce incoherent
    /// conversation histories.
    #[serde(skip)]
    pub prune_keep_tool_messages: usize,

    /// Number of non-system messages retained during the emergency tail-prune
    /// pass (second pass of context pruning).
    ///
    /// Same rationale as [`Self::prune_keep_tool_messages`].
    #[serde(skip)]
    pub prune_keep_tail_messages: usize,

    // -------------------------------------------------------------------------
    // Dual-threshold observation guard
    // -------------------------------------------------------------------------
    //
    // Standard loop detection (max_repeated_batch_steps) hashes tool names and
    // arguments to detect a batch repeated back to back.  It does not detect
    // cycles: a batch that recurs with other work in between resets the run,
    // so A -> B -> A -> B escapes it entirely.  See the `loop_detection`
    // module docs for why that cost was taken.  Observation-only tools (e.g. browser
    // snapshots, screenshots) legitimately repeat with identical signatures
    // because they take no meaningful arguments, yet return completely different
    // page content on each call.  These two fields allow a separate, higher
    // threshold to be applied when every tool in a batch is classified as an
    // exploratory tool, preventing false-positive loop aborts during ReAct
    // observation and navigation cycles while still catching an agent that
    // repeats one of them back to back without pause.
    /// Substring patterns used to classify tools as **exploratory**.
    ///
    /// "Exploratory" tools are those that drive progress by repeatedly
    /// querying or traversing a stateful source — page snapshots, navigation,
    /// clicks, file reads, directory listings, API pagination calls, etc.
    /// Their repeated invocation with identical arguments is a legitimate
    /// `ReAct` pattern, not a stuck loop.
    ///
    /// A tool call whose **lowercased** name contains any pattern in this list
    /// as a substring is classified as exploratory, so a short pattern like
    /// `"read"` also covers `thread_create`.  When **every** call in a batch
    /// matches, [`Self::max_observation_steps`] is applied as the loop
    /// detection threshold instead of [`Self::max_repeated_batch_steps`].
    ///
    /// **Matching semantics** — substring rather than exact string — are
    /// intentional: MCP servers routinely prepend namespace prefixes to tool
    /// names (e.g. `playwright_mcp_browser_snapshot`), so exact matching would
    /// require users to enumerate every vendor variant.  The pattern `"navigate"`
    /// matches `browser_navigate`, `db_navigate`, `fs_navigate`, etc.
    ///
    /// **BYO-MCP:** users connecting custom MCP servers should extend or replace
    /// this list via [`AgentConfig::from_user_params`] to include their own
    /// exploratory tool name fragments (e.g. `"get_dom"`, `"fetch_page"`,
    /// `"list_dir"`).
    ///
    /// An empty list means no tools are ever classified as exploratory;
    /// the standard [`Self::max_repeated_batch_steps`] threshold applies to all
    /// batches.
    ///
    /// Defaults cover both agent families gglib serves: browser/GUI tools
    /// (`snapshot`, `screenshot`, `read_page`, `navigate`, `click`) and the
    /// read-only tools coding agents repeat constantly (`read_file`,
    /// `list_dir`, `grep_search`, `search_files`, …). See the `Default` impl
    /// for why every entry is a full tool name rather than a fragment.
    pub observation_tools: Vec<String>,

    /// Maximum number of times an exploratory-tool-only batch may repeat
    /// **back to back and be answered the same way** before loop detection
    /// fires.
    ///
    /// Applied **instead of** [`Self::max_repeated_batch_steps`] when every
    /// tool call in the current batch matches a pattern in
    /// [`Self::observation_tools`].  A higher value (default: 15) gives the
    /// agent room to browse multiple pages, walk directory trees, or paginate
    /// through API results while still aborting an agent that repeats one
    /// identical batch back to back before it exhausts the token budget.
    ///
    /// **Mixed batches** (at least one non-exploratory tool alongside an
    /// exploratory one) always fall back to [`Self::max_repeated_batch_steps`]
    /// — the conservative choice.
    ///
    /// Clamped to [`MAX_OBSERVATION_STEPS_CEILING`] when supplied via
    /// [`AgentConfig::from_user_params`] to prevent API callers from providing
    /// a value large enough to neutralise the guard.
    ///
    /// # It is also the ceiling on rescued repeats
    ///
    /// A repeat whose answer *changed* is not a strike — an agent polling a
    /// build for output repeats a batch every turn and is working. That reset
    /// would, on its own, exempt any tool whose output carries a clock or a
    /// counter, so a batch may be carried by changing answers only while its
    /// run stays inside this allowance — unless it is exploratory *and* free
    /// to repeat. The number is reused rather than invented: an exploratory
    /// batch already gets it because repeating a call which changes nothing
    /// is free, and there is no measurement behind a second number.
    ///
    /// So this field is read twice for a mutating batch, and for an
    /// exploratory one that costs something elsewhere — never as a strike
    /// threshold, always as the ceiling on a moving answer. See
    /// [ADR 0010](https://github.com/mmogr/gglib/blob/main/docs/adr/0010-the-loop-guard-reads-what-came-back.md).
    ///
    /// Set to `None` to disable the elevated threshold entirely; exploratory
    /// batches then use [`Self::max_repeated_batch_steps`] like any other
    /// batch, and the rescue ceiling collapses onto that too — which leaves
    /// the verdict exactly as it was before it read answers at all.
    ///
    /// Default: `Some(15)`.
    pub max_observation_steps: Option<usize>,
}

impl Default for AgentConfig {
    fn default() -> Self {
        Self {
            max_iterations: DEFAULT_MAX_ITERATIONS,
            max_parallel_tools: DEFAULT_MAX_PARALLEL_TOOLS,
            tool_timeout_ms: 30_000,
            context_budget_chars: 180_000,
            max_repeated_batch_steps: Some(2),
            max_stagnation_steps: Some(DEFAULT_MAX_STAGNATION_STEPS),
            prune_keep_tool_messages: 10,
            prune_keep_tail_messages: 12,
            observation_tools: vec![
                // Browser / GUI agents.
                "snapshot".into(),
                "screenshot".into(),
                "read_page".into(),
                "navigate".into(),
                "click".into(),
                // Coding agents. Without these a VS Code Copilot or Cline
                // session that reads the same file three times — read, edit,
                // re-read to verify — is classified as a non-observation
                // repeat and rejected at `max_repeated_batch_steps` (2)
                // rather than at `max_observation_steps` (15).
                //
                // Matching is `contains` (see `is_observation_batch`), so a
                // short fragment silently captures unrelated tools: "read"
                // matches `thread_create`, "list" matches `listen_port`,
                // "glob" matches `set_global_config`. Every pattern here is
                // long enough that the only names it can capture are
                // themselves read-only — `list_dir` also covers
                // `list_directory` and `list_directory_with_sizes`, which is
                // why neither is listed separately.
                //
                // Deliberately absent for the same reason: bare `read`,
                // `grep`, `glob` and `view`, which some clients use as whole
                // tool names. There is no way to match those without also
                // exempting `thread_*`, `set_global_*` and `preview_*`, and
                // a guard that silently stops guarding is worse than one
                // that occasionally refuses honest work.
                "read_file".into(),
                "read_text_file".into(),
                "read_media_file".into(),
                "read_multiple_files".into(),
                "list_dir".into(),
                "list_files".into(),
                "list_allowed_directories".into(),
                "directory_tree".into(),
                "file_search".into(),
                "grep_search".into(),
                "search_files".into(),
                "semantic_search".into(),
                "codebase_search".into(),
                "test_search".into(),
                "get_file_info".into(),
                "get_errors".into(),
                "get_changed_files".into(),
                "get_terminal_output".into(),
                "list_code_usages".into(),
                "list_code_definition_names".into(),
                // The one entry the "changes nothing" rule covers only
                // locally: repeating it is free on this machine but spends
                // someone else's rate limit. Kept because re-reading docs
                // mid-task is ordinary — and held to 15 rather than waived,
                // by `is_costly_batch`, alongside `navigate` and `click`.
                "fetch_webpage".into(),
            ],
            max_observation_steps: Some(DEFAULT_MAX_OBSERVATION_STEPS),
        }
    }
}

// =============================================================================
// Validation
// =============================================================================

/// Error returned when [`AgentConfig::validated`] detects an invalid field.
///
/// Each variant names the exact invariant that was violated and carries the
/// offending value so callers (HTTP handlers, CLI) can surface a precise
/// diagnostic without re-inspecting the config.
#[derive(Debug, Clone, PartialEq, Eq, Error)]
pub enum AgentConfigError {
    /// `max_iterations` must be ≥ 1 — zero would make the loop exit
    /// immediately as `MaxIterationsReached(0)` without ever calling the LLM.
    #[error("max_iterations must be >= 1, got {0}")]
    MaxIterationsZero(usize),

    /// `max_parallel_tools` must be ≥ 1 — zero would deadlock the
    /// `Semaphore` used for tool-call concurrency (no permit can ever be
    /// acquired).
    #[error("max_parallel_tools must be >= 1, got {0} (0 would deadlock the semaphore)")]
    MaxParallelToolsZero(usize),

    /// `tool_timeout_ms` must be ≥ [`MIN_TOOL_TIMEOUT_MS`] — a value below
    /// the floor would silently time out every tool call, making tool
    /// calling unusable without a clear error.
    #[error("tool_timeout_ms must be >= {MIN_TOOL_TIMEOUT_MS}, got {0}")]
    ToolTimeoutTooLow(u64),
    /// `context_budget_chars` must be >= [`MIN_CONTEXT_BUDGET_CHARS`] — a value
    /// below the floor would cause the pruner to discard virtually all context.
    #[error("context_budget_chars must be >= {MIN_CONTEXT_BUDGET_CHARS}, got {0}")]
    ContextBudgetTooLow(usize),
}

impl AgentConfig {
    /// Build an `AgentConfig` from user-supplied overrides.
    ///
    /// Each `Some` numeric value is clamped to the safe `[floor, ceiling]`
    /// range before assignment; `None` fields retain their [`Default`] values.
    /// The result is validated before returning.
    ///
    /// This is the **single entry-point** for HTTP, Tauri, and CLI callers,
    /// eliminating duplicated clamping logic at every call site.
    ///
    /// # Observation-tool parameters
    ///
    /// - `observation_tools: Some(vec)` — **replaces** the default pattern list
    ///   entirely.  Pass the complete list you want, including any defaults you
    ///   wish to preserve.  `Some(vec![])` disables observation classification
    ///   (standard threshold applies to all batches).  `None` keeps the
    ///   built-in defaults, which cover browser tools and the read-only tools
    ///   coding agents repeat (see `AgentConfig::default`).
    ///
    /// - `max_observation_steps: Some(n)` — clamped to
    ///   `[1, MAX_OBSERVATION_STEPS_CEILING]`.  `None` keeps the built-in
    ///   default of `Some(15)`.
    ///
    /// # Stagnation parameter
    ///
    /// `max_stagnation_steps: Some(n)` — clamped to
    /// `[1, MAX_STAGNATION_STEPS_CEILING]`; `None` keeps the built-in default
    /// of `Some(DEFAULT_MAX_STAGNATION_STEPS)`.  The floor is 1 because a
    /// value of 0 would abort on the *first* occurrence of any response.
    /// Callers pass the persisted `Settings::max_stagnation_steps` here; it
    /// is deliberately not exposed per-request.
    ///
    /// # Errors
    ///
    /// Returns `Err(AgentConfigError)` if the clamped config violates any
    /// invariant (defense-in-depth — should never happen given the clamping).
    pub fn from_user_params(
        max_iterations: Option<usize>,
        max_parallel_tools: Option<usize>,
        tool_timeout_ms: Option<u64>,
        observation_tools: Option<Vec<String>>,
        max_observation_steps: Option<usize>,
        max_stagnation_steps: Option<usize>,
    ) -> Result<Self, AgentConfigError> {
        let mut cfg = Self::default();
        if let Some(n) = max_iterations {
            cfg.max_iterations = n.clamp(1, MAX_ITERATIONS_CEILING);
        }
        if let Some(n) = max_parallel_tools {
            cfg.max_parallel_tools = n.clamp(1, MAX_PARALLEL_TOOLS_CEILING);
        }
        if let Some(ms) = tool_timeout_ms {
            cfg.tool_timeout_ms = ms.clamp(MIN_TOOL_TIMEOUT_MS, MAX_TOOL_TIMEOUT_MS_CEILING);
        }
        if let Some(tools) = observation_tools {
            cfg.observation_tools = tools;
        }
        if let Some(n) = max_observation_steps {
            cfg.max_observation_steps = Some(n.clamp(1, MAX_OBSERVATION_STEPS_CEILING));
        }
        if let Some(n) = max_stagnation_steps {
            cfg.max_stagnation_steps = Some(n.clamp(1, MAX_STAGNATION_STEPS_CEILING));
        }
        cfg.validated()
    }

    /// Validate all fields that could cause the agent loop to malfunction.
    ///
    /// Call this after constructing an `AgentConfig` from untrusted input.
    /// The [`Default`] implementation is always valid; this acts as a safety
    /// net for values assembled by HTTP DTOs or CLI argument parsing.
    ///
    /// # Errors
    ///
    /// Returns `Err(AgentConfigError)` if any field violates its invariant.
    pub fn validated(self) -> Result<Self, AgentConfigError> {
        if self.max_iterations < 1 {
            return Err(AgentConfigError::MaxIterationsZero(self.max_iterations));
        }
        if self.max_parallel_tools < 1 {
            return Err(AgentConfigError::MaxParallelToolsZero(
                self.max_parallel_tools,
            ));
        }
        if self.tool_timeout_ms < MIN_TOOL_TIMEOUT_MS {
            return Err(AgentConfigError::ToolTimeoutTooLow(self.tool_timeout_ms));
        }
        if self.context_budget_chars < MIN_CONTEXT_BUDGET_CHARS {
            return Err(AgentConfigError::ContextBudgetTooLow(
                self.context_budget_chars,
            ));
        }
        Ok(self)
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn defaults_match_frontend_constants() {
        let cfg = AgentConfig::default();
        assert_eq!(cfg.max_iterations, DEFAULT_MAX_ITERATIONS);
        assert_eq!(cfg.max_parallel_tools, DEFAULT_MAX_PARALLEL_TOOLS);
        assert_eq!(cfg.tool_timeout_ms, 30_000);
        assert_eq!(cfg.context_budget_chars, 180_000);
        assert_eq!(cfg.max_repeated_batch_steps, Some(2));
        assert_eq!(
            cfg.max_stagnation_steps,
            Some(5),
            "the documented default stagnation ceiling"
        );
        assert_eq!(cfg.prune_keep_tool_messages, 10);
        assert_eq!(cfg.prune_keep_tail_messages, 12);
        assert_eq!(
            cfg.observation_tools,
            vec![
                "snapshot",
                "screenshot",
                "read_page",
                "navigate",
                "click",
                "read_file",
                "read_text_file",
                "read_media_file",
                "read_multiple_files",
                "list_dir",
                "list_files",
                "list_allowed_directories",
                "directory_tree",
                "file_search",
                "grep_search",
                "search_files",
                "semantic_search",
                "codebase_search",
                "test_search",
                "get_file_info",
                "get_errors",
                "get_changed_files",
                "get_terminal_output",
                "list_code_usages",
                "list_code_definition_names",
                "fetch_webpage",
            ],
            "default exploratory patterns must cover both browser tools and the \
             read-only tools coding agents repeat"
        );
        assert_eq!(
            cfg.max_observation_steps,
            Some(DEFAULT_MAX_OBSERVATION_STEPS),
            "must match DEFAULT_MAX_OBSERVATION_STEPS"
        );
    }

    #[test]
    fn default_config_passes_validation() {
        assert!(AgentConfig::default().validated().is_ok());
    }

    #[test]
    fn zero_max_iterations_rejected() {
        let cfg = AgentConfig {
            max_iterations: 0,
            ..Default::default()
        };
        assert_eq!(
            cfg.validated().unwrap_err(),
            AgentConfigError::MaxIterationsZero(0),
        );
    }

    #[test]
    fn zero_max_parallel_tools_rejected() {
        let cfg = AgentConfig {
            max_parallel_tools: 0,
            ..Default::default()
        };
        assert_eq!(
            cfg.validated().unwrap_err(),
            AgentConfigError::MaxParallelToolsZero(0),
        );
    }

    #[test]
    fn tool_timeout_below_floor_rejected() {
        let cfg = AgentConfig {
            tool_timeout_ms: MIN_TOOL_TIMEOUT_MS - 1,
            ..Default::default()
        };
        assert_eq!(
            cfg.validated().unwrap_err(),
            AgentConfigError::ToolTimeoutTooLow(MIN_TOOL_TIMEOUT_MS - 1),
        );
    }

    #[test]
    fn tool_timeout_at_floor_accepted() {
        let cfg = AgentConfig {
            tool_timeout_ms: MIN_TOOL_TIMEOUT_MS,
            ..Default::default()
        };
        assert!(cfg.validated().is_ok());
    }

    #[test]
    fn context_budget_below_floor_rejected() {
        let cfg = AgentConfig {
            context_budget_chars: MIN_CONTEXT_BUDGET_CHARS - 1,
            ..Default::default()
        };
        assert_eq!(
            cfg.validated().unwrap_err(),
            AgentConfigError::ContextBudgetTooLow(MIN_CONTEXT_BUDGET_CHARS - 1),
        );
    }

    #[test]
    fn context_budget_at_floor_accepted() {
        let cfg = AgentConfig {
            context_budget_chars: MIN_CONTEXT_BUDGET_CHARS,
            ..Default::default()
        };
        assert!(cfg.validated().is_ok());
    }

    #[test]
    fn boundary_values_accepted() {
        let cfg = AgentConfig {
            max_iterations: 1,
            max_parallel_tools: 1,
            tool_timeout_ms: MIN_TOOL_TIMEOUT_MS,
            context_budget_chars: MIN_CONTEXT_BUDGET_CHARS,
            ..Default::default()
        };
        assert!(cfg.validated().is_ok());
    }

    #[test]
    fn from_user_params_clamps_and_validates() {
        // All values within range → accepted as-is.
        let cfg = AgentConfig::from_user_params(Some(10), Some(3), Some(5_000), None, None, None)
            .unwrap();
        assert_eq!(cfg.max_iterations, 10);
        assert_eq!(cfg.max_parallel_tools, 3);
        assert_eq!(cfg.tool_timeout_ms, 5_000);
    }

    #[test]
    fn from_user_params_clamps_extremes() {
        // Zero iterations → clamped to 1.
        let cfg =
            AgentConfig::from_user_params(Some(0), Some(0), Some(0), None, None, None).unwrap();
        assert_eq!(cfg.max_iterations, 1);
        assert_eq!(cfg.max_parallel_tools, 1);
        assert_eq!(cfg.tool_timeout_ms, MIN_TOOL_TIMEOUT_MS);
    }

    #[test]
    fn from_user_params_clamps_above_ceiling() {
        let cfg = AgentConfig::from_user_params(
            Some(usize::MAX),
            Some(usize::MAX),
            Some(u64::MAX),
            None,
            None,
            None,
        )
        .unwrap();
        assert_eq!(cfg.max_iterations, MAX_ITERATIONS_CEILING);
        assert_eq!(cfg.max_parallel_tools, MAX_PARALLEL_TOOLS_CEILING);
        assert_eq!(cfg.tool_timeout_ms, MAX_TOOL_TIMEOUT_MS_CEILING);
    }

    #[test]
    fn from_user_params_none_keeps_defaults() {
        let cfg = AgentConfig::from_user_params(None, None, None, None, None, None).unwrap();
        let def = AgentConfig::default();
        assert_eq!(cfg.max_iterations, def.max_iterations);
        assert_eq!(cfg.max_parallel_tools, def.max_parallel_tools);
        assert_eq!(cfg.tool_timeout_ms, def.tool_timeout_ms);
        assert_eq!(cfg.observation_tools, def.observation_tools);
        assert_eq!(cfg.max_observation_steps, def.max_observation_steps);
    }

    #[test]
    fn from_user_params_observation_tools_replaces_defaults() {
        // A non-None observation_tools list replaces the built-in defaults.
        let custom = vec!["get_dom".into(), "fetch_page".into()];
        let cfg = AgentConfig::from_user_params(None, None, None, Some(custom.clone()), None, None)
            .unwrap();
        assert_eq!(cfg.observation_tools, custom);
    }

    #[test]
    fn from_user_params_empty_observation_tools_disables_classification() {
        // Some([]) disables observation classification — no tools ever match.
        let cfg =
            AgentConfig::from_user_params(None, None, None, Some(vec![]), None, None).unwrap();
        assert!(cfg.observation_tools.is_empty());
    }

    #[test]
    fn from_user_params_observation_steps_clamped_to_ceiling() {
        let cfg =
            AgentConfig::from_user_params(None, None, None, None, Some(usize::MAX), None).unwrap();
        assert_eq!(
            cfg.max_observation_steps,
            Some(MAX_OBSERVATION_STEPS_CEILING),
        );
    }

    #[test]
    fn from_user_params_observation_steps_clamped_to_floor() {
        // Zero would mean fire on the very first occurrence — clamp to 1.
        let cfg = AgentConfig::from_user_params(None, None, None, None, Some(0), None).unwrap();
        assert_eq!(cfg.max_observation_steps, Some(1));
    }

    #[test]
    fn from_user_params_observation_steps_within_range_unchanged() {
        let cfg = AgentConfig::from_user_params(None, None, None, None, Some(15), None).unwrap();
        assert_eq!(cfg.max_observation_steps, Some(15));
    }

    #[test]
    fn from_user_params_stagnation_steps_clamped_to_ceiling() {
        let cfg =
            AgentConfig::from_user_params(None, None, None, None, None, Some(usize::MAX)).unwrap();
        assert_eq!(cfg.max_stagnation_steps, Some(MAX_STAGNATION_STEPS_CEILING));
    }

    #[test]
    fn from_user_params_stagnation_steps_clamped_to_floor() {
        // Zero would mean abort on the first occurrence of any text — clamp to 1.
        let cfg = AgentConfig::from_user_params(None, None, None, None, None, Some(0)).unwrap();
        assert_eq!(cfg.max_stagnation_steps, Some(1));
    }

    #[test]
    fn from_user_params_stagnation_steps_none_keeps_default() {
        let cfg = AgentConfig::from_user_params(None, None, None, None, None, None).unwrap();
        assert_eq!(cfg.max_stagnation_steps, Some(DEFAULT_MAX_STAGNATION_STEPS),);
    }
}