Struct AgentConfig 

#[non_exhaustive]
pub struct AgentConfig {
    pub max_iterations: usize,
    pub max_parallel_tools: usize,
    pub tool_timeout_ms: u64,
    pub context_budget_chars: usize,
    pub max_repeated_batch_steps: Option<usize>,
    pub max_stagnation_steps: Option<usize>,
    pub prune_keep_tool_messages: usize,
    pub prune_keep_tail_messages: usize,
}

Configuration that governs a single agentic loop run.

All fields have sensible defaults via Default that match the historical TypeScript frontend constants (previously in agentLoop.ts, now reflected in streamAgentChat.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.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

max_iterations: usize

Maximum number of LLM→tool→LLM iterations before the loop is aborted.

Frontend constant: DEFAULT_MAX_TOOL_ITERS = 25.

max_parallel_tools: 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] 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.

Frontend constant: MAX_PARALLEL_TOOLS = 5.

tool_timeout_ms: u64

Per-tool execution timeout in milliseconds.

Frontend constant: TOOL_TIMEOUT_MS = 30_000.

context_budget_chars: usize

Maximum total character budget across all messages before context pruning is applied.

Frontend constant: MAX_CONTEXT_CHARS = 180_000.

max_repeated_batch_steps: Option<usize>

Maximum number of times the same tool-call batch signature may repeat before the loop is declared stuck and aborted with crate::ports::AgentError::LoopDetected.

Frontend constant: MAX_SAME_SIGNATURE_HITS = 2 in streamAgentChat.ts.

Set to None to disable loop detection entirely (useful in tests that deliberately repeat the same tool call).

max_stagnation_steps: Option<usize>

Session-wide occurrence limit for identical assistant text before the loop is considered stagnant and aborted with crate::ports::AgentError::StagnationDetected.

Semantics: Each occurrence of the same response text increments a session counter. The error fires when the counter after incrementing 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.

Frontend constant: MAX_STAGNATION_STEPS = 5 in streamAgentChat.ts.

Set to None to disable stagnation detection entirely (useful in tests that return a fixed LLM response across many iterations).

prune_keep_tool_messages: 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.

prune_keep_tail_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.

Implementations

impl AgentConfig

pub fn from_user_params( max_iterations: Option<usize>, max_parallel_tools: Option<usize>, tool_timeout_ms: Option<u64>, ) -> Result<Self, AgentConfigError>

Build an AgentConfig from user-supplied overrides.

Each Some 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 both HTTP and CLI callers, eliminating duplicated clamping logic at every call site.

Errors

Returns Err(AgentConfigError) if the clamped config violates any invariant (defense-in-depth — should never happen given the clamping).

pub const fn validated(self) -> Result<Self, AgentConfigError>

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.

Trait Implementations

impl Clone for AgentConfig

fn clone(&self) -> AgentConfig

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for AgentConfig

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for AgentConfig

fn default() -> Self

Returns the “default value” for a type.

impl Serialize for AgentConfig

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.