142 lines
5.2 KiB
Go
142 lines
5.2 KiB
Go
// Package curator runs curators: long-running agent loops that maintain
|
|
// memory, each with a declared interval, tool set and memory engine.
|
|
package curator
|
|
|
|
import (
|
|
"context"
|
|
"errors"
|
|
"strings"
|
|
"time"
|
|
)
|
|
|
|
// HealthStatus is a curator's point-in-time health.
|
|
type HealthStatus string
|
|
|
|
const (
|
|
HealthHealthy HealthStatus = "healthy"
|
|
HealthDegraded HealthStatus = "degraded"
|
|
HealthUnhealthy HealthStatus = "unhealthy"
|
|
)
|
|
|
|
// Health is a point-in-time curator health report.
|
|
type Health struct {
|
|
Status HealthStatus
|
|
Message string
|
|
}
|
|
|
|
// Manifest is a curator's declared shape: what input wakes it, how often it
|
|
// runs, which tools it may reach, and which memory engine it uses. The
|
|
// registry validates the manifest at registration, so a curator can never
|
|
// discover capabilities it did not declare.
|
|
type Manifest struct {
|
|
// Interval is the check-in cadence: how often a pass is eligible when
|
|
// there is no pending input. Must be positive.
|
|
Interval time.Duration
|
|
// Cooldown is the backoff after a pass that found nothing to do. Zero
|
|
// lets the runtime pick a multiple of Interval.
|
|
Cooldown time.Duration
|
|
// OnInput marks the curator as input-driven: primary input (e.g. a
|
|
// completed chat turn) wakes it before the next interval. Wake events
|
|
// are best-effort nudges; the trigger decision is a deterministic
|
|
// state read at pass time.
|
|
OnInput bool
|
|
// Tools is the declared tool set: the only tools a pass may reach.
|
|
// Enforcement is mechanical — the pass's tool set is built from this
|
|
// list, never from a broader registry.
|
|
Tools []string
|
|
// Skills declares the skill-maintenance capability. The registrar must
|
|
// carry a SkillStore for a curator that declares it.
|
|
Skills bool
|
|
// MemoryEngine names the attached memory engine once the memory engine
|
|
// family exists. Empty means the curator does not
|
|
// use memory; a memory operation without a declared engine is
|
|
// rejected.
|
|
MemoryEngine string
|
|
// Conversations declares the conversation-history capability.
|
|
// The registrar
|
|
// must carry a ConversationSource for a curator that declares it.
|
|
Conversations bool
|
|
// Model is the model reference ("provider/model") passes use. Empty
|
|
// uses the registrar's default.
|
|
Model string
|
|
}
|
|
|
|
// Validate checks the declared shape. It is called by the registry at
|
|
// registration; a curator with an invalid manifest is refused.
|
|
func (m Manifest) Validate() error {
|
|
if m.Interval <= 0 {
|
|
return errors.New("curator manifest: interval must be positive")
|
|
}
|
|
for _, tool := range m.Tools {
|
|
if strings.TrimSpace(tool) == "" {
|
|
return errors.New("curator manifest: tool names must be non-empty")
|
|
}
|
|
}
|
|
return nil
|
|
}
|
|
|
|
// Lifecycle is the start/health/stop contract every curator implements. The
|
|
// registry drives it with shutdown ordering and failure isolation; a
|
|
// curator's Health must never panic the daemon.
|
|
type Lifecycle interface {
|
|
Start(ctx context.Context) error
|
|
Health(ctx context.Context) Health
|
|
Stop(ctx context.Context) error
|
|
}
|
|
|
|
// CuratorEngine is the typed contract every curator implements. Name/Version
|
|
// are identity, Manifest declares the shape, Check/Pass are the domain
|
|
// operations, Bind receives the narrow host access, and Lifecycle carries
|
|
// start/health/stop.
|
|
type CuratorEngine interface {
|
|
Lifecycle
|
|
Name() string
|
|
Version() string
|
|
Manifest() Manifest
|
|
// Check reports whether a pass should run now. It must be cheap: no
|
|
// model calls, no work a chat turn would wait on. The runtime calls it
|
|
// when deciding whether to run a pass early.
|
|
Check(ctx context.Context) (bool, error)
|
|
// Pass runs one maintenance pass. The runtime guarantees at most one
|
|
// in-flight pass per curator, bounds it with context cancellation and
|
|
// per-pass budgets, and recovers panics so a failing pass never takes
|
|
// down another curator, a chat turn, or the daemon.
|
|
Pass(ctx context.Context, in PassInput) (PassResult, error)
|
|
// Bind attaches the curator's narrow host access. The registry calls
|
|
// Bind exactly once, at registration, with a view filtered to the
|
|
// curator's declared capabilities.
|
|
Bind(host Registrar)
|
|
}
|
|
|
|
// PassInput carries why a pass runs and the input horizon it may consume.
|
|
type PassInput struct {
|
|
// Reason describes why this pass runs (e.g. "20 primary turns since
|
|
// last pass" or "daily check-in"). It is recorded on actions and
|
|
// events so curator activity stays attributable.
|
|
Reason string
|
|
// Since is the input horizon: primary input at or after this time is
|
|
// this pass's material. Zero means the curator decides.
|
|
Since time.Time
|
|
// LastPass is when the previous pass started; zero for the first pass.
|
|
LastPass time.Time
|
|
}
|
|
|
|
// PassResult reports what a pass did. Every action is attributable: the
|
|
// registry emits them as events and they are inspectable at runtime
|
|
type PassResult struct {
|
|
// Actions records what this pass changed and why.
|
|
Actions []Action
|
|
// NextCheckIn lets a pass suggest the next eligible time (e.g. a
|
|
// longer backoff when there was nothing to do). Zero means the
|
|
// runtime uses the manifest interval and cooldown.
|
|
NextCheckIn time.Time
|
|
}
|
|
|
|
// Action records one change a curator made and why.
|
|
type Action struct {
|
|
At time.Time
|
|
Type string // e.g. "skill.updated", "memory.written"
|
|
Detail string // what changed, human-readable
|
|
Reason string // why it happened
|
|
}
|