feat(curator): definition-driven engine with tool-carrying passes

Phase 1 of dynamic curator definitions (archie-core-trnd.1):

- ToolBuilder implementation resolves declared tool names from the
  daemon's process-wide tool registry, returning exactly the declared
  set and failing closed on an unknown name.
- curatorLLMRunner now carries ChatRequest.Tools and MaxSteps into
  core.GenerateOptions and widens ChatResult with the executed tool
  calls so a pass can attribute its actions.
- One generic DefinitionEngine interprets a Definition (Manifest +
  name/enabled/instructions): its pass composes instructions with the
  built declared tool set, runs the model loop, and records an action
  per tool invocation.
- [[curators]] config definitions carry the Manifest shape verbatim plus
  name/enabled/instructions; a definition missing interval is refused,
  never defaulted.
- Idle curators are observable: the runtime logs a debug line when Check
  reports not-due.
This commit is contained in:
sam committed 2026-09-22 15:05:24 +10:00
1 parent debeb869bb
commit 60f04a351a
14 files changed
+687 -5

No files matched your search

+32
View File
@@ -55,6 +55,7 @@ import (
"github.com/samcharles93/archie-core/internal/infrastructure/skillcurator"
"github.com/samcharles93/archie-core/internal/infrastructure/staterpc"
"github.com/samcharles93/archie-core/internal/infrastructure/taskactions"
"github.com/samcharles93/archie-core/internal/infrastructure/toolbuilder"
"github.com/samcharles93/archie-core/internal/logging"
"github.com/samcharles93/archie-core/internal/plugin"
"github.com/samcharles93/archie-core/internal/plugin/pluginextract"
@@ -1024,6 +1025,10 @@ func (b *boot) setupCurators(ctx context.Context) {
b.curatorRegistry = curator.NewRegistry(curator.Registrar{
Log: log.With("component", "curator"),
Events: curatorEventSink{b.bus},
// Tools resolves declared curator tool names from the same
// process-wide registry a chat turn is given (b.toolReg): one
// catalogue, resolved down to the declared set by the builder.
Tools: toolbuilder.New(b.toolReg),
// b.memEngines (*domainmemory.Registry) satisfies
// curator.MemoryEngineSource's Get(name) signature directly, no
// adapter needed. Set by setupMemoryEngine, which Run() calls before
@@ -1053,6 +1058,33 @@ func (b *boot) setupCurators(ctx context.Context) {
if err := b.curatorRegistry.Register(sessioncurator.New(sessioncurator.DefaultInterval, infraMemory.EngineName)); err != nil {
log.Error("session-memory curator registration failed", "err", err)
}
// Config definitions are seed data: each enabled [[curators]] entry is
// registered through the one generic definition-driven engine. Code
// registrations above win for their own name (a duplicate is refused
// and logged, not silently replaced).
for _, def := range b.cfg.Curators {
if !def.Enabled {
continue
}
engine := curator.NewDefinitionEngine(curator.Definition{
Name: def.Name,
Enabled: def.Enabled,
Instructions: def.Instructions,
Manifest: curator.Manifest{
Interval: def.Interval.Std(),
Cooldown: def.Cooldown.Std(),
OnInput: def.OnInput,
Tools: def.Tools,
Skills: def.Skills,
MemoryEngine: def.MemoryEngine,
Conversations: def.Conversations,
Model: def.Model,
},
})
if err := b.curatorRegistry.Register(engine); err != nil {
log.Error("config curator registration failed", "curator", def.Name, "err", err)
}
}
// 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
+20 -4
View File
@@ -498,8 +498,10 @@ func (s curatorEventSink) Emit(kind, detail string, data map[string]any) {
// curatorLLMRunner adapts the shared ai-sdk runtime to the curator
// family's narrow LLMRunner contract: one model reference, plain
// messages, no tools, no streaming -- curators that need more than a
// single completion are a bigger decision than this adapter makes.
// messages, and the declared tool set -- no streaming. Tools are built
// through the same agentexec path a chat turn uses, so a curator's
// declared set is converted to a runnable core.ToolSet rather than a
// parallel catalogue.
type curatorLLMRunner struct {
rt *runtime.Runtime
// outcomes records this call for /status alongside sendChatTurn's. A
@@ -523,12 +525,26 @@ func (r curatorLLMRunner) Chat(ctx context.Context, req curator.ChatRequest) (cu
for _, m := range req.Messages {
msgs = append(msgs, chat.Message{Role: chat.Role(m.Role), Content: m.Content})
}
res, err := r.rt.Chat(ctx, req.Model, core.GenerateOptions{Messages: msgs, MaxSteps: max(req.MaxSteps, 1)})
toolSet, err := agentexec.BuildToolSetFrom(req.Tools, agentexec.ToolSetOptions{})
if err != nil {
r.outcomes.record(req.Model, err)
return curator.ChatResult{}, err
}
res, err := r.rt.Chat(ctx, req.Model, core.GenerateOptions{
Messages: msgs,
Tools: toolSet,
MaxSteps: max(req.MaxSteps, 1),
})
r.outcomes.record(req.Model, err)
if err != nil {
return curator.ChatResult{}, err
}
return curator.ChatResult{Text: res.Text}, nil
calls := make([]curator.ToolCall, 0, len(res.ToolCalls))
for _, call := range res.ToolCalls {
calls = append(calls, curator.ToolCall{Name: call.ToolName, Input: call.Input})
}
return curator.ChatResult{Text: res.Text, ToolCalls: calls}, nil
}
type chatTaskWriterAdapter struct {
+7
View File
@@ -546,6 +546,13 @@ type Config struct {
Repos []Repo `toml:"repos" yaml:"repos"`
ModelLimits map[string]ModelLimits `toml:"-" yaml:"-" json:"-"`
// Curators holds curator definitions as seed data ([[curators]]).
// Each entry is a curator.Manifest plus name/enabled/instructions.
// Seed data only: the app layer registers each enabled definition
// through the one generic definition-driven engine, and (once
// persistence lands) a stored definition of the same name wins.
Curators []CuratorDefinition `toml:"curators" yaml:"curators" json:"curators,omitempty"`
// Extra holds additional feature configuration from conf.d/ files that
// don't match a known feature name. Keys are the filename stem (e.g.
// "custom-tool" for conf.d/custom-tool.yaml).
+21
View File
@@ -0,0 +1,21 @@
package config
// CuratorDefinition is one [[curators]] entry: a curator definition as
// seed data. It carries the curator.Manifest shape verbatim plus the
// identity, lifecycle flag, and free-form instructions the manifest cannot
// express. A definition missing interval is refused by configuration
// validation, never defaulted.
type CuratorDefinition struct {
Name string `toml:"name" yaml:"name" json:"name"`
Enabled bool `toml:"enabled" yaml:"enabled" json:"enabled"`
Instructions string `toml:"instructions" yaml:"instructions" json:"instructions"`
Interval Duration `toml:"interval" yaml:"interval" json:"interval"`
Cooldown Duration `toml:"cooldown" yaml:"cooldown" json:"cooldown"`
OnInput bool `toml:"on_input" yaml:"on_input" json:"on_input"`
Tools []string `toml:"tools" yaml:"tools" json:"tools"`
Skills bool `toml:"skills" yaml:"skills" json:"skills"`
MemoryEngine string `toml:"memory_engine" yaml:"memory_engine" json:"memory_engine"`
Conversations bool `toml:"conversations" yaml:"conversations" json:"conversations"`
Model string `toml:"model" yaml:"model" json:"model"`
}
+18
View File
@@ -0,0 +1,18 @@
package curator
// Definition is a curator definition as data: the declared Manifest plus
// the identity, lifecycle flag, and free-form instructions the manifest
// cannot express. One generic engine (DefinitionEngine) interprets any
// definition -- there is deliberately no catalogue of curator "types" and
// no second authority beside the existing registry.
type Definition struct {
// Name is the registry key.
Name string
// Enabled gates registration: a disabled definition is seed data that
// the app layer does not register.
Enabled bool
// Instructions is the free-form system prompt for the generic engine.
Instructions string
// Manifest is the declared shape, verbatim.
Manifest Manifest
}
@@ -0,0 +1,130 @@
package curator
import (
"context"
"fmt"
"strings"
"github.com/samcharles93/archie-core/internal/tools"
)
// ActionToolCalled is the Action.Type recorded for each tool the model
// loop invoked, so a definition-driven pass stays attributable through the
// registry's activity surface and events.
const ActionToolCalled = "tool.called"
// defaultDefinitionMaxSteps bounds the model/tool loop of one definition
// pass. It is not a definition value and is deliberately not configurable
// yet: the PRD's no-live-path-constants rule covers interval, cooldown,
// tools, model, and memory engine, not loop length.
const defaultDefinitionMaxSteps = 10
// DefinitionEngine interprets a Definition: one generic engine serving
// every data-defined curator. Its pass composes the definition's
// instructions with the built declared tool set, calls the model, and
// records an Action per tool invocation.
type DefinitionEngine struct {
def Definition
host Registrar
}
// NewDefinitionEngine builds the generic engine for one definition.
func NewDefinitionEngine(def Definition) *DefinitionEngine {
return &DefinitionEngine{def: def}
}
func (e *DefinitionEngine) Name() string { return e.def.Name }
func (e *DefinitionEngine) Version() string { return "1" }
func (e *DefinitionEngine) Manifest() Manifest { return e.def.Manifest }
func (e *DefinitionEngine) Bind(host Registrar) { e.host = host }
func (e *DefinitionEngine) Start(context.Context) error { return nil }
func (e *DefinitionEngine) Health(context.Context) Health {
return Health{Status: HealthHealthy}
}
func (e *DefinitionEngine) Stop(context.Context) error { return nil }
// Check reports a definition is eligible whenever the runtime schedules it:
// a definition has no input state of its own to read, so eligibility is the
// manifest interval (and optional OnInput nudge) the runtime already owns.
func (e *DefinitionEngine) Check(context.Context) (bool, error) { return true, nil }
// Pass resolves the declared tools, composes the instructions with the
// built set, runs the model loop, and records an Action per tool call. A
// declared name with no implementation fails the pass (fail closed); the
// model receives exactly the declared set, never a broader registry.
func (e *DefinitionEngine) Pass(ctx context.Context, in PassInput) (PassResult, error) {
declared := e.def.Manifest.Tools
var built []tools.ToolEntry
if len(declared) > 0 {
if e.host.Tools == nil {
return PassResult{}, fmt.Errorf("curator %s: declares tools but no ToolBuilder is bound", e.def.Name)
}
var err error
built, err = e.host.Tools.Build(ctx, declared)
if err != nil {
return PassResult{}, fmt.Errorf("curator %s: build tools: %w", e.def.Name, err)
}
}
if e.host.LLM == nil {
return PassResult{}, fmt.Errorf("curator %s: no model runner is bound", e.def.Name)
}
model := e.def.Manifest.Model
if model == "" {
model = e.host.Model
}
res, err := e.host.LLM.Chat(ctx, ChatRequest{
Model: model,
Messages: definitionMessages(e.def.Instructions, built, in.Reason),
Tools: built,
MaxSteps: defaultDefinitionMaxSteps,
})
if err != nil {
return PassResult{}, err
}
actions := make([]Action, 0, len(res.ToolCalls))
for _, call := range res.ToolCalls {
actions = append(actions, Action{
At: e.host.Clock.Now(),
Type: ActionToolCalled,
Detail: call.Name,
Reason: in.Reason,
})
}
return PassResult{Actions: actions}, nil
}
// definitionMessages builds the prompt for one pass: the definition's
// instructions plus a summary of the built tool set as the system prompt,
// and the pass reason as the user turn. The tool summaries come from the
// same set that was built, never from a wider list.
func definitionMessages(instructions string, built []tools.ToolEntry, reason string) []Message {
system := instructions
if len(built) > 0 {
var b strings.Builder
b.WriteString(instructions)
b.WriteString("\n\nAvailable tools:\n")
for _, t := range built {
desc := strings.TrimSpace(t.Description)
if desc == "" {
desc = "(no description)"
}
fmt.Fprintf(&b, "- %s: %s\n", t.Name, desc)
}
system = b.String()
}
user := strings.TrimSpace(reason)
if user == "" {
user = "Run your scheduled pass now."
}
return []Message{
{Role: "system", Content: system},
{Role: "user", Content: user},
}
}
@@ -0,0 +1,183 @@
package curator
import (
"context"
"fmt"
"strings"
"testing"
"time"
"github.com/samcharles93/archie-core/internal/tools"
)
// recordingLLM captures the ChatRequest a definition pass builds and returns
// a fixed result, so tests assert exactly what reached the model.
type recordingLLM struct {
req ChatRequest
result ChatResult
err error
}
func (l *recordingLLM) Chat(_ context.Context, req ChatRequest) (ChatResult, error) {
l.req = req
return l.result, l.err
}
// mapBuilder resolves declared names from a fixed map: the same resolution
// contract as the infrastructure ToolBuilder, without domain tests importing
// infrastructure.
type mapBuilder struct {
entries map[string]tools.ToolEntry
}
func (b mapBuilder) Build(_ context.Context, declared []string) ([]tools.ToolEntry, error) {
out := make([]tools.ToolEntry, 0, len(declared))
for _, name := range declared {
entry, ok := b.entries[name]
if !ok {
return nil, fmt.Errorf("declared tool %q has no implementation", name)
}
out = append(out, entry)
}
return out, nil
}
func definitionTool(name string) tools.ToolEntry {
return tools.ToolEntry{
Name: name,
Description: name + " tool",
Handler: func(context.Context, map[string]any) (any, error) { return nil, nil },
}
}
func TestDefinitionEnginePassReachesExactlyDeclaredTools(t *testing.T) {
t.Parallel()
def := Definition{
Name: "project-curator",
Enabled: true,
Instructions: "Review the repository and report what you changed.",
Manifest: Manifest{
Interval: time.Hour,
Model: "provider/config-model",
Tools: []string{"read"},
},
}
llm := &recordingLLM{result: ChatResult{
Text: "done",
ToolCalls: []ToolCall{{Name: "read", Input: "{}"}},
}}
engine := NewDefinitionEngine(def)
engine.Bind(Registrar{
LLM: llm,
Model: "provider/default-model",
Tools: mapBuilder{entries: map[string]tools.ToolEntry{
"read": definitionTool("read"),
"write": definitionTool("write"),
}},
Clock: testClock{now: time.Unix(0, 0)},
})
res, err := engine.Pass(context.Background(), PassInput{Reason: "check-in"})
if err != nil {
t.Fatalf("Pass() error = %v, want nil", err)
}
if got := len(llm.req.Tools); got != 1 {
t.Fatalf("model received %d tools, want exactly the declared 1 (never a broader registry)", got)
}
if llm.req.Tools[0].Name != "read" {
t.Fatalf("model received tool %q, want the declared %q", llm.req.Tools[0].Name, "read")
}
if llm.req.Model != "provider/config-model" {
t.Fatalf("model reference = %q, want the definition's %q (no fallback to the default)", llm.req.Model, "provider/config-model")
}
if llm.req.MaxSteps <= 1 {
t.Fatalf("MaxSteps = %d, want more than one so the tool loop can run", llm.req.MaxSteps)
}
if len(llm.req.Messages) == 0 || llm.req.Messages[0].Role != "system" {
t.Fatalf("messages = %+v, want a leading system prompt", llm.req.Messages)
}
if sys := llm.req.Messages[0].Content; !strings.Contains(sys, def.Instructions) || !strings.Contains(sys, "read") {
t.Fatalf("system prompt = %q, want the definition instructions plus the declared tool summary", sys)
}
if len(res.Actions) != 1 {
t.Fatalf("Pass() actions = %d, want one per tool call", len(res.Actions))
}
a := res.Actions[0]
if a.Type != ActionToolCalled || a.Detail != "read" || a.Reason != "check-in" {
t.Fatalf("action = %+v, want the invoked tool attributed with the pass reason", a)
}
}
func TestDefinitionEnginePassFailsOnUnknownDeclaredTool(t *testing.T) {
t.Parallel()
def := Definition{
Name: "project-curator",
Manifest: Manifest{
Interval: time.Hour,
Tools: []string{"gh.issue.create"},
},
}
llm := &recordingLLM{}
engine := NewDefinitionEngine(def)
engine.Bind(Registrar{
LLM: llm,
Tools: mapBuilder{entries: map[string]tools.ToolEntry{}},
Clock: testClock{now: time.Unix(0, 0)},
})
if _, err := engine.Pass(context.Background(), PassInput{Reason: "check-in"}); err == nil {
t.Fatal("Pass() with an unknown declared tool = nil error, want the build failure to fail the pass")
}
if llm.req.Messages != nil {
t.Fatalf("model was called despite the failed build: %+v", llm.req)
}
}
func TestDefinitionEngineManifestIsTheDefinitionNoCodeFallback(t *testing.T) {
t.Parallel()
def := Definition{
Name: "config-defined",
Enabled: true,
Instructions: "do the thing",
Manifest: Manifest{
Interval: 17 * time.Minute,
Cooldown: 3 * time.Minute,
OnInput: true,
Tools: []string{"read", "shell"},
Model: "provider/config-model",
},
}
engine := NewDefinitionEngine(def)
got := engine.Manifest()
if got.Interval != 17*time.Minute {
t.Fatalf("Manifest().Interval = %v, want the definition's %v (no code constant)", got.Interval, 17*time.Minute)
}
if got.Cooldown != 3*time.Minute || !got.OnInput {
t.Fatalf("Manifest() = %+v, want the definition's cooldown/on_input", got)
}
if len(got.Tools) != 2 || got.Tools[0] != "read" || got.Tools[1] != "shell" {
t.Fatalf("Manifest().Tools = %v, want the definition's declared set", got.Tools)
}
if got.Model != "provider/config-model" {
t.Fatalf("Manifest().Model = %q, want the definition's model", got.Model)
}
}
func TestDefinitionEngineRegistrationRequiresToolBuilder(t *testing.T) {
t.Parallel()
reg := NewRegistry(Registrar{})
err := reg.Register(NewDefinitionEngine(Definition{
Name: "project-curator",
Manifest: Manifest{Interval: time.Hour, Tools: []string{"read"}},
}))
if err == nil {
t.Fatal("Register(tools-declaring definition) = nil, want the existing no-ToolBuilder refusal")
}
}
+12 -1
View File
@@ -74,9 +74,20 @@ type Message struct {
Content string
}
// ChatResult is the model's final answer.
// ChatResult is the model's final answer plus the tool invocations the
// model loop executed, so a pass can attribute its actions to the tools
// that ran.
type ChatResult struct {
Text string
// ToolCalls is every tool invocation across the loop, in execution
// order. Empty for a single completion with no tools.
ToolCalls []ToolCall
}
// ToolCall is one tool invocation the model loop executed.
type ToolCall struct {
Name string
Input string // JSON-encoded arguments, verbatim from the model
}
// ToolBuilder resolves declared tool names into a runnable tool set. A
+3
View File
@@ -207,6 +207,9 @@ func (rt *Runtime) runLoop(ctx context.Context, name string, c CuratorEngine) {
}
if !due {
next = clock.Now().Add(m.Interval)
if log := rt.registry.Host().Log; log != nil {
log.Debug("curator not due", "curator", name, "next", next)
}
continue
}
+55
View File
@@ -3,6 +3,7 @@ package curator
import (
"context"
"errors"
"log/slog"
"slices"
"sync"
"testing"
@@ -454,6 +455,60 @@ func TestRuntimePassInputRecordsReasonAndLastPass(t *testing.T) {
}
}
// debugCaptureHandler records debug-level messages so a test can observe an
// idle curator that the runtime would otherwise be silent about.
type debugCaptureHandler struct {
mu sync.Mutex
msgs []string
}
func (h *debugCaptureHandler) Enabled(context.Context, slog.Level) bool { return true }
func (h *debugCaptureHandler) Handle(_ context.Context, r slog.Record) error {
if r.Level == slog.LevelDebug {
h.mu.Lock()
h.msgs = append(h.msgs, r.Message)
h.mu.Unlock()
}
return nil
}
func (h *debugCaptureHandler) WithAttrs([]slog.Attr) slog.Handler { return h }
func (h *debugCaptureHandler) WithGroup(string) slog.Handler { return h }
func (h *debugCaptureHandler) count(msg string) int {
h.mu.Lock()
defer h.mu.Unlock()
n := 0
for _, m := range h.msgs {
if m == msg {
n++
}
}
return n
}
func TestRuntimeLogsWhenCheckReportsNotDue(t *testing.T) {
t.Parallel()
clock := newFakeClock(time.Unix(0, 0))
handler := &debugCaptureHandler{}
c := newFake("idle", Manifest{Interval: testInterval})
c.checkResult = false
reg := NewRegistry(Registrar{Clock: clock, Events: &testSink{}, Log: slog.New(handler)})
if err := reg.Register(c); err != nil {
t.Fatalf("Register(idle) = %v, want nil", err)
}
rt := NewRuntime(reg, RuntimeConfig{})
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 check-in logged", func() bool {
return handler.count("curator not due") > 0
})
}
func TestRuntimePassInputSetsSinceToPriorPass(t *testing.T) {
t.Parallel()
@@ -0,0 +1,69 @@
package configuration
import (
"testing"
"time"
"github.com/samcharles93/archie-core/internal/config"
)
func TestValidateCurators(t *testing.T) {
tests := []struct {
name string
mutate func(cfg *config.Config)
wantErr bool
}{
{
name: "no curators",
mutate: func(cfg *config.Config) {},
},
{
name: "valid curator",
mutate: func(cfg *config.Config) {
cfg.Curators = []config.CuratorDefinition{{Name: "project", Enabled: true, Interval: config.Duration(time.Hour)}}
},
},
{
name: "missing interval",
mutate: func(cfg *config.Config) {
cfg.Curators = []config.CuratorDefinition{{Name: "project", Enabled: true}}
},
wantErr: true,
},
{
name: "zero interval",
mutate: func(cfg *config.Config) {
cfg.Curators = []config.CuratorDefinition{{Name: "project", Enabled: true, Interval: config.Duration(0)}}
},
wantErr: true,
},
{
name: "negative interval",
mutate: func(cfg *config.Config) {
cfg.Curators = []config.CuratorDefinition{{Name: "project", Enabled: true, Interval: config.Duration(-time.Minute)}}
},
wantErr: true,
},
{
// A definition must be valid seed data whether or not it is
// currently enabled: flipping Enabled on later must not silently
// default the interval.
name: "disabled curator still requires interval",
mutate: func(cfg *config.Config) {
cfg.Curators = []config.CuratorDefinition{{Name: "project"}}
},
wantErr: true,
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
cfg := minimalValidConfig()
tt.mutate(&cfg)
err := Validate(&cfg)
if (err != nil) != tt.wantErr {
t.Fatalf("Validate() error = %v, wantErr %v", err, tt.wantErr)
}
})
}
}
@@ -109,6 +109,9 @@ func validateBootstrap(cfg *config.Config) error {
if err := validateImage(cfg); err != nil {
return err
}
if err := validateCurators(cfg); err != nil {
return err
}
return validateCapture(cfg)
}
@@ -173,6 +176,19 @@ func validateImage(cfg *config.Config) error {
return nil
}
// validateCurators rejects a curator definition with no interval. The
// interval is a live-path value: a definition missing it is refused with a
// clear error rather than defaulted at registration or pass time, so a
// config-defined curator can never silently inherit a code constant.
func validateCurators(cfg *config.Config) error {
for i, def := range cfg.Curators {
if def.Interval <= 0 {
return fmt.Errorf("%w: curators[%d].interval must be positive", ErrInvalidInput, i)
}
}
return nil
}
// validateMemory rejects an engine name outside memoryEngines. Empty is
// valid input to Validate (applyDefaults resolves it to memoryEngineBuiltin
// before this runs on the real load path); it is not "unknown" so it does
@@ -0,0 +1,48 @@
// Package toolbuilder resolves a curator's declared tool names from the
// daemon's process-wide tool registry (internal/tools.Registry). It is the
// implementation of curator.ToolBuilder: resolution returns exactly the
// declared set, never a broader registry, and a declared name with no
// implementation fails the build rather than silently returning fewer tools.
package toolbuilder
import (
"context"
"errors"
"fmt"
"github.com/samcharles93/archie-core/internal/domain/curator"
"github.com/samcharles93/archie-core/internal/tools"
)
var _ curator.ToolBuilder = (*Builder)(nil)
// Builder resolves declared curator tool names against a tools.Registry.
type Builder struct {
reg *tools.Registry
}
// New builds a ToolBuilder over reg. A nil reg is valid and reports a
// clear error from Build when a declared tool set is requested.
func New(reg *tools.Registry) *Builder {
return &Builder{reg: reg}
}
// Build returns exactly the declared set in declared order. A declared name
// absent from the registry fails the build.
func (b *Builder) Build(_ context.Context, declared []string) ([]tools.ToolEntry, error) {
if b.reg == nil {
if len(declared) == 0 {
return nil, nil
}
return nil, errors.New("toolbuilder: no tool registry bound")
}
out := make([]tools.ToolEntry, 0, len(declared))
for _, name := range declared {
entry, ok := b.reg.Get(name)
if !ok {
return nil, fmt.Errorf("toolbuilder: declared tool %q has no implementation", name)
}
out = append(out, entry)
}
return out, nil
}
@@ -0,0 +1,73 @@
package toolbuilder
import (
"context"
"testing"
"github.com/samcharles93/archie-core/internal/tools"
)
func mustRegister(t *testing.T, reg *tools.Registry, names ...string) {
t.Helper()
for _, name := range names {
if err := reg.Register(tools.ToolEntry{
Name: name,
Handler: func(context.Context, map[string]any) (any, error) { return nil, nil },
}); err != nil {
t.Fatalf("register %s: %v", name, err)
}
}
}
func namesOf(entries []tools.ToolEntry) []string {
out := make([]string, 0, len(entries))
for _, e := range entries {
out = append(out, e.Name)
}
return out
}
func TestBuilderResolvesExactlyDeclared(t *testing.T) {
t.Parallel()
reg := tools.NewRegistry()
mustRegister(t, reg, "read", "write", "shell")
got, err := New(reg).Build(context.Background(), []string{"read", "shell"})
if err != nil {
t.Fatalf("Build() error = %v, want nil", err)
}
want := []string{"read", "shell"}
if len(got) != len(want) {
t.Fatalf("Build() returned %d tools, want exactly %d (declared set, never broader)", len(got), len(want))
}
if gotNames := namesOf(got); gotNames[0] != want[0] || gotNames[1] != want[1] {
t.Fatalf("Build() = %v, want %v in declared order", gotNames, want)
}
}
func TestBuilderUnknownNameFails(t *testing.T) {
t.Parallel()
reg := tools.NewRegistry()
mustRegister(t, reg, "read")
if _, err := New(reg).Build(context.Background(), []string{"read", "gh.issue.create"}); err == nil {
t.Fatal("Build() with an unknown declared name = nil error, want failure")
}
}
func TestBuilderEmptyDeclaredSetIsEmptyNotWholeRegistry(t *testing.T) {
t.Parallel()
reg := tools.NewRegistry()
mustRegister(t, reg, "read")
got, err := New(reg).Build(context.Background(), nil)
if err != nil {
t.Fatalf("Build(nil) error = %v, want nil", err)
}
if len(got) != 0 {
t.Fatalf("Build(nil) = %v, want no tools (an empty declaration must not fall back to the whole registry)", namesOf(got))
}
}