Struct LoopGuard 

pub struct LoopGuard { /* private fields */ }

Sliding-window detector for repeated tool calls.

The guard keeps the last window (tool_name, args) records in a FIFO ring. On every LoopGuard::record, if the new key already appears threshold times (including the call being recorded) in the buffer, LoopDetectedError is returned. The new call is still recorded so repeated calls to record after a detection stay deterministic.

Use LoopGuard::would_raise to peek at the next decision without mutating the buffer.

Implementations

impl LoopGuard

pub fn with_capacity(window: usize, threshold: usize) -> Self

Construct a guard.

Panics

Panics on invalid construction (matches the spirit of Python’s ValueError, but in Rust idiom we treat invalid construction as a programming bug rather than a recoverable error):

• window < 2
• threshold < 2
• threshold > window

If you want a non-panicking constructor, see LoopGuard::try_new.

pub fn try_new(window: usize, threshold: usize) -> Result<Self, ConfigError>

Fallible constructor. Returns Err(ConfigError) instead of panicking.

pub fn with_key_fn<F>(window: usize, threshold: usize, key_fn: F) -> Self

where F: Fn(&str, &Value) -> Key + Send + Sync + 'static,

Construct a guard with a custom key function.

The key function decides which calls should be considered “the same”. Two calls that produce equal Keys count toward the threshold. Use this to ignore noisy fields like request_id or timestamp that change every call but don’t represent real intent.

pub fn window(&self) -> usize

Configured window size.

pub fn threshold(&self) -> usize

Configured threshold.

pub fn len(&self) -> usize

Number of calls currently in the buffer.

pub fn is_empty(&self) -> bool

True if no calls have been recorded since construction or last reset.

pub fn recent_keys(&self) -> Vec<&Key>

Recent keys, oldest first.

Returned as borrowed references so callers do not pay an allocation cost just to inspect the ring. Clone individual entries with key.clone() if you need to keep them past the next record call.

pub fn record( &mut self, tool_name: &str, args: &Value, ) -> Result<(), LoopDetectedError>

Record a call. Returns Err(LoopDetectedError) if the threshold is met.

The call is recorded into the ring before the count is checked, so subsequent calls observe the same offending entry until evicted.

pub fn would_raise(&self, tool_name: &str, args: &Value) -> bool

Return true if the next record for this key would raise.

Lets callers preview the outcome without mutating the buffer. The simulation accounts for buffer eviction: if the buffer is already full and the oldest entry has the same key, the projected count loses one before gaining one.

pub fn reset(&mut self)

Forget all recorded calls.

Trait Implementations

impl Debug for LoopGuard

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

Formats the value using the given formatter.