Files
archie/internal/tools/registry.go
T
sam f73b2d1c8c feat: memory manager sync/prefetch/scan/shutdown + broad in-flight epic work
Checkpoint commit covering concurrent work across several archie-core-abg
epics to avoid losing in-progress state:

- Memory manager (18.7-18.16): background sync pipeline, prefetch with
  timeout, memory-write notification, threat scanning, shutdown drain
  with abandoned-write tracking, frozen snapshot pattern. Wired
  ScanContent and NotifyMemoryToolWrite into HandleToolCall so scanning
  and notification actually apply to writes, not just exist as unused
  primitives.
- Fixed a literal unresolved merge-conflict that had been committed to
  internal/memory/scrubber/scrubber.go.
- Tool provider/registry, MCP client/transport (stdio, HTTP, SSE),
  multimodal results, disclosure.
- Pairing device auth store, rate limiting.
- Gateway compression, session store, tasks.
- Various workflow, plugin host, and agentexec updates.
2026-07-27 03:34:46 +10:00

472 lines
11 KiB
Go

package tools
import (
"errors"
"fmt"
"go/ast"
"go/parser"
"go/token"
"io/fs"
"path"
"strconv"
"sync"
)
// ErrDuplicateTool is returned by [Registry.Register] when a tool with the
// same name has already been registered.
var ErrDuplicateTool = errors.New("duplicate tool name")
// defaultRegistry is the package-level singleton.
var defaultRegistry = NewRegistry()
// DefaultRegistry returns the package-level singleton registry. Most
// callers should use this rather than creating their own.
func DefaultRegistry() *Registry {
return defaultRegistry
}
// Registry is a thread-safe tool registry. It maps tool names to
// [ToolEntry] values and supports lookup by toolset and availability.
type Registry struct {
mu sync.RWMutex
tools map[string]ToolEntry
}
// NewRegistry creates a new, empty Registry.
func NewRegistry() *Registry {
return &Registry{
tools: make(map[string]ToolEntry),
}
}
// Register adds a tool entry to the registry. It returns an error if the
// entry fails [ToolEntry.Validate], or if a tool with the same name is
// already registered (wrapping [ErrDuplicateTool]).
func (r *Registry) Register(e ToolEntry) error {
return r.RegisterBatch([]ToolEntry{e})
}
// RegisterBatch adds all entries or none.
func (r *Registry) RegisterBatch(entries []ToolEntry) error {
clones := make([]ToolEntry, len(entries))
names := make(map[string]struct{}, len(entries))
for _, entry := range entries {
if err := entry.Validate(); err != nil {
return err
}
if _, exists := names[entry.Name]; exists {
return fmt.Errorf("%w: %q", ErrDuplicateTool, entry.Name)
}
names[entry.Name] = struct{}{}
}
for i, entry := range entries {
clones[i] = entry.Clone()
}
r.mu.Lock()
defer r.mu.Unlock()
for name := range names {
if _, exists := r.tools[name]; exists {
return fmt.Errorf("%w: %q", ErrDuplicateTool, name)
}
}
for _, entry := range clones {
r.tools[entry.Name] = entry
}
return nil
}
// Unregister removes the named tools. Unknown names are ignored.
func (r *Registry) Unregister(names ...string) {
r.mu.Lock()
defer r.mu.Unlock()
for _, name := range names {
delete(r.tools, name)
}
}
// Get returns the tool entry registered under name, and whether it was
// found. The returned entry is a defensive copy -- mutating it does not
// affect the registry.
func (r *Registry) Get(name string) (ToolEntry, bool) {
r.mu.RLock()
defer r.mu.RUnlock()
e, ok := r.tools[name]
if !ok {
return ToolEntry{}, false
}
return e.Clone(), true
}
// All returns all registered tool entries. The returned slice is a
// snapshot -- mutating it does not affect the registry.
func (r *Registry) All() []ToolEntry {
r.mu.RLock()
defer r.mu.RUnlock()
out := make([]ToolEntry, 0, len(r.tools))
for _, e := range r.tools {
out = append(out, e.Clone())
}
return out
}
// ByToolset returns tools belonging to the given toolset. Pass an empty
// string to match tools that have no toolset.
func (r *Registry) ByToolset(toolset string) []ToolEntry {
r.mu.RLock()
defer r.mu.RUnlock()
var out []ToolEntry
for _, e := range r.tools {
if e.Toolset == toolset {
out = append(out, e.Clone())
}
}
return out
}
// Available returns tools whose [ToolEntry.Available] method returns true.
//
// CheckFn is evaluated outside the registry lock to avoid deadlock if
// the function re-enters the registry (e.g. calling Register or All).
func (r *Registry) Available() []ToolEntry {
r.mu.RLock()
snapshot := make([]ToolEntry, 0, len(r.tools))
for _, e := range r.tools {
snapshot = append(snapshot, e.Clone())
}
r.mu.RUnlock()
// Evaluate CheckFn outside the lock -- no deadlock risk.
var out []ToolEntry
for _, e := range snapshot {
if e.Available() {
out = append(out, e)
}
}
return out
}
// Discover scans a directory of Go source files for Register calls
// that pass a [ToolEntry] composite literal. It uses [go/parser] and
// [go/ast] to statically analyse source files without executing them.
//
// Discover returns the number of Register calls found. Function fields
// (Handler, CheckFn, DynamicSchemaOverrides) cannot be resolved from
// static source analysis and remain nil. Entries that fail
// [ToolEntry.Validate] -- typically because Handler is nil -- are
// counted but not registered.
//
// Parse errors in individual files do not stop the scan; they are
// accumulated and returned as a joined error alongside the count of
// Register calls found in successfully-parsed files.
func (r *Registry) Discover(fsys fs.FS, dir string) (int, error) {
entries, err := fs.Glob(fsys, path.Join(dir, "*.go"))
if err != nil {
return 0, err
}
count := 0
var errs []error
for _, filePath := range entries {
src, err := fs.ReadFile(fsys, filePath)
if err != nil {
errs = append(errs, fmt.Errorf("read %s: %w", filePath, err))
continue
}
fset := token.NewFileSet()
f, err := parser.ParseFile(fset, filePath, src, parser.ParseComments)
if err != nil {
errs = append(errs, fmt.Errorf("parse %s: %w", filePath, err))
continue
}
count += countRegisterCalls(f)
for _, entry := range extractToolEntries(f) {
// Best-effort registration: only entries that pass
// Validate (have Name + Handler) are registered.
_ = r.Register(entry)
}
}
return count, errors.Join(errs...)
}
// countRegisterCalls counts the number of Register method calls in a Go AST.
func countRegisterCalls(f *ast.File) int {
count := 0
ast.Inspect(f, func(n ast.Node) bool {
call, ok := n.(*ast.CallExpr)
if !ok {
return true
}
if isRegisterCall(call) {
count++
}
return true
})
return count
}
// extractToolEntries walks the AST and extracts [ToolEntry] composite
// literals from Register calls.
func extractToolEntries(f *ast.File) []ToolEntry {
var entries []ToolEntry
ast.Inspect(f, func(n ast.Node) bool {
call, ok := n.(*ast.CallExpr)
if !ok {
return true
}
if !isRegisterCall(call) {
return true
}
if len(call.Args) == 0 {
return true
}
comp, ok := call.Args[0].(*ast.CompositeLit)
if !ok {
return true
}
entries = append(entries, toolEntryFromCompositeLit(comp))
return true
})
return entries
}
// isRegisterCall reports whether call is a .Register(...) method call on
// a *Registry receiver. It accepts common patterns:
//
// - DefaultRegistry().Register(...)
// - tools.DefaultRegistry().Register(...)
// - r.Register(...) where r is a known registry variable
func isRegisterCall(call *ast.CallExpr) bool {
sel, ok := call.Fun.(*ast.SelectorExpr)
if !ok {
return false
}
if sel.Sel.Name != "Register" {
return false
}
// The receiver must be a call to DefaultRegistry, with or without
// a package qualifier (e.g. DefaultRegistry() or tools.DefaultRegistry()).
rcv, ok := sel.X.(*ast.CallExpr)
if !ok {
return false
}
return callsDefaultRegistry(rcv)
}
// callsDefaultRegistry reports whether call is a DefaultRegistry()
// invocation, with or without a package qualifier.
func callsDefaultRegistry(call *ast.CallExpr) bool {
switch fn := call.Fun.(type) {
case *ast.Ident:
return fn.Name == "DefaultRegistry"
case *ast.SelectorExpr:
// pkg.DefaultRegistry()
return fn.Sel.Name == "DefaultRegistry"
default:
return false
}
}
// toolEntryFromCompositeLit extracts a [ToolEntry] from an AST composite
// literal. Only basic literal values (strings, bools, ints) are extracted;
// function references are ignored.
func toolEntryFromCompositeLit(lit *ast.CompositeLit) ToolEntry {
var e ToolEntry
for _, elt := range lit.Elts {
kv, ok := elt.(*ast.KeyValueExpr)
if !ok {
continue
}
key, ok := kv.Key.(*ast.Ident)
if !ok {
continue
}
switch key.Name {
case "Name":
e.Name = stringLit(kv.Value)
case "Toolset":
e.Toolset = stringLit(kv.Value)
case "Description":
e.Description = stringLit(kv.Value)
case "Emoji":
e.Emoji = stringLit(kv.Value)
case "IsAsync":
e.IsAsync = boolLit(kv.Value)
case "MaxResultSizeChars":
e.MaxResultSizeChars = intLit(kv.Value)
case "RequiresEnv":
e.RequiresEnv = stringSliceLit(kv.Value)
case "Schema":
e.Schema = schemaLit(kv.Value)
}
}
return e
}
// --- AST value extractors ---
func stringLit(expr ast.Expr) string {
lit, ok := expr.(*ast.BasicLit)
if !ok || lit.Kind != token.STRING {
return ""
}
// strconv.Unquote handles double-quoted, backtick-delimited (raw),
// and interpreted string literals with escape sequences.
s, err := strconv.Unquote(lit.Value)
if err != nil {
return ""
}
return s
}
func boolLit(expr ast.Expr) bool {
ident, ok := expr.(*ast.Ident)
return ok && ident.Name == "true"
}
func intLit(expr ast.Expr) int {
// Handle negative literals: the AST represents -5 as
// UnaryExpr{Op: token.SUB, X: BasicLit{Kind: INT, Value: "5"}}.
if un, ok := expr.(*ast.UnaryExpr); ok && un.Op == token.SUB {
lit, ok := un.X.(*ast.BasicLit)
if !ok || lit.Kind != token.INT {
return 0
}
v, err := strconv.ParseInt(lit.Value, 0, 0)
if err != nil {
return 0
}
return -int(v)
}
lit, ok := expr.(*ast.BasicLit)
if !ok || lit.Kind != token.INT {
return 0
}
// base=0 auto-detects decimal, hex (0x), octal (0o), binary (0b).
v, err := strconv.ParseInt(lit.Value, 0, 0)
if err != nil {
return 0
}
return int(v)
}
func stringSliceLit(expr ast.Expr) []string {
comp, ok := expr.(*ast.CompositeLit)
if !ok {
return nil
}
out := make([]string, 0, len(comp.Elts))
for _, elt := range comp.Elts {
if s := stringLit(elt); s != "" || isStringLit(elt) {
out = append(out, s)
}
}
return out
}
// isStringLit reports whether expr is a string literal (including empty).
func isStringLit(expr ast.Expr) bool {
lit, ok := expr.(*ast.BasicLit)
return ok && lit.Kind == token.STRING
}
func schemaLit(expr ast.Expr) JSONSchema {
comp, ok := expr.(*ast.CompositeLit)
if !ok {
return nil
}
s := make(JSONSchema)
for _, elt := range comp.Elts {
kv, ok := elt.(*ast.KeyValueExpr)
if !ok {
continue
}
key := schemaKey(kv.Key)
if key == "" {
continue
}
if v := schemaValue(kv.Value); v != nil {
s[key] = v
}
}
if len(s) == 0 {
return nil
}
return s
}
// schemaKey extracts a key string from a schema literal key expression.
// Handles string literals and identifier names (e.g. Type: "object").
func schemaKey(expr ast.Expr) string {
if s := stringLit(expr); s != "" {
return s
}
if ident, ok := expr.(*ast.Ident); ok {
return ident.Name
}
return ""
}
// schemaValue extracts a value from a schema literal, handling strings,
// ints, bools, nested maps, and arrays of strings.
func schemaValue(expr ast.Expr) any {
switch v := expr.(type) {
case *ast.BasicLit:
switch v.Kind {
case token.STRING:
return stringLit(v)
case token.INT:
return intLit(v)
default:
return nil
}
case *ast.Ident:
if v.Name == "true" {
return true
}
if v.Name == "false" {
return false
}
return nil
case *ast.CompositeLit:
// Check if it's a slice/array (no key-value pairs) or a map.
if isArrayLit(v) {
return schemaArrayLit(v)
}
return schemaLit(v)
default:
return nil
}
}
// isArrayLit reports whether a composite literal looks like a slice/array
// (elements without keys) rather than a map.
func isArrayLit(lit *ast.CompositeLit) bool {
if len(lit.Elts) == 0 {
return false
}
_, ok := lit.Elts[0].(*ast.KeyValueExpr)
return !ok
}
// schemaArrayLit extracts a []any from an array composite literal.
func schemaArrayLit(lit *ast.CompositeLit) []any {
var out []any
for _, elt := range lit.Elts {
if v := schemaValue(elt); v != nil {
out = append(out, v)
}
}
return out
}