Files
archie/internal/domain/curator/contract.go
T
sam fc6bffad50 feat(curator): session-memory curator reference implementation
Closes archie-core-1786637499114 (persistent session-memory curator),
the last open item in the curator engine epic.

docs/prds/session-memory-curator.md records the decisions this needed
before coding, most notably: Observation.Identity is the session ID,
not a user or cross-session identity. migration-decisions.md#5's
memory-scope mapping (global/agent-wide/user-wide/agent-user
relationship) is still explicitly open, and this issue has no business
deciding it unilaterally -- session-as-identity is the narrowest
unambiguous scope available today and is forward-compatible with a
later, properly-decided identity resolution.

curator gains ConversationSource (RecentSessions/Messages), gated in
Registry.validateDeclared/filter exactly like Skills/MemoryEngines, plus
Manifest.Conversations. internal/infrastructure/sessioncurator/adapter.go
adapts gateway.SessionStore's full CRUD/branch/search surface down to
those two read-only methods -- curator must not import gateway.Message,
so role derivation (message.From == botUser -> assistant) is copied from
gateway.compressTurnHistory's existing logic, not shared.

sessioncurator.go: Check is a cheap RecentSessions bool. Pass takes each
session's last 40 messages, asks the model for a JSON array of durable
facts (capped at 5/session), and writes each through
Registrar.MemoryEngines.Get(name) -- resolved by name at call time, the
same trust model every other curator capability already uses. A
response that fails to parse degrades to "nothing extracted" for that
session (not a Pass error); a real model-call failure propagates as one
(these were originally conflated into the same swallowed-error path --
caught by TestPassPropagatesALLMFailure, fixed by splitting the model
call from the parse step). PassInput.Since zero resolves to a 24h
lookback, not the beginning of time, so a cold-start first pass can't
read a session's entire history.

Manifest.OnInput = true wakes it via the existing WakeOnPrimaryInput
wiring (events.KindTurnCompleted), which already excludes every
curator-derived event kind from the forwarded set -- the trigger-
accounting invariant (archie-core-1786637489768) needed no new code to
hold here.

Wired into bootstrap.go:setupCurators via a new curatorLLMRunner adapter
(main.go) over the shared ai-sdk runtime, and sessioncurator.NewAdapter
over b.chatSessionStore/b.cfg.BotUser. Model resolves from
b.chatModels.ActiveModel() -- not b.defaultChatIdentity, which names a
task-routing identity, not a model reference (the same source
telegram_setup.go's sendChatTurn already uses for a real chat turn).

task check is green (full Go suite + dashboard tests).
2026-09-02 03:09:04 +10:00

152 lines
5.9 KiB
Go

// 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
// Conversations declares the conversation-history capability
// (session-memory curator, archie-core-1786637499114). 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
// (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
}