Files
archie/internal/tools/availability.go
T
sam 8356863712 feat: Tools P1 — guardrails, classification, budget, availability, disclosure, dispatch
- 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
2026-07-26 09:53:38 +10:00

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)
}