Documentation
¶
Overview ¶
Package breathgate provides turn pacing, pause control, debounce, and cooldown mechanisms for autonomous agent loops.
In multi-turn agent execution, runaway loops can rapidly exhaust API rate limits, deplete token spend, or cause destructive thrashing. A breath gate introduces deliberate breathing room between autonomous operations, enforcing minimum intervals, bounded jitter to avoid thundering-herd synchronization, and automatic or explicit cooldown periods.
All methods on Gate are safe for concurrent use across multiple goroutines.
Index ¶
- type Config
- type Gate
- func (g *Gate) Check() bool
- func (g *Gate) Config() Config
- func (g *Gate) RecordTurn()
- func (g *Gate) Remaining() time.Duration
- func (g *Gate) Reset()
- func (g *Gate) Stats() Stats
- func (g *Gate) TriggerCooldown()
- func (g *Gate) TriggerCooldownFor(d time.Duration)
- func (g *Gate) Wait(ctx context.Context) error
- type Stats
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// MinInterval is the minimum pause required between consecutive turns.
// If non-positive, no pacing interval is enforced between turns.
MinInterval time.Duration
// MaxInterval is the upper bound for jittered or adaptive pacing intervals.
// If non-positive or less than MinInterval, MinInterval is treated as the ceiling.
MaxInterval time.Duration
// Cooldown is the duration of an enforced pause when a burst limit is exceeded
// or an explicit cooldown is requested.
Cooldown time.Duration
// Jitter is a scaling coefficient in the range [0.0, 1.0] used to add
// pseudo-random variance to pacing intervals, preventing thundering herds.
// A value of 0.10 adds up to 10% additional random delay to MinInterval.
Jitter float64
// BurstLimit is the maximum number of rapid turns allowed within a burst window
// before triggering an automatic Cooldown. If non-positive, burst detection is disabled.
BurstLimit int
// BurstWindow is the maximum elapsed duration between turns to be considered
// consecutive for burst limit tracking. If non-positive, defaults to
// 2 * max(MinInterval, MaxInterval).
BurstWindow time.Duration
// Clock is an optional custom time provider (defaults to time.Now if nil).
Clock func() time.Time
// RNG is an optional pseudo-random generator returning a float64 in [0.0, 1.0).
// Defaults to rand.Float64 if nil.
RNG func() float64
// Sleep is an optional context-aware sleeper function (defaults to timer-based wait if nil).
Sleep func(ctx context.Context, d time.Duration) error
}
Config specifies pacing intervals, jitter factor, and cooldown behavior for a Gate.
func DefaultConfig ¶
func DefaultConfig() Config
DefaultConfig returns a recommended production configuration with sensible pacing defaults: 100ms minimum interval, 500ms max interval, 5s cooldown, 10% jitter, and a burst limit of 20 turns.
type Gate ¶
type Gate struct {
// contains filtered or unexported fields
}
Gate manages pacing intervals, pause control, debounce, and cooldowns. It enforces minimum breathing intervals between autonomous tool turns, serializes rapid bursts, and protects against runaway thrashing loops. All methods on Gate are safe for concurrent use across multiple goroutines.
func New ¶
New constructs a new Gate with the provided Config. Negative intervals and out-of-range jitter factors are automatically sanitized to safe bounds.
func (*Gate) Check ¶
Check reports whether the gate is ready to admit the next turn immediately without waiting. It returns true if both the pacing interval and any active cooldown have elapsed. Check does not block and does not modify turn counters.
func (*Gate) RecordTurn ¶
func (g *Gate) RecordTurn()
RecordTurn logs the completion of a turn, updating timestamps and evaluating burst limits. If the number of rapid consecutive turns meets or exceeds BurstLimit, an automatic Cooldown is triggered.
func (*Gate) Remaining ¶
Remaining returns the duration until the gate will be ready to admit the next turn. Returns 0 if the gate is ready immediately.
func (*Gate) Reset ¶
func (g *Gate) Reset()
Reset clears all cooldowns, pacing reservations, and consecutive turn counters, immediately restoring the gate to its initial ready state.
func (*Gate) Stats ¶
Stats returns an atomic snapshot of current gate metrics and operational status.
func (*Gate) TriggerCooldown ¶
func (g *Gate) TriggerCooldown()
TriggerCooldown forces the gate into an active cooldown state for the duration configured in Config.Cooldown.
func (*Gate) TriggerCooldownFor ¶
TriggerCooldownFor forces the gate into an active cooldown state for the specified duration. Useful when handling external API rate limit responses such as HTTP 429 Retry-After headers.
func (*Gate) Wait ¶
Wait blocks until the required pacing interval and any active cooldown period have elapsed, or until the provided Context is canceled. Concurrent callers are serialized and scheduled in FIFO order to prevent thundering herds.
Returns nil on successful wait or immediate admission, or ctx.Err() if canceled.
type Stats ¶
type Stats struct {
// TotalTurns is the cumulative number of turns recorded by the gate.
TotalTurns int64
// ThrottledTurns is the count of turns that experienced a non-zero wait delay.
ThrottledTurns int64
// CooldownCount is the number of times the gate has entered a cooldown state.
CooldownCount int64
// TotalWaitTime is the cumulative time callers spent waiting in Wait.
TotalWaitTime time.Duration
// LastTurn is the timestamp when the most recent turn was recorded.
LastTurn time.Time
// InCooldown indicates whether the gate is actively in a cooldown period.
InCooldown bool
// ConsecutiveTurns is the current run of consecutive turns within the burst window.
ConsecutiveTurns int
}
Stats holds an immutable snapshot of operational metrics for a Gate.
Source Files