Files
archie/internal/domain/curator/runtime.go
T
sam 7fd393492d fix(curator): populate PassInput.Since with the prior pass time
WIRE: docs/prds/session-memory-curator.md specifies that each pass finds
"sessions with activity since the last pass", and its effectiveSince rule
treats a zero Since as "the runtime declining to name a horizon" (24h
fallback for the first pass). The runtime is the only production constructor
of PassInput and already carries lastPass, so it must name the horizon at the
producer by setting Since to the prior pass time. Previously Since was never
set, so the session curator fell back to now-24h on every pass and re-read
the same window each chat turn.
2026-09-15 12:48:38 +10:00

343 lines
9.8 KiB
Go

package curator
import (
"context"
"errors"
"fmt"
"sync"
"time"
"github.com/samcharles93/archie-core/internal/events"
)
const (
defaultPassTimeout = 10 * time.Minute
defaultWakeBuffer = 64
// minPassGap is the minimum time between the end of one pass and the
// start of the next. It exists so a curator that suggests a past or
// immediate NextCheckIn cannot hot-spin the loop; nudges still wake a
// loop early, so pending input is never delayed by it.
minPassGap = time.Second
)
// RuntimeConfig tunes the curator runtime. All fields are optional; zero
// values use the documented defaults.
type RuntimeConfig struct {
// PassTimeout bounds a single pass via context deadline. Zero uses
// defaultPassTimeout (10m).
PassTimeout time.Duration
// MaxConcurrentPasses caps simultaneous passes across all curators.
// Zero uses 1: passes serialize behind a shared slot so a pass burst
// can never saturate the model runtime against chat turns.
MaxConcurrentPasses int
}
// Runtime runs the registered curators' loops: one goroutine per curator,
// timing driven by the registry's clock (fake-clock testable), waking on
// best-effort nudges (the trigger decision belongs to the curator's Check),
// with per-pass timeouts, panic recovery, and bounded shutdown.
//
// Curators are peers, never dependencies: nothing a curator does — a
// blocking pass, a panic, a burst of nudges — can block a chat turn, an
// agent run, or the daemon. Wake events are accelerations; the trigger is a
// deterministic state read at pass time (archie-core-035), so a dropped
// nudge only delays a run to the next check-in.
type Runtime struct {
registry *Registry
cfg RuntimeConfig
mu sync.Mutex
started bool
cancel context.CancelFunc
wg sync.WaitGroup
nudges map[string]chan struct{}
sem chan struct{}
}
// NewRuntime builds a runtime over the registry. The runtime shares the
// registry's clock (so loop timing is fake-clock testable) and event sink
// (so every run and action stays attributable).
func NewRuntime(registry *Registry, cfg RuntimeConfig) *Runtime {
if cfg.PassTimeout <= 0 {
cfg.PassTimeout = defaultPassTimeout
}
if cfg.MaxConcurrentPasses <= 0 {
cfg.MaxConcurrentPasses = 1
}
return &Runtime{
registry: registry,
cfg: cfg,
nudges: make(map[string]chan struct{}),
sem: make(chan struct{}, cfg.MaxConcurrentPasses),
}
}
// Start launches one loop per registered curator and starts the curators'
// lifecycle. A curator whose Start fails is skipped by the registry and
// reported in the joined error; every other curator still runs. Starting an
// already-started runtime is an error.
func (rt *Runtime) Start(ctx context.Context) error {
rt.mu.Lock()
if rt.started {
rt.mu.Unlock()
return errors.New("curator runtime already started")
}
rt.started = true
loopCtx, cancel := context.WithCancel(ctx)
rt.cancel = cancel
for _, name := range rt.registry.Names() {
c, _ := rt.registry.Get(name)
if c.Manifest().OnInput {
rt.nudges[name] = make(chan struct{}, defaultWakeBuffer)
}
}
rt.mu.Unlock()
startErr := rt.registry.Start(ctx)
if log := rt.registry.Host().Log; log != nil {
if startErr != nil {
log.Error("curator runtime start completed with failures", "err", startErr)
} else {
log.Info("curator runtime started", "curators", len(rt.registry.Names()))
}
}
for _, name := range rt.registry.Names() {
c, _ := rt.registry.Get(name)
rt.wg.Add(1)
go rt.runLoop(loopCtx, name, c)
}
return startErr
}
// Nudge is a best-effort wake: input-driven curators check their trigger
// early instead of waiting for the next interval. A full channel or an
// unknown name drops the nudge — waking is an acceleration, never the
// source of truth. An empty curator name nudges every input-driven curator.
func (rt *Runtime) Nudge(curator string) {
rt.mu.Lock()
defer rt.mu.Unlock()
for name, ch := range rt.nudges {
if curator != "" && curator != name {
continue
}
select {
case ch <- struct{}{}:
default:
}
}
}
// Stop cancels every loop, waits for in-flight passes to unwind (bounded by
// ctx), then stops the curators' lifecycle in reverse registration order.
// A pass that ignores cancellation cannot hang shutdown beyond ctx: Stop
// returns ctx.Err once the deadline passes. Stopping a runtime that never
// started is a no-op.
func (rt *Runtime) Stop(ctx context.Context) error {
rt.mu.Lock()
if !rt.started {
rt.mu.Unlock()
return nil
}
rt.started = false
cancel := rt.cancel
rt.cancel = nil
rt.mu.Unlock()
cancel()
done := make(chan struct{})
go func() {
rt.wg.Wait()
close(done)
}()
select {
case <-done:
case <-ctx.Done():
if log := rt.registry.Host().Log; log != nil {
log.Error("curator runtime shutdown timed out", "err", ctx.Err())
}
return fmt.Errorf("curator runtime shutdown: %w", ctx.Err())
}
err := rt.registry.Stop(ctx)
if log := rt.registry.Host().Log; log != nil {
if err != nil {
log.Error("curator runtime stopped with failures", "err", err)
} else {
log.Info("curator runtime stopped")
}
}
return err
}
// runLoop is one curator's lifetime: sleep until eligible or nudged, ask
// Check whether input is pending, run a bounded pass when it is, and back
// off to the cooldown after an idle or failed pass. Panics in Check and
// Pass are recovered here; the loop survives them.
func (rt *Runtime) runLoop(ctx context.Context, name string, c CuratorEngine) {
defer rt.wg.Done()
m := c.Manifest()
cooldown := m.Cooldown
if cooldown <= 0 {
cooldown = 2 * m.Interval
}
clock := rt.registry.Host().Clock
wakeCh := rt.nudges[name] // nil for non-input curators: the case never fires
var next time.Time // zero means immediately eligible
var lastPass time.Time
for {
now := clock.Now()
reason := "check-in"
if !next.IsZero() && now.Before(next) {
woke, done := waitNext(ctx, wakeCh, clock.After(next.Sub(now)))
if done {
return
}
if woke {
reason = "wake"
}
}
due, err := rt.safeCheck(ctx, c)
if err != nil {
rt.fail(name, "check", err)
next = clock.Now().Add(cooldown)
continue
}
if !due {
next = clock.Now().Add(m.Interval)
continue
}
if !rt.acquire(ctx) {
return // shutting down while waiting for a pass slot
}
passCtx, cancel := context.WithTimeout(ctx, rt.cfg.PassTimeout)
result, perr := rt.safePass(passCtx, c, PassInput{Reason: reason, Since: lastPass, LastPass: lastPass})
cancel()
rt.release()
now = clock.Now()
lastPass = now
if perr != nil {
rt.fail(name, "pass", perr)
next = now.Add(cooldown)
} else {
next = scheduleNext(now, m, cooldown, result)
rt.emitRun(name, now, result)
}
}
}
// waitNext blocks until a nudge, the sleep timer, or shutdown. woke means
// a nudge fired — re-check the trigger now; done means the context was
// cancelled — exit the loop.
func waitNext(ctx context.Context, wakeCh <-chan struct{}, timer <-chan time.Time) (woke, done bool) {
select {
case <-ctx.Done():
return false, true
case <-wakeCh:
return true, false
case <-timer:
return false, false
}
}
// scheduleNext computes the next eligible time after a successful pass. A
// curator-suggested NextCheckIn in the past (or immediate) would hot-spin
// the loop, so it is clamped to the minimum pass gap; an idle pass (no
// actions) backs off to the cooldown.
func scheduleNext(now time.Time, m Manifest, cooldown time.Duration, result PassResult) time.Time {
switch {
case !result.NextCheckIn.IsZero():
next := result.NextCheckIn
if earliest := now.Add(minPassGap); next.Before(earliest) {
next = earliest
}
return next
case len(result.Actions) == 0:
return now.Add(cooldown)
default:
return now.Add(m.Interval)
}
}
func (rt *Runtime) acquire(ctx context.Context) bool {
select {
case rt.sem <- struct{}{}:
return true
case <-ctx.Done():
return false
}
}
func (rt *Runtime) release() { <-rt.sem }
func (rt *Runtime) safeCheck(ctx context.Context, c CuratorEngine) (due bool, err error) {
defer func() {
if p := recover(); p != nil {
err = fmt.Errorf("check panic: %v", p)
}
}()
return c.Check(ctx)
}
func (rt *Runtime) safePass(ctx context.Context, c CuratorEngine, in PassInput) (result PassResult, err error) {
defer func() {
if p := recover(); p != nil {
err = fmt.Errorf("pass panic: %v", p)
}
}()
return c.Pass(ctx, in)
}
// fail records a Check/Pass failure on the event stream. The event bus is
// non-blocking by contract (bounded dropping buffers), so even a failing
// curator cannot backpressure anything.
func (rt *Runtime) fail(name, phase string, err error) {
if log := rt.registry.Host().Log; log != nil {
log.Error("curator failed", "curator", name, "phase", phase, "err", err)
}
if sink := rt.registry.Host().Events; sink != nil {
sink.Emit(events.KindCuratorError, name, map[string]any{
"curator": name,
"phase": phase,
"err": err.Error(),
})
}
}
// emitRun publishes one run summary plus one event per action, so what ran,
// when, what it changed, and why all stay attributable (archie-core-114).
func (rt *Runtime) emitRun(name string, at time.Time, result PassResult) {
rt.registry.RecordActivity(name, at, result.Actions)
host := rt.registry.Host()
if log := host.Log; log != nil {
log.Info("curator pass completed", "curator", name, "actions", len(result.Actions), "at", at)
for _, a := range result.Actions {
log.Info("curator action", "curator", name, "type", a.Type, "detail", a.Detail, "reason", a.Reason, "at", a.At)
}
}
sink := host.Events
if sink == nil {
return
}
sink.Emit(events.KindCuratorRun, name, map[string]any{
"curator": name,
"actions": len(result.Actions),
"at": at,
})
for _, a := range result.Actions {
sink.Emit(events.KindCuratorAction, name, map[string]any{
"curator": name,
"type": a.Type,
"detail": a.Detail,
"reason": a.Reason,
"at": a.At,
})
}
}