diff --git a/cmd/archied/main.go b/cmd/archied/main.go index 80de669c5..39362c7b1 100644 --- a/cmd/archied/main.go +++ b/cmd/archied/main.go @@ -29,6 +29,7 @@ import ( "github.com/samcharles93/archie-core/internal/channels/webhook" "github.com/samcharles93/archie-core/internal/config" "github.com/samcharles93/archie-core/internal/container" + "github.com/samcharles93/archie-core/internal/curator" "github.com/samcharles93/archie-core/internal/daemon" "github.com/samcharles93/archie-core/internal/domain/workintake" "github.com/samcharles93/archie-core/internal/events" @@ -639,6 +640,38 @@ func run() int { }() log.Info("memory manager started", "dir", memDir) + // ── Curator engine family ──────────────────────────────────────── + // The registry owns curator registration, lifecycle and shutdown + // ordering. The runtime loop (archie-core-89x) and the reference + // curators (archie-core-i7i, gs8) are wired by their issues; until + // then the registry is empty and Stop is a no-op. The event sink + // rides the in-process bus, whose bounded dropping per-subscriber + // buffers guarantee curator activity can never backpressure the + // daemon or a chat turn. + curatorRegistry := curator.NewRegistry(curator.Registrar{ + Events: curatorEventSink{bus}, + }) + // The runtime owns the per-curator loops (archie-core-89x): one + // goroutine per curator, wake nudges, per-pass budgets, panic + // recovery, bounded shutdown. Stop order at shutdown: runtime first + // (cancels in-flight passes, then stops curator lifecycle), then the + // registry's own Stop below, which is a no-op by then. + curatorRuntime := curator.NewRuntime(curatorRegistry, curator.RuntimeConfig{}) + defer func() { + stopCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + if err := curatorRuntime.Stop(stopCtx); err != nil { + log.Error("curator runtime shutdown", "err", err) + } + }() + defer func() { + stopCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + if err := curatorRegistry.Stop(stopCtx); err != nil { + log.Error("curator registry shutdown", "err", err) + } + }() + // ── Guardrail engine ─────────────────────────────────────────────── gc := tools.DefaultGuardrailConfig() guardrails := tools.NewGuardrailEngine(gc) @@ -722,6 +755,7 @@ func run() int { Memory: memManager, Guardrails: guardrails, ToolRegistry: toolReg, + Curators: curatorRegistry, Identities: identityRunners, } @@ -753,6 +787,9 @@ func run() int { log.Error("startup", "err", err) return 1 } + if err := curatorRuntime.Start(ctx); err != nil { + log.Error("curator runtime startup", "err", err) + } for _, startGateway := range startGateways { startGateway() } @@ -769,6 +806,18 @@ func run() int { return 0 } +// curatorEventSink adapts the in-process event bus to the curator family's +// narrow emission contract. Bus publish is non-blocking with bounded, +// dropping per-subscriber buffers, so curator activity can never +// backpressure the daemon or a chat turn. +type curatorEventSink struct { + b *events.Bus +} + +func (s curatorEventSink) Emit(kind, detail string, data map[string]any) { + s.b.Publish(events.Event{Kind: kind, Detail: detail, Data: data}) +} + type chatTaskWriterAdapter struct { enqueue func( ctx context.Context, diff --git a/docs/architecture/plugins-and-extensions.md b/docs/architecture/plugins-and-extensions.md index 19bb7f2df..ad6e647e3 100644 --- a/docs/architecture/plugins-and-extensions.md +++ b/docs/architecture/plugins-and-extensions.md @@ -40,3 +40,34 @@ A plugin: Plugins may be internally cohesive like small services. They do not become network services without a concrete security or operational reason. + +## Curator surprisal sampling (deferred) + +The curator engine family (epic `archie-core-yp9`) selects which memories +deserve agentic attention via surprisal-based sampling: score memories by how +surprising they are and spend the sampled reasoner's agentic budget on the +most surprising items. Wave 1 of the epic ships the `Sampler` strategy seam in +`internal/curator` with cheap, embedding-free strategies (recency, random, +all, and a staleness proxy). The embedding-backed strategy is a documented +extension point and is gated behind an embedding capability Archie does not +yet have — **any surprisal-style sampling is gated behind adding one**. + +Requirements for the deferred work, so it can be picked up without +re-deriving the design (tracked as `archie-core-yp9.1` embeddings capability, +then `archie-core-yp9.2` surprisal strategies): + +- A `Sampler` implementation behind the same interface as the cheap + strategies; selection deterministic given fixed inputs. +- Algorithm: sample up to a candidate cap; build a k-NN graph over embedding + vectors; row-normalize the adjacency with self-loops; power-iterate to the + stationary distribution; surprisal = −log(stationary probability of the + nearest point); select the highest-surprisal items. +- Degradation: content without an embedding is skipped; an embedding failure + aborts sampling and falls back to free exploration — a sampling failure + must never fail or crash a curator pass. +- Cost bound: the graph build is quadratic in the candidate cap; the cap must + be a named constant with a documented bound. +- The embedding capability itself: a narrow typed client usable by in-process + components, config-driven provider/model, credential-missing degrades to + "capability unavailable" (daemon still starts), timeouts on network calls, + tests via httptest only. diff --git a/internal/curator/contract.go b/internal/curator/contract.go new file mode 100644 index 000000000..aa211d04d --- /dev/null +++ b/internal/curator/contract.go @@ -0,0 +1,147 @@ +// Package curator is the curator engine family: long-running agent loops +// that reason over memory and perform small maintenance tasks, rather than +// one hardcoded background job. See epic archie-core-yp9. +// +// A curator is defined by a declared shape (check-in interval, tool set, +// attached memory engine), runs persistently while there is input, and backs +// off to a cooldown when idle. The family follows the strict plugin engine +// rule: a typed contract (CuratorEngine), an owning registry (Registry) with +// start/health/stop and shutdown ordering, and narrow typed host access +// (Registrar) — a curator never receives the daemon or an untyped hook map. +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 (archie-core-035). + 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 (skill curator, + // archie-core-i7i). 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 (archie-core-pek). Empty means the curator does not + // use memory; a memory operation without a declared engine is + // rejected. + MemoryEngine string + // 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 +// (archie-core-114). +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 +} diff --git a/internal/curator/contract_test.go b/internal/curator/contract_test.go new file mode 100644 index 000000000..f0577f02c --- /dev/null +++ b/internal/curator/contract_test.go @@ -0,0 +1,72 @@ +package curator + +import ( + "testing" + "time" +) + +func TestManifestValidate(t *testing.T) { + t.Parallel() + + tests := []struct { + name string + manifest Manifest + wantErr bool + }{ + { + name: "valid minimal", + manifest: Manifest{Interval: time.Hour}, + }, + { + name: "valid full", + manifest: Manifest{ + Interval: time.Hour, + Cooldown: time.Minute, + OnInput: true, + Tools: []string{"skills.list", "skills.write"}, + Skills: true, + MemoryEngine: "builtin", + Model: "provider/model", + }, + }, + { + name: "zero interval", + manifest: Manifest{}, + wantErr: true, + }, + { + name: "negative interval", + manifest: Manifest{Interval: -time.Hour}, + wantErr: true, + }, + { + name: "empty tool name", + manifest: Manifest{Interval: time.Hour, Tools: []string{""}}, + wantErr: true, + }, + { + name: "blank tool name", + manifest: Manifest{Interval: time.Hour, Tools: []string{" "}}, + wantErr: true, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + t.Parallel() + err := tt.manifest.Validate() + if (err != nil) != tt.wantErr { + t.Fatalf("Validate() error = %v, wantErr %v", err, tt.wantErr) + } + }) + } +} + +func TestManifestValidateRejectsDuplicateTools(t *testing.T) { + t.Parallel() + + m := Manifest{Interval: time.Hour, Tools: []string{"skills.list", "skills.list"}} + if err := m.Validate(); err != nil { + t.Fatalf("Validate() = %v, want nil (duplicates are the builder's problem)", err) + } +} diff --git a/internal/curator/registrar.go b/internal/curator/registrar.go new file mode 100644 index 000000000..b9ebc899b --- /dev/null +++ b/internal/curator/registrar.go @@ -0,0 +1,113 @@ +package curator + +import ( + "context" + "time" + + "github.com/samcharles93/archie-core/internal/tools" +) + +// Registrar is the narrow typed host access a curator receives at +// registration. Only the services the curator's declared shape requires are +// ever populated in the view the registry binds (see Registry.filter); the +// daemon itself is never part of it. Fields are typed contracts declared +// here — this package never names who implements them. +type Registrar struct { + // Model is the default model reference ("provider/model") for + // curators whose manifest leaves Model empty. + Model string + // LLM provides model access for agentic passes. Bound when the curator + // declares an agentic capability (tools, skills, or a memory engine). + LLM LLMRunner + // Tools resolves the declared tool names into a runnable tool set. + // Resolution is the enforcement point: a pass receives exactly the + // declared set, never a broader registry. Bound when tools are + // declared. + Tools ToolBuilder + // Skills is the skill-maintenance capability (skill curator, + // archie-core-i7i). Bound when the curator declares Skills. + Skills SkillStore + // Events publishes curator activity. Implementations must be + // non-blocking and bounded (drop on overflow), so a curator can never + // apply backpressure to a chat turn or the daemon. Always bound. + Events EventSink + // Clock is injectable time. Always bound; nil at construction is + // replaced with the system clock. + Clock Clock +} + +// LLMRunner is the model access a curator needs for a pass. The app layer +// adapts the shared runtime to this narrow contract. +type LLMRunner interface { + Chat(ctx context.Context, req ChatRequest) (ChatResult, error) +} + +// ChatRequest is one model call: messages plus the runnable tool set. +type ChatRequest struct { + Model string + Messages []Message + Tools []tools.ToolEntry + MaxSteps int +} + +// Message is one conversation message. +type Message struct { + Role string // e.g. "system", "user", "assistant", "tool" + Content string +} + +// ChatResult is the model's final answer. +type ChatResult struct { + Text string +} + +// ToolBuilder resolves declared tool names into a runnable tool set. A +// declared name with no implementation fails the pass rather than silently +// running with fewer tools, and no tool outside the declared set is +// returned. +type ToolBuilder interface { + Build(ctx context.Context, declared []string) ([]tools.ToolEntry, error) +} + +// SkillStore is the skill-maintenance capability. The implementation owns +// the on-disk format and catalog reload rules (archie-core-i7i). +type SkillStore interface { + List(ctx context.Context) ([]SkillRef, error) + Read(ctx context.Context, name string) (Skill, error) + Write(ctx context.Context, s Skill) error + Delete(ctx context.Context, name string) error +} + +// SkillRef identifies one skill on disk. +type SkillRef struct { + Name string + Path string +} + +// Skill is one skill definition. +type Skill struct { + Name string + Content string + Description string +} + +// EventSink publishes curator activity (what ran, what changed, why). It is +// the emission side only; wake signals arrive through the runtime's own +// subscription (archie-core-89x). Implementations MUST be non-blocking and +// bounded, matching the in-process event bus semantics. +type EventSink interface { + Emit(kind, detail string, data map[string]any) +} + +// Clock is injectable time: Now for timestamps and After for loop sleeps. +// The runtime's loop timing is tested with a fake clock, never wall-clock +// sleeps (archie-core-89x); the real implementation is the system clock. +type Clock interface { + Now() time.Time + After(d time.Duration) <-chan time.Time +} + +type systemClock struct{} + +func (systemClock) Now() time.Time { return time.Now() } +func (systemClock) After(d time.Duration) <-chan time.Time { return time.After(d) } diff --git a/internal/curator/registry.go b/internal/curator/registry.go new file mode 100644 index 000000000..0496528f9 --- /dev/null +++ b/internal/curator/registry.go @@ -0,0 +1,287 @@ +package curator + +import ( + "context" + "errors" + "fmt" + "reflect" + "slices" + "sync" +) + +// Registry errors. +var ( + // ErrDuplicate is returned when a curator name is already registered. + ErrDuplicate = errors.New("duplicate curator") + // ErrStarted is returned when registration or lifecycle is attempted + // after the registry has started. + ErrStarted = errors.New("curator registry already started") +) + +type registryState uint8 + +const ( + stateIdle registryState = iota + stateRunning + stateStopped +) + +type curatorStatus struct { + started bool + startErr error +} + +// Registry is the curator family owner: it controls registration and +// discovery, lifecycle (start/health/stop), shutdown ordering, and failure +// isolation. A curator failure — a rejected registration, a failing Start, a +// blocking Stop, even a panicking Bind — affects only that curator and is +// reported, never fatal to the daemon or to other curators. +type Registry struct { + mu sync.Mutex + host Registrar + curators map[string]CuratorEngine + status map[string]curatorStatus + order []string + state registryState +} + +// NewRegistry builds the family registry. A nil Clock is replaced with the +// system clock; every other nil service is valid until a curator declares +// the capability that requires it. +func NewRegistry(host Registrar) *Registry { + if host.Clock == nil { + host.Clock = systemClock{} + } + return &Registry{ + host: host, + curators: make(map[string]CuratorEngine), + status: make(map[string]curatorStatus), + } +} + +// Register validates the curator's declared shape against the registrar and +// adds it, binding the curator to a host view filtered to its declared +// capabilities. Registration fails on nil engines, invalid manifests, +// duplicate names, a declared capability with no host service behind it, or +// a panicking Bind — and a failure affects only that curator. +func (r *Registry) Register(c CuratorEngine) error { + if isNilEngine(c) { + return errors.New("curator: nil engine") + } + m := c.Manifest() + if err := m.Validate(); err != nil { + return err + } + if err := r.validateDeclared(m); err != nil { + return err + } + + r.mu.Lock() + defer r.mu.Unlock() + if r.state != stateIdle { + return ErrStarted + } + if _, dup := r.curators[c.Name()]; dup { + return fmt.Errorf("%w: %s", ErrDuplicate, c.Name()) + } + if err := bindSafely(c, r.filter(m)); err != nil { + return err + } + r.curators[c.Name()] = c + r.order = append(r.order, c.Name()) + return nil +} + +// validateDeclared enforces "only the host services a curator's declared +// shape requires": a declared capability must have a host service behind it. +// A curator can never discover the daemon or an untyped hook map here — the +// registrar is the only channel. +func (r *Registry) validateDeclared(m Manifest) error { + if len(m.Tools) > 0 && r.host.Tools == nil { + return errors.New("curator manifest: declares tools but the registrar has no ToolBuilder") + } + if m.Skills && r.host.Skills == nil { + return errors.New("curator manifest: declares the skills capability but the registrar has no SkillStore") + } + return nil +} + +// filter returns the registrar view narrowed to the curator's declared +// capabilities. Events and Clock are always present (activity must stay +// attributable and time is universal); model access is present only for +// agentic curators; every capability service is present only when declared. +func (r *Registry) filter(m Manifest) Registrar { + v := r.host + if !agentic(m) { + v.LLM = nil + } + if len(m.Tools) == 0 { + v.Tools = nil + } + if !m.Skills { + v.Skills = nil + } + return v +} + +func agentic(m Manifest) bool { + return len(m.Tools) > 0 || m.Skills || m.MemoryEngine != "" +} + +// bindSafely isolates a panicking Bind: a curator that panics while +// receiving its host access is refused without taking the registry down. +func bindSafely(c CuratorEngine, host Registrar) (err error) { + defer func() { + if p := recover(); p != nil { + err = fmt.Errorf("curator %s: bind panic: %v", c.Name(), p) + } + }() + c.Bind(host) + return nil +} + +// Host returns the raw registrar bundle the registry was built with — the +// shared services (events, clock, model) the runtime and future surfaces +// use. It is narrow typed; the daemon itself is never part of it. +func (r *Registry) Host() Registrar { + r.mu.Lock() + defer r.mu.Unlock() + return r.host +} + +// Get returns the registered curator by name. +func (r *Registry) Get(name string) (CuratorEngine, bool) { + r.mu.Lock() + defer r.mu.Unlock() + c, ok := r.curators[name] + return c, ok +} + +// Names returns the registered curator names in sorted order. +func (r *Registry) Names() []string { + r.mu.Lock() + defer r.mu.Unlock() + names := make([]string, 0, len(r.curators)) + for name := range r.curators { + names = append(names, name) + } + slices.Sort(names) + return names +} + +// Start starts every registered curator in registration order. A curator +// whose Start fails (error or panic) is marked unhealthy and skipped; the +// rest start regardless, and all failures are joined into the returned +// error. This is the family's failure-isolation boundary for lifecycle. +func (r *Registry) Start(ctx context.Context) error { + r.mu.Lock() + if r.state != stateIdle { + r.mu.Unlock() + return ErrStarted + } + r.state = stateRunning + order := slices.Clone(r.order) + r.mu.Unlock() + + var errs []error + for _, name := range order { + c := r.curators[name] + err := startSafely(ctx, c) + r.mu.Lock() + if err != nil { + r.status[name] = curatorStatus{startErr: err} + errs = append(errs, fmt.Errorf("curator %s: %w", name, err)) + } else { + r.status[name] = curatorStatus{started: true} + } + r.mu.Unlock() + } + return errors.Join(errs...) +} + +func startSafely(ctx context.Context, c CuratorEngine) (err error) { + defer func() { + if p := recover(); p != nil { + err = fmt.Errorf("start panic: %v", p) + } + }() + return c.Start(ctx) +} + +// Health reports every registered curator's health. A curator whose Start +// failed is reported unhealthy with the failure; otherwise the curator's own +// Health is used. A panicking Health is reported unhealthy, not propagated. +func (r *Registry) Health(ctx context.Context) map[string]Health { + r.mu.Lock() + defer r.mu.Unlock() + out := make(map[string]Health, len(r.curators)) + for name, c := range r.curators { + if st, ok := r.status[name]; ok && st.startErr != nil { + out[name] = Health{Status: HealthUnhealthy, Message: st.startErr.Error()} + continue + } + out[name] = healthSafely(ctx, c) + } + return out +} + +func healthSafely(ctx context.Context, c CuratorEngine) (h Health) { + defer func() { + if p := recover(); p != nil { + h = Health{Status: HealthUnhealthy, Message: fmt.Sprintf("health panic: %v", p)} + } + }() + return c.Health(ctx) +} + +// Stop stops every started curator in reverse registration order. Curators +// whose Start failed are skipped; the call is bounded by ctx — a curator +// that ignores cancellation cannot hang the daemon's shutdown beyond the +// caller's deadline, and its error is joined into the result. Stopping a +// registry that never started is a no-op. +func (r *Registry) Stop(ctx context.Context) error { + r.mu.Lock() + if r.state == stateIdle || r.state == stateStopped { + r.mu.Unlock() + return nil + } + r.state = stateStopped + order := slices.Clone(r.order) + r.mu.Unlock() + + var errs []error + for i := len(order) - 1; i >= 0; i-- { + name := order[i] + r.mu.Lock() + st, ok := r.status[name] + r.mu.Unlock() + if !ok || !st.started { + continue + } + c := r.curators[name] + if err := stopSafely(ctx, c); err != nil { + errs = append(errs, fmt.Errorf("curator %s: %w", name, err)) + } + } + return errors.Join(errs...) +} + +func stopSafely(ctx context.Context, c CuratorEngine) (err error) { + defer func() { + if p := recover(); p != nil { + err = fmt.Errorf("stop panic: %v", p) + } + }() + return c.Stop(ctx) +} + +func isNilEngine(c CuratorEngine) bool { + v := reflect.ValueOf(c) + switch v.Kind() { + case reflect.Invalid: + return true + case reflect.Chan, reflect.Func, reflect.Interface, reflect.Map, reflect.Pointer, reflect.Slice: + return v.IsNil() + } + return false +} diff --git a/internal/curator/registry_test.go b/internal/curator/registry_test.go new file mode 100644 index 000000000..44e5ad936 --- /dev/null +++ b/internal/curator/registry_test.go @@ -0,0 +1,577 @@ +package curator + +import ( + "context" + "errors" + "slices" + "sync" + "sync/atomic" + "testing" + "time" + + "github.com/samcharles93/archie-core/internal/tools" +) + +// --- host-service fakes ----------------------------------------------------- + +type testLLM struct{ calls int } + +func (l *testLLM) Chat(_ context.Context, _ ChatRequest) (ChatResult, error) { + l.calls++ + return ChatResult{Text: "ok"}, nil +} + +type testBuilder struct{ built [][]string } + +func (b *testBuilder) Build(_ context.Context, declared []string) ([]tools.ToolEntry, error) { + b.built = append(b.built, declared) + return nil, nil +} + +type testStore struct{} + +func (testStore) List(context.Context) ([]SkillRef, error) { return nil, nil } +func (testStore) Read(context.Context, string) (Skill, error) { return Skill{}, nil } +func (testStore) Write(context.Context, Skill) error { return nil } +func (testStore) Delete(context.Context, string) error { return nil } + +type testSink struct { + mu sync.Mutex + kinds []string +} + +func (s *testSink) Emit(kind, _ string, _ map[string]any) { + s.mu.Lock() + defer s.mu.Unlock() + s.kinds = append(s.kinds, kind) +} + +func (s *testSink) kindsOf() []string { + s.mu.Lock() + defer s.mu.Unlock() + return slices.Clone(s.kinds) +} + +func (s *testSink) count(kind string) int { + n := 0 + for _, k := range s.kindsOf() { + if k == kind { + n++ + } + } + return n +} + +type testClock struct{ now time.Time } + +func (c testClock) Now() time.Time { return c.now } +func (c testClock) After(d time.Duration) <-chan time.Time { + return time.After(d) +} + +// --- fake curator ------------------------------------------------------------ + +type fakeCurator struct { + name string + manifest Manifest + events []string + recorder *[]string // shared lifecycle log; nil means record to events + startErr error + stopErr error + stopBlock chan struct{} + bindPanic bool + view Registrar + + // pass/check control (runtime tests). + checkResult bool + checkErr error + checkPanic bool + checkCalls atomic.Int32 + passResult PassResult + passErr error + passPanic bool + passBlock chan struct{} // if set, Pass blocks until closed or ctx done + passIgnoreCtx bool // if true, Pass ignores ctx while blocked + passCalls atomic.Int32 + inputMu sync.Mutex + inputs []PassInput +} + +func newFake(name string, manifest Manifest) *fakeCurator { + return &fakeCurator{name: name, manifest: manifest} +} + +func (f *fakeCurator) record(e string) { + if f.recorder != nil { + *f.recorder = append(*f.recorder, e) + } else { + f.events = append(f.events, e) + } +} + +func (f *fakeCurator) Name() string { return f.name } +func (f *fakeCurator) Version() string { return "test" } +func (f *fakeCurator) Manifest() Manifest { return f.manifest } +func (f *fakeCurator) Bind(host Registrar) { + f.view = host + f.record("bind:" + f.name) + if f.bindPanic { + panic("bind boom") + } +} + +func (f *fakeCurator) Check(context.Context) (bool, error) { + f.checkCalls.Add(1) + if f.checkPanic { + panic("check boom") + } + if f.checkErr != nil { + return false, f.checkErr + } + return f.checkResult, nil +} + +func (f *fakeCurator) Pass(ctx context.Context, in PassInput) (PassResult, error) { + f.passCalls.Add(1) + f.inputMu.Lock() + f.inputs = append(f.inputs, in) + f.inputMu.Unlock() + if f.passPanic { + panic("pass boom") + } + if f.passBlock != nil { + if f.passIgnoreCtx { + <-f.passBlock + } else { + select { + case <-f.passBlock: + case <-ctx.Done(): + return PassResult{}, ctx.Err() + } + } + } + if f.passErr != nil { + return PassResult{}, f.passErr + } + return f.passResult, nil +} + +func (f *fakeCurator) Start(context.Context) error { + if f.startErr != nil { + return f.startErr + } + f.record("start:" + f.name) + return nil +} + +func (f *fakeCurator) Health(context.Context) Health { return Health{Status: HealthHealthy} } + +func (f *fakeCurator) Stop(ctx context.Context) error { + if f.stopBlock != nil { + select { + case <-f.stopBlock: + case <-ctx.Done(): + return ctx.Err() + } + } + if f.stopErr != nil { + return f.stopErr + } + f.record("stop:" + f.name) + return nil +} + +// --- registry behavior ------------------------------------------------------- + +func TestRegistryRegisterAndDiscover(t *testing.T) { + t.Parallel() + + r := NewRegistry(Registrar{}) + a := newFake("a", Manifest{Interval: time.Hour}) + b := newFake("b", Manifest{Interval: time.Hour}) + if err := r.Register(a); err != nil { + t.Fatalf("Register(a) = %v, want nil", err) + } + if err := r.Register(b); err != nil { + t.Fatalf("Register(b) = %v, want nil", err) + } + + got, ok := r.Get("a") + if !ok || got != a { + t.Fatalf("Get(a) = (%v, %v), want (a, true)", got, ok) + } + if _, ok := r.Get("missing"); ok { + t.Fatal("Get(missing) = true, want false") + } + + if got := r.Names(); len(got) != 2 || got[0] != "a" || got[1] != "b" { + t.Fatalf("Names() = %v, want [a b]", got) + } +} + +func TestRegistryRegisterDuplicateRejected(t *testing.T) { + t.Parallel() + + r := NewRegistry(Registrar{}) + a := newFake("a", Manifest{Interval: time.Hour}) + if err := r.Register(a); err != nil { + t.Fatalf("Register(a) = %v, want nil", err) + } + err := r.Register(newFake("a", Manifest{Interval: time.Hour})) + if !errors.Is(err, ErrDuplicate) { + t.Fatalf("Register(dup) = %v, want ErrDuplicate", err) + } + if got := r.Names(); len(got) != 1 { + t.Fatalf("Names() = %v, want only the first registration", got) + } +} + +func TestRegistryRegisterNilEngineRejected(t *testing.T) { + t.Parallel() + + r := NewRegistry(Registrar{}) + if err := r.Register(nil); err == nil { + t.Fatal("Register(nil) = nil, want error") + } +} + +func TestRegistryRegisterTypedNilEngineRejected(t *testing.T) { + t.Parallel() + + r := NewRegistry(Registrar{}) + var c *fakeCurator + if err := r.Register(c); err == nil { + t.Fatal("Register(typed nil) = nil, want error") + } +} + +func TestRegistryRegisterInvalidManifestRejected(t *testing.T) { + t.Parallel() + + r := NewRegistry(Registrar{}) + if err := r.Register(newFake("bad", Manifest{})); err == nil { + t.Fatal("Register(zero interval) = nil, want error") + } + if got := r.Names(); len(got) != 0 { + t.Fatalf("Names() = %v, want empty after rejected registration", got) + } +} + +func TestRegistryRegisterAfterStartRejected(t *testing.T) { + t.Parallel() + + r := NewRegistry(Registrar{}) + if err := r.Register(newFake("a", Manifest{Interval: time.Hour})); err != nil { + t.Fatalf("Register(a) = %v, want nil", err) + } + if err := r.Start(context.Background()); err != nil { + t.Fatalf("Start() = %v, want nil", err) + } + err := r.Register(newFake("b", Manifest{Interval: time.Hour})) + if !errors.Is(err, ErrStarted) { + t.Fatalf("Register after Start = %v, want ErrStarted", err) + } +} + +func TestRegistryDeclaredCapabilitiesRequireHostServices(t *testing.T) { + t.Parallel() + + tests := []struct { + name string + host Registrar + manifest Manifest + wantErr bool + }{ + { + name: "tools declared, no builder", + host: Registrar{}, + manifest: Manifest{Interval: time.Hour, Tools: []string{"skills.list"}}, + wantErr: true, + }, + { + name: "tools declared, builder present", + host: Registrar{Tools: &testBuilder{}}, + manifest: Manifest{Interval: time.Hour, Tools: []string{"skills.list"}}, + }, + { + name: "skills declared, no store", + host: Registrar{}, + manifest: Manifest{Interval: time.Hour, Skills: true}, + wantErr: true, + }, + { + name: "skills declared, store present", + host: Registrar{Skills: testStore{}}, + manifest: Manifest{Interval: time.Hour, Skills: true}, + }, + { + name: "nothing declared, empty host", + host: Registrar{}, + manifest: Manifest{Interval: time.Hour}, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + t.Parallel() + r := NewRegistry(tt.host) + err := r.Register(newFake("c", tt.manifest)) + if (err != nil) != tt.wantErr { + t.Fatalf("Register() = %v, wantErr %v", err, tt.wantErr) + } + }) + } +} + +func TestRegistryBindFiltersToDeclaredCapabilities(t *testing.T) { + t.Parallel() + + host := Registrar{ + Model: "provider/default", + LLM: &testLLM{}, + Tools: &testBuilder{}, + Skills: testStore{}, + Events: &testSink{}, + Clock: testClock{now: time.Unix(0, 0)}, + } + + // A curator declaring nothing agentic receives no model access and no + // capability services, but always receives events and time. + r := NewRegistry(host) + plain := newFake("plain", Manifest{Interval: time.Hour}) + if err := r.Register(plain); err != nil { + t.Fatalf("Register(plain) = %v, want nil", err) + } + if plain.view.LLM != nil { + t.Error("view.LLM = non-nil for a curator declaring no agentic capability") + } + if plain.view.Tools != nil { + t.Error("view.Tools = non-nil for a curator declaring no tools") + } + if plain.view.Skills != nil { + t.Error("view.Skills = non-nil for a curator not declaring skills") + } + if plain.view.Events == nil { + t.Error("view.Events = nil; activity must always be attributable") + } + if plain.view.Clock == nil { + t.Error("view.Clock = nil; time is always available") + } + + // A curator declaring tools and skills receives exactly those, plus the + // model access an agentic pass needs. + toolsy := newFake("toolsy", Manifest{Interval: time.Hour, Tools: []string{"skills.list"}, Skills: true}) + if err := r.Register(toolsy); err != nil { + t.Fatalf("Register(toolsy) = %v, want nil", err) + } + if toolsy.view.LLM == nil { + t.Error("view.LLM = nil for a curator declaring agentic capabilities") + } + if toolsy.view.Tools == nil { + t.Error("view.Tools = nil for a curator declaring tools") + } + if toolsy.view.Skills == nil { + t.Error("view.Skills = nil for a curator declaring skills") + } + + // A curator declaring only a memory engine still needs model access to + // reason over memory. + mem := newFake("mem", Manifest{Interval: time.Hour, MemoryEngine: "builtin"}) + if err := r.Register(mem); err != nil { + t.Fatalf("Register(mem) = %v, want nil", err) + } + if mem.view.LLM == nil { + t.Error("view.LLM = nil for a curator declaring a memory engine") + } + if mem.view.Tools != nil { + t.Error("view.Tools = non-nil for a curator declaring no tools") + } +} + +func TestRegistryBindPanicIsolated(t *testing.T) { + t.Parallel() + + r := NewRegistry(Registrar{}) + panicky := newFake("panicky", Manifest{Interval: time.Hour}) + panicky.bindPanic = true + if err := r.Register(panicky); err == nil { + t.Fatal("Register(panicking Bind) = nil, want error") + } + if got := r.Names(); len(got) != 0 { + t.Fatalf("Names() = %v, want empty after a panicking Bind", got) + } + + // The registry survives and still accepts healthy curators. + if err := r.Register(newFake("ok", Manifest{Interval: time.Hour})); err != nil { + t.Fatalf("Register(ok) after panicking Bind = %v, want nil", err) + } +} + +func TestRegistryStartStopOrdering(t *testing.T) { + t.Parallel() + + r := NewRegistry(Registrar{}) + var log []string + a := newFake("a", Manifest{Interval: time.Hour}) + a.recorder = &log + b := newFake("b", Manifest{Interval: time.Hour}) + b.recorder = &log + c := newFake("c", Manifest{Interval: time.Hour}) + c.recorder = &log + for _, cur := range []*fakeCurator{a, b, c} { + if err := r.Register(cur); err != nil { + t.Fatalf("Register(%s) = %v, want nil", cur.name, err) + } + } + + if err := r.Start(context.Background()); err != nil { + t.Fatalf("Start() = %v, want nil", err) + } + if err := r.Stop(context.Background()); err != nil { + t.Fatalf("Stop() = %v, want nil", err) + } + + want := []string{ + "bind:a", "bind:b", "bind:c", + "start:a", "start:b", "start:c", + "stop:c", "stop:b", "stop:a", + } + if got := log; !equalStrings(got, want) { + t.Fatalf("lifecycle events = %v, want %v (start in registration order, stop reversed)", got, want) + } +} + +func TestRegistryStartIsolatesFailure(t *testing.T) { + t.Parallel() + + r := NewRegistry(Registrar{}) + var log []string + a := newFake("a", Manifest{Interval: time.Hour}) + a.recorder = &log + bad := newFake("bad", Manifest{Interval: time.Hour}) + bad.recorder = &log + bad.startErr = errBoom + c := newFake("c", Manifest{Interval: time.Hour}) + c.recorder = &log + for _, cur := range []*fakeCurator{a, bad, c} { + if err := r.Register(cur); err != nil { + t.Fatalf("Register(%s) = %v, want nil", cur.name, err) + return + } + } + + err := r.Start(context.Background()) + if !errors.Is(err, errBoom) { + t.Fatalf("Start() error = %v, want the failing curator's error", err) + } + + // The healthy curators started; the failing one never became started. + if !logHas(log, "start:a") || !logHas(log, "start:c") { + t.Fatalf("healthy curators did not start: %v", log) + } + if logHas(log, "start:bad") { + t.Fatalf("failing curator started despite Start error: %v", log) + } + + health := r.Health(context.Background()) + if health["bad"].Status != HealthUnhealthy { + t.Fatalf("Health(bad).Status = %v, want unhealthy", health["bad"].Status) + } + if health["a"].Status != HealthHealthy { + t.Fatalf("Health(a).Status = %v, want healthy", health["a"].Status) + } + + // Stop skips the curator that never started and stops the rest in + // reverse registration order. + if err := r.Stop(context.Background()); err != nil { + t.Fatalf("Stop() = %v, want nil", err) + } + want := []string{"bind:a", "bind:bad", "bind:c", "start:a", "start:c", "stop:c", "stop:a"} + if got := log; !equalStrings(got, want) { + t.Fatalf("lifecycle events = %v, want %v", got, want) + } +} + +func TestRegistryStopBoundedByContext(t *testing.T) { + t.Parallel() + + r := NewRegistry(Registrar{}) + blocked := newFake("blocked", Manifest{Interval: time.Hour}) + blocked.stopBlock = make(chan struct{}) + if err := r.Register(blocked); err != nil { + t.Fatalf("Register(blocked) = %v, want nil", err) + } + if err := r.Start(context.Background()); err != nil { + t.Fatalf("Start() = %v, want nil", err) + } + + ctx, cancel := context.WithTimeout(context.Background(), 20*time.Millisecond) + defer cancel() + start := time.Now() + err := r.Stop(ctx) + elapsed := time.Since(start) + + if !errors.Is(err, context.DeadlineExceeded) { + t.Fatalf("Stop() error = %v, want context.DeadlineExceeded", err) + } + if elapsed > 2*time.Second { + t.Fatalf("Stop() took %v; a blocking curator must not hang shutdown", elapsed) + } +} + +func TestRegistryStopBeforeStartIsNoop(t *testing.T) { + t.Parallel() + + r := NewRegistry(Registrar{}) + if err := r.Register(newFake("a", Manifest{Interval: time.Hour})); err != nil { + t.Fatalf("Register(a) = %v, want nil", err) + } + if err := r.Stop(context.Background()); err != nil { + t.Fatalf("Stop() before Start = %v, want nil no-op", err) + } +} + +func TestRegistryStartTwiceRejected(t *testing.T) { + t.Parallel() + + r := NewRegistry(Registrar{}) + if err := r.Start(context.Background()); err != nil { + t.Fatalf("Start() = %v, want nil", err) + } + if err := r.Start(context.Background()); !errors.Is(err, ErrStarted) { + t.Fatalf("second Start() = %v, want ErrStarted", err) + } +} + +func TestRegistryHealthReportsEveryCurator(t *testing.T) { + t.Parallel() + + r := NewRegistry(Registrar{}) + if err := r.Register(newFake("a", Manifest{Interval: time.Hour})); err != nil { + t.Fatalf("Register(a) = %v, want nil", err) + } + health := r.Health(context.Background()) + if len(health) != 1 || health["a"].Status != HealthHealthy { + t.Fatalf("Health() = %v, want one healthy entry for a", health) + } +} + +// --- helpers ----------------------------------------------------------------- + +var errBoom = errors.New("boom") + +func equalStrings(a, b []string) bool { + if len(a) != len(b) { + return false + } + for i := range a { + if a[i] != b[i] { + return false + } + } + return true +} + +func logHas(log []string, want string) bool { + return slices.Contains(log, want) +} diff --git a/internal/curator/runtime.go b/internal/curator/runtime.go new file mode 100644 index 000000000..a91882be2 --- /dev/null +++ b/internal/curator/runtime.go @@ -0,0 +1,311 @@ +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) + 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(): + return fmt.Errorf("curator runtime shutdown: %w", ctx.Err()) + } + return rt.registry.Stop(ctx) +} + +// 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, 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 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) { + sink := rt.registry.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, + }) + } +} diff --git a/internal/curator/runtime_test.go b/internal/curator/runtime_test.go new file mode 100644 index 000000000..db8e95970 --- /dev/null +++ b/internal/curator/runtime_test.go @@ -0,0 +1,455 @@ +package curator + +import ( + "context" + "errors" + "slices" + "sync" + "testing" + "time" + + "github.com/samcharles93/archie-core/internal/events" +) + +// --- fake clock --------------------------------------------------------------- + +// fakeClock is the runtime's injectable clock: Now plus clock-driven timers +// that fire when Advance moves past their deadline. Loop timing is tested +// with this, never wall-clock sleeps. +type fakeClock struct { + mu sync.Mutex + now time.Time + timers []*fakeTimer +} + +type fakeTimer struct { + c chan time.Time + at time.Time +} + +func newFakeClock(start time.Time) *fakeClock { return &fakeClock{now: start} } + +func (fc *fakeClock) Now() time.Time { + fc.mu.Lock() + defer fc.mu.Unlock() + return fc.now +} + +func (fc *fakeClock) After(d time.Duration) <-chan time.Time { + fc.mu.Lock() + defer fc.mu.Unlock() + t := &fakeTimer{c: make(chan time.Time, 1), at: fc.now.Add(d)} + fc.timers = append(fc.timers, t) + return t.c +} + +// Advance moves the clock forward and fires every timer whose deadline has +// passed, returning how many fired. +func (fc *fakeClock) Advance(d time.Duration) int { + fc.mu.Lock() + fc.now = fc.now.Add(d) + var fired []*fakeTimer + remain := fc.timers[:0] + for _, t := range fc.timers { + if !t.at.After(fc.now) { + fired = append(fired, t) + } else { + remain = append(remain, t) + } + } + fc.timers = remain + fc.mu.Unlock() + for _, t := range fired { + select { + case t.c <- t.at: + default: + } + } + return len(fired) +} + +// --- helpers ------------------------------------------------------------------ + +func waitFor(t *testing.T, timeout time.Duration, what string, cond func() bool) { + t.Helper() + deadline := time.Now().Add(timeout) + for time.Now().Before(deadline) { + if cond() { + return + } + time.Sleep(time.Millisecond) + } + t.Fatalf("timed out waiting for %s", what) +} + +func newRuntimeTestEnv(t *testing.T, clock Clock, cfg RuntimeConfig, curators ...*fakeCurator) (*Registry, *Runtime, *testSink) { + t.Helper() + sink := &testSink{} + reg := NewRegistry(Registrar{Clock: clock, Events: sink}) + for _, c := range curators { + if err := reg.Register(c); err != nil { + t.Fatalf("Register(%s) = %v, want nil", c.name, err) + } + } + return reg, NewRuntime(reg, cfg), sink +} + +const testInterval = 10 * time.Minute + +// --- loop behavior ------------------------------------------------------------- + +func TestRuntimeWakeRunsPendingPassImmediately(t *testing.T) { + t.Parallel() + + clock := newFakeClock(time.Unix(0, 0)) + c := newFake("c", Manifest{Interval: testInterval, OnInput: true}) + c.checkResult = true + c.passResult = PassResult{Actions: []Action{{Type: "test", Reason: "r"}}} + _, rt, _ := newRuntimeTestEnv(t, clock, RuntimeConfig{}, c) + + if err := rt.Start(context.Background()); err != nil { + t.Fatalf("Start() = %v, want nil", err) + } + t.Cleanup(func() { _ = rt.Stop(context.Background()) }) + + // Pending input at start: the first pass runs without any clock advance. + waitFor(t, 2*time.Second, "first pass", func() bool { return c.passCalls.Load() == 1 }) + + // A nudge before the next interval wakes the curator early: a second + // pass runs without advancing the clock past the interval. + rt.Nudge("c") + waitFor(t, 2*time.Second, "pass on nudge", func() bool { return c.passCalls.Load() == 2 }) + if got := clock.Now(); got.After(time.Unix(0, 0).Add(testInterval)) { + t.Fatalf("clock advanced to %v; wake must not wait for the interval", got) + } +} + +func TestRuntimeIdleCuratorSleepsUntilInterval(t *testing.T) { + t.Parallel() + + clock := newFakeClock(time.Unix(0, 0)) + c := newFake("c", Manifest{Interval: testInterval}) + c.checkResult = false // nothing pending + _, rt, _ := newRuntimeTestEnv(t, clock, RuntimeConfig{}, c) + + if err := rt.Start(context.Background()); err != nil { + t.Fatalf("Start() = %v, want nil", err) + } + t.Cleanup(func() { _ = rt.Stop(context.Background()) }) + + // Initial check only; nothing due before the interval. + waitFor(t, 2*time.Second, "initial check", func() bool { return c.checkCalls.Load() >= 1 }) + if c.passCalls.Load() != 0 { + t.Fatalf("passCalls = %d, want 0 while idle", c.passCalls.Load()) + } + + clock.Advance(testInterval - time.Second) + time.Sleep(50 * time.Millisecond) + if got := c.checkCalls.Load(); got != 1 { + t.Fatalf("checkCalls = %d after %v, want 1 (idle curator must not wake early)", got, testInterval-time.Second) + } + + clock.Advance(time.Second) + waitFor(t, 2*time.Second, "check at interval", func() bool { return c.checkCalls.Load() >= 2 }) + if c.passCalls.Load() != 0 { + t.Fatalf("passCalls = %d, want 0 (Check said nothing pending)", c.passCalls.Load()) + } +} + +func TestRuntimeCooldownAfterIdlePass(t *testing.T) { + t.Parallel() + + clock := newFakeClock(time.Unix(0, 0)) + c := newFake("c", Manifest{Interval: testInterval, Cooldown: 30 * time.Minute}) + c.checkResult = true + c.passResult = PassResult{} // no actions: the pass was idle + _, rt, _ := newRuntimeTestEnv(t, clock, RuntimeConfig{}, c) + + if err := rt.Start(context.Background()); err != nil { + t.Fatalf("Start() = %v, want nil", err) + } + t.Cleanup(func() { _ = rt.Stop(context.Background()) }) + + waitFor(t, 2*time.Second, "idle pass", func() bool { return c.passCalls.Load() == 1 }) + + // The cooldown (30m) outranks the interval (10m): nothing runs at + // +10m... + clock.Advance(testInterval) + time.Sleep(50 * time.Millisecond) + if got := c.checkCalls.Load(); got != 1 { + t.Fatalf("checkCalls = %d at +interval, want 1 (cooldown must apply after an idle pass)", got) + } + // ...and the next pass runs at +30m. + clock.Advance(20 * time.Minute) + waitFor(t, 2*time.Second, "pass after cooldown", func() bool { return c.passCalls.Load() == 2 }) +} + +func TestRuntimeNextCheckInOverride(t *testing.T) { + t.Parallel() + + clock := newFakeClock(time.Unix(0, 0)) + c := newFake("c", Manifest{Interval: testInterval}) + c.checkResult = true + c.passResult = PassResult{NextCheckIn: time.Unix(0, 0).Add(5 * time.Minute)} + _, rt, _ := newRuntimeTestEnv(t, clock, RuntimeConfig{}, c) + + if err := rt.Start(context.Background()); err != nil { + t.Fatalf("Start() = %v, want nil", err) + } + t.Cleanup(func() { _ = rt.Stop(context.Background()) }) + + waitFor(t, 2*time.Second, "first pass", func() bool { return c.passCalls.Load() == 1 }) + + // The pass suggested +5m; neither the 10m interval nor anything else + // fires before it. + clock.Advance(4 * time.Minute) + time.Sleep(50 * time.Millisecond) + if got := c.checkCalls.Load(); got != 1 { + t.Fatalf("checkCalls = %d before NextCheckIn, want 1", got) + } + clock.Advance(time.Minute) + waitFor(t, 2*time.Second, "pass at NextCheckIn", func() bool { return c.passCalls.Load() == 2 }) + + // The second pass suggests the same absolute time, now in the past. + // The runtime clamps it to the minimum gap instead of hot-spinning. + clock.Advance(500 * time.Millisecond) + time.Sleep(50 * time.Millisecond) + if got := c.passCalls.Load(); got != 2 { + t.Fatalf("passCalls = %d before the clamp gap elapses, want 2 (past NextCheckIn must not hot-spin)", got) + } + clock.Advance(500 * time.Millisecond) + waitFor(t, 2*time.Second, "pass after clamp gap", func() bool { return c.passCalls.Load() == 3 }) + if got := c.checkCalls.Load(); got > 10 { + t.Fatalf("checkCalls = %d; a clamped NextCheckIn must not produce a check burst", got) + } +} + +func TestRuntimeNudgeIgnoredForNonInputCurator(t *testing.T) { + t.Parallel() + + clock := newFakeClock(time.Unix(0, 0)) + c := newFake("c", Manifest{Interval: testInterval}) // OnInput false + c.checkResult = true + _, rt, _ := newRuntimeTestEnv(t, clock, RuntimeConfig{}, c) + + if err := rt.Start(context.Background()); err != nil { + t.Fatalf("Start() = %v, want nil", err) + } + t.Cleanup(func() { _ = rt.Stop(context.Background()) }) + + waitFor(t, 2*time.Second, "first pass", func() bool { return c.passCalls.Load() == 1 }) + + rt.Nudge("c") + time.Sleep(50 * time.Millisecond) + if got := c.passCalls.Load(); got != 1 { + t.Fatalf("passCalls = %d after nudge, want 1 (non-input curator ignores nudges)", got) + } + + // A nudge for an unknown curator is dropped without panicking. + rt.Nudge("missing") +} + +func TestRuntimePassPanicRecovered(t *testing.T) { + t.Parallel() + + clock := newFakeClock(time.Unix(0, 0)) + c := newFake("c", Manifest{Interval: testInterval, Cooldown: 5 * time.Minute}) + c.checkResult = true + c.passPanic = true + _, rt, sink := newRuntimeTestEnv(t, clock, RuntimeConfig{}, c) + + if err := rt.Start(context.Background()); err != nil { + t.Fatalf("Start() = %v, want nil", err) + } + t.Cleanup(func() { _ = rt.Stop(context.Background()) }) + + waitFor(t, 2*time.Second, "panicking pass", func() bool { return c.passCalls.Load() == 1 }) + waitFor(t, 2*time.Second, "error event", func() bool { return sink.count(events.KindCuratorError) >= 1 }) + + // The loop survives the panic: the next check-in still happens. + clock.Advance(5 * time.Minute) + waitFor(t, 2*time.Second, "pass after panic", func() bool { return c.passCalls.Load() == 2 }) +} + +func TestRuntimeCheckPanicRecovered(t *testing.T) { + t.Parallel() + + clock := newFakeClock(time.Unix(0, 0)) + c := newFake("c", Manifest{Interval: testInterval, Cooldown: 5 * time.Minute}) + c.checkPanic = true + _, rt, sink := newRuntimeTestEnv(t, clock, RuntimeConfig{}, c) + + if err := rt.Start(context.Background()); err != nil { + t.Fatalf("Start() = %v, want nil", err) + } + t.Cleanup(func() { _ = rt.Stop(context.Background()) }) + + waitFor(t, 2*time.Second, "error event", func() bool { return sink.count(events.KindCuratorError) >= 1 }) + clock.Advance(5 * time.Minute) + waitFor(t, 2*time.Second, "check after panic", func() bool { return c.checkCalls.Load() >= 2 }) +} + +func TestRuntimeShutdownCancelsInFlightPass(t *testing.T) { + t.Parallel() + + clock := newFakeClock(time.Unix(0, 0)) + c := newFake("c", Manifest{Interval: testInterval}) + c.checkResult = true + c.passBlock = make(chan struct{}) + _, rt, _ := newRuntimeTestEnv(t, clock, RuntimeConfig{}, c) + + if err := rt.Start(context.Background()); err != nil { + t.Fatalf("Start() = %v, want nil", err) + } + waitFor(t, 2*time.Second, "blocked pass", func() bool { return c.passCalls.Load() == 1 }) + + stopCtx, cancel := context.WithTimeout(context.Background(), 2*time.Second) + defer cancel() + start := time.Now() + if err := rt.Stop(stopCtx); err != nil { + t.Fatalf("Stop() = %v, want nil (in-flight pass must be cancelled via context)", err) + } + if elapsed := time.Since(start); elapsed > 2*time.Second { + t.Fatalf("Stop() took %v; shutdown must be bounded", elapsed) + } +} + +func TestRuntimeShutdownBoundedDespiteStuckPass(t *testing.T) { + t.Parallel() + + clock := newFakeClock(time.Unix(0, 0)) + c := newFake("c", Manifest{Interval: testInterval}) + c.checkResult = true + c.passBlock = make(chan struct{}) + c.passIgnoreCtx = true // violates the contract on purpose: Pass ignores ctx + _, rt, _ := newRuntimeTestEnv(t, clock, RuntimeConfig{}, c) + + if err := rt.Start(context.Background()); err != nil { + t.Fatalf("Start() = %v, want nil", err) + } + waitFor(t, 2*time.Second, "stuck pass", func() bool { return c.passCalls.Load() == 1 }) + t.Cleanup(func() { close(c.passBlock) }) // unstick the goroutine at test end + + stopCtx, cancel := context.WithTimeout(context.Background(), 30*time.Millisecond) + defer cancel() + start := time.Now() + err := rt.Stop(stopCtx) + if !errors.Is(err, context.DeadlineExceeded) { + t.Fatalf("Stop() error = %v, want context.DeadlineExceeded", err) + } + if elapsed := time.Since(start); elapsed > 2*time.Second { + t.Fatalf("Stop() took %v; a stuck pass must not hang shutdown", elapsed) + } +} + +func TestRuntimeMaxConcurrentPasses(t *testing.T) { + t.Parallel() + + clock := newFakeClock(time.Unix(0, 0)) + a := newFake("a", Manifest{Interval: testInterval, OnInput: true}) + a.checkResult = true + a.passBlock = make(chan struct{}) + b := newFake("b", Manifest{Interval: testInterval, OnInput: true}) + b.checkResult = true + _, rt, _ := newRuntimeTestEnv(t, clock, RuntimeConfig{MaxConcurrentPasses: 1}, a, b) + + if err := rt.Start(context.Background()); err != nil { + t.Fatalf("Start() = %v, want nil", err) + } + closed := false + t.Cleanup(func() { + if !closed { + close(a.passBlock) + } + _ = rt.Stop(context.Background()) + }) + + // a holds the single pass slot, blocked. + waitFor(t, 2*time.Second, "a's blocked pass", func() bool { return a.passCalls.Load() == 1 }) + + // b is woken, but the slot is taken: b's pass count cannot advance + // past its initial run while a is in flight. + before := b.passCalls.Load() + for i := 0; i < 5; i++ { + rt.Nudge("b") + } + time.Sleep(100 * time.Millisecond) + if got := b.passCalls.Load(); got != before { + t.Fatalf("b.passCalls = %d while a is blocked (was %d); max concurrent passes = 1", got, before) + } + + // a finishes; b's queued pass runs. + close(a.passBlock) + closed = true + waitFor(t, 2*time.Second, "b's pass after slot freed", func() bool { + return b.passCalls.Load() > before + }) +} + +func TestRuntimeEmitsRunAndActionEvents(t *testing.T) { + t.Parallel() + + clock := newFakeClock(time.Unix(0, 0)) + c := newFake("c", Manifest{Interval: testInterval}) + c.checkResult = true + c.passResult = PassResult{Actions: []Action{ + {Type: "skill.updated", Detail: "d1", Reason: "stale"}, + {Type: "skill.pruned", Detail: "d2", Reason: "unused"}, + }} + _, rt, sink := newRuntimeTestEnv(t, clock, RuntimeConfig{}, c) + + if err := rt.Start(context.Background()); err != nil { + t.Fatalf("Start() = %v, want nil", err) + } + t.Cleanup(func() { _ = rt.Stop(context.Background()) }) + + waitFor(t, 2*time.Second, "run event", func() bool { return sink.count(events.KindCuratorRun) == 1 }) + waitFor(t, 2*time.Second, "action events", func() bool { return sink.count(events.KindCuratorAction) == 2 }) +} + +func TestRuntimeLifecycleGuards(t *testing.T) { + t.Parallel() + + clock := newFakeClock(time.Unix(0, 0)) + _, rt, _ := newRuntimeTestEnv(t, clock, RuntimeConfig{}) + + if err := rt.Stop(context.Background()); err != nil { + t.Fatalf("Stop() before Start = %v, want nil no-op", err) + } + if err := rt.Start(context.Background()); err != nil { + t.Fatalf("Start() = %v, want nil", err) + } + t.Cleanup(func() { _ = rt.Stop(context.Background()) }) + if err := rt.Start(context.Background()); err == nil { + t.Fatal("second Start() = nil, want error") + } +} + +func TestRuntimePassInputRecordsReasonAndLastPass(t *testing.T) { + t.Parallel() + + clock := newFakeClock(time.Unix(0, 0)) + c := newFake("c", Manifest{Interval: testInterval, OnInput: true}) + c.checkResult = true + _, rt, _ := newRuntimeTestEnv(t, clock, RuntimeConfig{}, c) + + if err := rt.Start(context.Background()); err != nil { + t.Fatalf("Start() = %v, want nil", err) + } + t.Cleanup(func() { _ = rt.Stop(context.Background()) }) + + waitFor(t, 2*time.Second, "first pass", func() bool { return c.passCalls.Load() == 1 }) + + rt.Nudge("c") + waitFor(t, 2*time.Second, "nudged pass", func() bool { return c.passCalls.Load() == 2 }) + + c.inputMu.Lock() + inputs := slices.Clone(c.inputs) + c.inputMu.Unlock() + if len(inputs) != 2 { + t.Fatalf("pass inputs = %d, want 2", len(inputs)) + } + if inputs[1].LastPass.IsZero() { + t.Error("second pass LastPass is zero; want the previous pass time") + } +} diff --git a/internal/daemon/daemon.go b/internal/daemon/daemon.go index a1eac41a7..fd9e2c739 100644 --- a/internal/daemon/daemon.go +++ b/internal/daemon/daemon.go @@ -17,6 +17,7 @@ import ( "github.com/samcharles93/archie-core/internal/agentexec" "github.com/samcharles93/archie-core/internal/config" "github.com/samcharles93/archie-core/internal/container" + "github.com/samcharles93/archie-core/internal/curator" "github.com/samcharles93/archie-core/internal/domain/workintake" "github.com/samcharles93/archie-core/internal/eventbus" "github.com/samcharles93/archie-core/internal/events" @@ -92,6 +93,10 @@ type Daemon struct { // composition root (cmd/archied) to wfeval.Discover; nil disables // discovery. CustomStages func(dir string) ([]workflow.Stage, error) + // Curators is the curator engine family registry (epic archie-core-yp9). + // The runtime loop (archie-core-89x) and reference curators (i7i, gs8) + // are driven through it; nil when the family is not composed. + Curators *curator.Registry // Identities holds per-identity runner state for multi-identity mode. // When non-empty, Run() starts one goroutine per identity instead of // using the single-identity Forge/Trees/Cfg.Repos path. diff --git a/internal/events/events.go b/internal/events/events.go index c9f4e3951..9f226f571 100644 --- a/internal/events/events.go +++ b/internal/events/events.go @@ -29,6 +29,13 @@ const ( KindHumanRejected = "human_rejected" KindTaskRetried = "task_retried" KindLog = "log" // data: level, msg + + // Curator family activity (epic archie-core-yp9). Curator runs ride + // the same bus so background agents mutating memory stay observable: + // what ran, when, what changed, and why (archie-core-114). + KindCuratorRun = "curator_run" // data: curator, actions, at + KindCuratorAction = "curator_action" // data: curator, type, detail, reason + KindCuratorError = "curator_error" // data: curator, phase, err ) // Event is the single wire type: task lifecycle, stage progress, agent