- ToolCallGuardrailConfig + GuardrailEngine with RecordSuccess/RecordFailure - ToolClassification bitmask (idempotent/mutating) with dispatch gating - TurnBudget for token/char accounting with spill-to-disk - AvailabilityCache with TTL + failure grace window - Progressive disclosure engine for tool schema filtering - Tool dispatch executor with parallel/serial classification - RecordSuccess fix: now returns GuardrailDecision (no-progress threshold) - All tests pass with -race, 58 new test functions across 6 test files
106 lines
3.1 KiB
Go
106 lines
3.1 KiB
Go
package tools
|
|
|
|
import (
|
|
"sync"
|
|
"time"
|
|
)
|
|
|
|
// AvailabilityCache wraps a [CheckFn] with TTL-based result caching.
|
|
//
|
|
// Positive results (tool is available) are cached for the TTL duration.
|
|
// Negative results (tool is unavailable) are cached for the failure
|
|
// grace period. A nil check function means "always available" -- Check
|
|
// returns true immediately with no caching overhead.
|
|
//
|
|
// All methods are safe for concurrent use.
|
|
type AvailabilityCache struct {
|
|
TTL time.Duration
|
|
FailureGracePeriod time.Duration
|
|
|
|
check CheckFn
|
|
|
|
mu sync.Mutex
|
|
lastResult bool
|
|
checkedAt time.Time
|
|
}
|
|
|
|
// NewAvailabilityCache creates an [AvailabilityCache] wrapping the given
|
|
// check function. If check is nil, Check always returns true (the tool
|
|
// is permanently available and no caching is needed).
|
|
//
|
|
// Typical values: TTL=30s for positive results, FailureGracePeriod=60s
|
|
// for negative results (avoid churn when a dependency is temporarily down).
|
|
func NewAvailabilityCache(check CheckFn, ttl, failureGrace time.Duration) *AvailabilityCache {
|
|
return &AvailabilityCache{
|
|
TTL: ttl,
|
|
FailureGracePeriod: failureGrace,
|
|
check: check,
|
|
}
|
|
}
|
|
|
|
// Check reports whether the tool is available. It returns the cached
|
|
// result when the cache is still fresh; otherwise it re-evaluates the
|
|
// underlying check function.
|
|
//
|
|
// When the underlying check returns true (available), the result is
|
|
// cached for c.TTL. When it returns false (unavailable), the result is
|
|
// cached for c.FailureGracePeriod -- this prevents tight re-check loops
|
|
// while a dependency is temporarily down.
|
|
func (c *AvailabilityCache) Check() bool {
|
|
if c.check == nil {
|
|
return true
|
|
}
|
|
|
|
c.mu.Lock()
|
|
defer c.mu.Unlock()
|
|
|
|
now := time.Now()
|
|
cacheDuration := c.TTL
|
|
if !c.lastResult {
|
|
cacheDuration = c.FailureGracePeriod
|
|
}
|
|
|
|
if c.checkedAt.IsZero() || now.Sub(c.checkedAt) >= cacheDuration {
|
|
c.lastResult = c.check()
|
|
c.checkedAt = now
|
|
}
|
|
|
|
return c.lastResult
|
|
}
|
|
|
|
// Invalidate forces the next call to Check to bypass the cache and
|
|
// re-evaluate the underlying check function.
|
|
func (c *AvailabilityCache) Invalidate() {
|
|
c.mu.Lock()
|
|
c.checkedAt = time.Time{}
|
|
c.mu.Unlock()
|
|
}
|
|
|
|
// LastChecked reports when the cache was last refreshed. A zero time
|
|
// means the cache has never been evaluated.
|
|
func (c *AvailabilityCache) LastChecked() time.Time {
|
|
c.mu.Lock()
|
|
defer c.mu.Unlock()
|
|
return c.checkedAt
|
|
}
|
|
|
|
// CachedAvailable returns the most recent cached result without
|
|
// re-evaluating the check function. For tools with a nil check,
|
|
// this always returns true.
|
|
func (c *AvailabilityCache) CachedAvailable() bool {
|
|
if c.check == nil {
|
|
return true
|
|
}
|
|
c.mu.Lock()
|
|
defer c.mu.Unlock()
|
|
return c.lastResult
|
|
}
|
|
|
|
// NewAvailabilityCacheFromEntry is a convenience constructor that creates
|
|
// an [AvailabilityCache] from a [ToolEntry]'s CheckFn using the given TTL
|
|
// and failure grace period. When the entry has a nil CheckFn the returned
|
|
// cache reports always-available.
|
|
func NewAvailabilityCacheFromEntry(e ToolEntry, ttl, failureGrace time.Duration) *AvailabilityCache {
|
|
return NewAvailabilityCache(e.CheckFn, ttl, failureGrace)
|
|
}
|