* chore(plugin): delete the unwired capability-host health surface
plugin.Host.Health, plugin.Host.Manifests, ModuleStatus and their private
safeHealth helper were implemented, exhaustively tested, and called from nowhere
but their own tests. AGENTS.md forbids speculative surfaces, and no settled
design places plugin module status anywhere that exists:
- docs/prds/status-health-surface.md Phase 2 is self-described as "a proposed
resolution, awaiting Sam's sign-off -- not yet implemented", and does not
mention plugin status even in that unapproved list.
- The readiness subsystem enumerates exactly five probes -- state_db, config,
disk, model, gateway (internal/app/archied/readiness.go) -- with no plugin
probe.
- docs/architecture/plugins-and-extensions.md names no operator-visible plugin
status surface.
- The only bead naming it is closed.
plugin.Host itself stays: it is the daemon's live capability host, constructed
and Start/Stop-ed from internal/app/archied. Only the unconsumed observability
methods go.
host_contract_test.go encoded the defect -- it asserted plugin.Host *defines*
"Health" and "Manifests" -- so those two names are removed from its list, which
is now exactly the shipped lifecycle: Register, Start, Stop. The three tests
covering the deleted surface are removed with it.
The Yaegi symbol table (internal/plugin/pluginextract) was regenerated rather
than hand-edited, so ModuleStatus leaves the reflected type set with it.
Reachability evidence: Host.Health and Host.Manifests appear only in their own
tests; plugin.Host is otherwise reached from bootstrap.go and gateway.go for
Register/Start/Stop. Note that "task reachability" does NOT flag these -- the
address-taken constructor is a known blind spot of the whole-program RTA.
* chore(plugin): delete the dead Module.Health chain wired to nothing
Extends the capability-host observability deletion: plugin.Module.Health
was a required interface method with real implementations in
tools/provider/mcp and tools/provider/builtin, aggregated by
tools/provider.Registry.Health via a provider-package-local safeHealth,
and backed by per-module LifecycleState bookkeeping in plugin.Host
(registeredModule.state, setModuleState). None of it had a caller before
this change -- Host.Health was the only thing that would ever have read
a registered module's Health(), and Host.Health was already deleted as
unreachable. registeredModule.state was write-only: nothing ever read it.
Deleted:
- plugin.Module.Health, plugin.Health/HealthStatus (+ consts),
plugin.LifecycleState (+ consts), legacyModule.Health,
registeredModule.state, Host.setModuleState and its call sites.
- tools/provider.Registry.Health, tools/provider.safeHealth.
- tools/provider/mcp.Provider.Health, tools/provider/builtin.Provider.Health.
- Tests exclusively covering the above, and fakes' now-unnecessary Health
methods (plugin/host_test.go, pluginextract/reachability_test.go,
tools/provider/{provider,optional}_test.go, tools/provider/mcp/provider_test.go,
app/agentworker/mcp_providers_test.go).
internal/plugin/pluginextract's generated file was regenerated via
`go generate ./internal/plugin/...` and the yaegi wrapper nil-guards
(dropped by fresh generation, as documented in reachability_test.go)
were reapplied by hand to WManifest/WStart/WStop/WName/WVersion,
following this repo's established post-regen pattern.
537 lines
15 KiB
Go
537 lines
15 KiB
Go
// Package provider defines the typed tool-provider capability family.
|
|
package provider
|
|
|
|
import (
|
|
"context"
|
|
"errors"
|
|
"fmt"
|
|
"reflect"
|
|
"slices"
|
|
"sync"
|
|
"time"
|
|
|
|
"github.com/samcharles93/archie-core/internal/plugin"
|
|
"github.com/samcharles93/archie-core/internal/tools"
|
|
)
|
|
|
|
var (
|
|
// ErrDuplicateProvider is returned when a manifest ID is already registered.
|
|
ErrDuplicateProvider = errors.New("duplicate tool provider")
|
|
// ErrRegistryStarted is returned when registration occurs after lifecycle start.
|
|
ErrRegistryStarted = errors.New("tool provider registry already started")
|
|
)
|
|
|
|
const toolCapability plugin.CapabilityKind = "tools"
|
|
|
|
const cleanupTimeout = 10 * time.Second
|
|
|
|
// Engine is one lifecycle-managed source of executable tools.
|
|
type Engine interface {
|
|
plugin.Module
|
|
Discover(context.Context) ([]tools.ToolEntry, error)
|
|
}
|
|
|
|
type registryState uint8
|
|
|
|
const (
|
|
stateIdle registryState = iota
|
|
stateStarting
|
|
stateRunning
|
|
stateStopping
|
|
stateStopped
|
|
stateFailed
|
|
)
|
|
|
|
type registration struct {
|
|
engine Engine
|
|
manifest plugin.Manifest
|
|
// optional marks a provider the daemon can run without. Atomicity is
|
|
// right for a provider archied requires; it is wrong for an external
|
|
// MCP server pulled from a registry at runtime, which is exactly the
|
|
// category that is allowed to be absent.
|
|
optional bool
|
|
}
|
|
|
|
// SkippedProvider is an optional provider that could not be started, and why.
|
|
type SkippedProvider struct {
|
|
ID string
|
|
Err error
|
|
}
|
|
|
|
type runningProvider struct {
|
|
registration registration
|
|
toolNames []string
|
|
}
|
|
|
|
// Registry owns tool-provider registration, lifecycle, and central indexing.
|
|
// The capability host starts and stops the Registry as one typed family module;
|
|
// the Registry, in turn, owns provider ordering and atomic tool availability.
|
|
type Registry struct {
|
|
opMu sync.Mutex
|
|
mu sync.RWMutex
|
|
|
|
index *tools.Registry
|
|
providers map[string]registration
|
|
running []runningProvider
|
|
// skipped records optional providers excluded from the running set.
|
|
// Health reports it: a silent degradation is how one broken npm package
|
|
// went unnoticed until the daemon crash-looped.
|
|
skipped []SkippedProvider
|
|
state registryState
|
|
}
|
|
|
|
// NewRegistry creates a provider registry backed by the central tool index.
|
|
func NewRegistry(index *tools.Registry) *Registry {
|
|
if index == nil {
|
|
index = tools.NewRegistry()
|
|
}
|
|
return &Registry{
|
|
index: index,
|
|
providers: make(map[string]registration),
|
|
}
|
|
}
|
|
|
|
// Register adds an engine the daemon requires. Its failure to start or
|
|
// discover fails the whole family, as before.
|
|
func (r *Registry) Register(engine Engine) error {
|
|
return r.register(engine, false)
|
|
}
|
|
|
|
// RegisterOptional adds an engine the daemon can run without.
|
|
//
|
|
// An optional provider that fails to start or discover is logged, excluded
|
|
// from the running set, and does not roll the family back or stop the daemon.
|
|
// Required/optional is a deployment decision, not a property of the code, so
|
|
// it is stated by the registrar rather than declared in the engine's own
|
|
// manifest.
|
|
func (r *Registry) RegisterOptional(engine Engine) error {
|
|
return r.register(engine, true)
|
|
}
|
|
|
|
func (r *Registry) register(engine Engine, optional bool) error {
|
|
if isNilEngine(engine) {
|
|
return errors.New("tool provider is nil")
|
|
}
|
|
manifest, err := safeManifest(engine)
|
|
if err != nil {
|
|
return err
|
|
}
|
|
if err := manifest.Validate(); err != nil {
|
|
return fmt.Errorf("tool provider manifest: %w", err)
|
|
}
|
|
if !slices.Contains(manifest.Capabilities, toolCapability) {
|
|
return fmt.Errorf("tool provider %q does not declare %q capability", manifest.ID, toolCapability)
|
|
}
|
|
manifest = cloneManifest(manifest)
|
|
|
|
r.mu.Lock()
|
|
defer r.mu.Unlock()
|
|
if r.state != stateIdle {
|
|
return ErrRegistryStarted
|
|
}
|
|
if _, exists := r.providers[manifest.ID]; exists {
|
|
return fmt.Errorf("%w: %q", ErrDuplicateProvider, manifest.ID)
|
|
}
|
|
r.providers[manifest.ID] = registration{engine: engine, manifest: manifest, optional: optional}
|
|
return nil
|
|
}
|
|
|
|
// Skipped returns the optional providers excluded from the running set.
|
|
func (r *Registry) Skipped() []SkippedProvider {
|
|
r.mu.RLock()
|
|
defer r.mu.RUnlock()
|
|
return append([]SkippedProvider(nil), r.skipped...)
|
|
}
|
|
|
|
// Get returns a registered engine by manifest ID.
|
|
func (r *Registry) Get(id string) (Engine, bool) {
|
|
r.mu.RLock()
|
|
defer r.mu.RUnlock()
|
|
registration, ok := r.providers[id]
|
|
return registration.engine, ok
|
|
}
|
|
|
|
// Manifest identifies the tool-provider family to the capability host.
|
|
func (r *Registry) Manifest() plugin.Manifest {
|
|
return plugin.Manifest{
|
|
ID: "archie.tools",
|
|
Name: "Tool providers",
|
|
Version: "1.0.0",
|
|
APIVersion: plugin.HostAPIVersion,
|
|
Capabilities: []plugin.CapabilityKind{toolCapability},
|
|
}
|
|
}
|
|
|
|
// Start starts and discovers registered providers in dependency order. A
|
|
// provider's tools become visible as one atomic batch only after Start and
|
|
// Discover both succeed. Any failure rolls the complete family back.
|
|
func (r *Registry) Start(ctx context.Context) error {
|
|
r.opMu.Lock()
|
|
defer r.opMu.Unlock()
|
|
|
|
r.mu.Lock()
|
|
switch r.state {
|
|
case stateRunning:
|
|
r.mu.Unlock()
|
|
return nil
|
|
case stateIdle:
|
|
r.state = stateStarting
|
|
default:
|
|
state := r.state
|
|
r.mu.Unlock()
|
|
return fmt.Errorf("tool provider registry cannot start from state %d", state)
|
|
}
|
|
providers := cloneRegistrations(r.providers)
|
|
r.mu.Unlock()
|
|
|
|
order, err := dependencyOrder(providers)
|
|
if err != nil {
|
|
r.setFailed(nil)
|
|
return err
|
|
}
|
|
|
|
started := make([]runningProvider, 0, len(order))
|
|
var skipped []SkippedProvider
|
|
unavailable := make(map[string]struct{})
|
|
|
|
for _, id := range order {
|
|
reg := providers[id]
|
|
|
|
// A provider whose dependency was skipped cannot run either. If it
|
|
// is required, that is a hard failure: it declared it cannot work
|
|
// without something now absent, so running it anyway would be worse
|
|
// than not starting.
|
|
if missing, blocked := firstUnavailable(reg, unavailable); blocked {
|
|
cause := fmt.Errorf("tool provider %q depends on unavailable provider %q", id, missing)
|
|
if !reg.optional {
|
|
return r.failFamily(ctx, started, cause)
|
|
}
|
|
unavailable[id] = struct{}{}
|
|
skipped = append(skipped, SkippedProvider{ID: id, Err: cause})
|
|
continue
|
|
}
|
|
|
|
rp, err := r.startProvider(ctx, reg, started)
|
|
if err == nil {
|
|
started = append(started, rp)
|
|
continue
|
|
}
|
|
if !reg.optional {
|
|
// failProvider has already rolled back and set the failed state.
|
|
return err
|
|
}
|
|
// Optional: the provider is out, the family carries on.
|
|
unavailable[id] = struct{}{}
|
|
skipped = append(skipped, SkippedProvider{ID: id, Err: err})
|
|
}
|
|
|
|
r.mu.Lock()
|
|
r.running = started
|
|
r.skipped = skipped
|
|
r.state = stateRunning
|
|
r.mu.Unlock()
|
|
return nil
|
|
}
|
|
|
|
// firstUnavailable reports the first dependency of reg that was skipped.
|
|
func firstUnavailable(reg registration, unavailable map[string]struct{}) (string, bool) {
|
|
for _, dependency := range reg.manifest.Dependencies {
|
|
if _, missing := unavailable[dependency]; missing {
|
|
return dependency, true
|
|
}
|
|
}
|
|
return "", false
|
|
}
|
|
|
|
// failFamily rolls back everything started so far and marks the registry
|
|
// failed, for a failure that is not attributable to one provider's own Start.
|
|
func (r *Registry) failFamily(ctx context.Context, started []runningProvider, cause error) error {
|
|
cleanupCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), cleanupTimeout)
|
|
defer cancel()
|
|
rollbackFailed, rollbackErr := rollback(cleanupCtx, r.index, started)
|
|
r.setFailed(rollbackFailed)
|
|
return errors.Join(cause, rollbackErr)
|
|
}
|
|
|
|
// Stop removes all provider-owned tools before stopping providers in reverse
|
|
// startup order. It continues after provider failures and joins their errors.
|
|
func (r *Registry) Stop(ctx context.Context) error {
|
|
r.opMu.Lock()
|
|
defer r.opMu.Unlock()
|
|
|
|
r.mu.Lock()
|
|
switch r.state {
|
|
case stateStopped:
|
|
r.mu.Unlock()
|
|
return nil
|
|
case stateRunning:
|
|
r.state = stateStopping
|
|
case stateFailed:
|
|
if len(r.running) == 0 {
|
|
r.state = stateStopped
|
|
r.mu.Unlock()
|
|
return nil
|
|
}
|
|
r.state = stateStopping
|
|
case stateIdle:
|
|
r.running = nil
|
|
r.state = stateStopped
|
|
r.mu.Unlock()
|
|
return nil
|
|
default:
|
|
state := r.state
|
|
r.mu.Unlock()
|
|
return fmt.Errorf("tool provider registry cannot stop from state %d", state)
|
|
}
|
|
running := append([]runningProvider(nil), r.running...)
|
|
r.mu.Unlock()
|
|
|
|
var errs []error
|
|
var failed []runningProvider
|
|
for _, current := range slices.Backward(running) {
|
|
|
|
r.index.Unregister(current.toolNames...)
|
|
if err := safeStop(ctx, current.registration.engine); err != nil {
|
|
failed = append(failed, current)
|
|
errs = append(errs, fmt.Errorf(
|
|
"stop tool provider %q: %w",
|
|
current.registration.manifest.ID,
|
|
err,
|
|
))
|
|
}
|
|
}
|
|
|
|
r.mu.Lock()
|
|
r.running = reverseRunning(failed)
|
|
if len(failed) == 0 {
|
|
r.state = stateStopped
|
|
} else {
|
|
r.state = stateFailed
|
|
}
|
|
r.mu.Unlock()
|
|
return errors.Join(errs...)
|
|
}
|
|
|
|
func (r *Registry) setFailed(running []runningProvider) {
|
|
r.mu.Lock()
|
|
r.running = append([]runningProvider(nil), running...)
|
|
r.state = stateFailed
|
|
r.mu.Unlock()
|
|
}
|
|
|
|
// startProvider starts, discovers, and indexes one provider.
|
|
//
|
|
// A required provider's failure rolls back previously-started providers and
|
|
// returns a joined error. An optional provider's failure stops only itself
|
|
// and returns the cause, leaving the family running -- Start decides which,
|
|
// since only the registrar knows whether the daemon needs this provider.
|
|
func (r *Registry) startProvider(ctx context.Context, reg registration, started []runningProvider) (runningProvider, error) {
|
|
id := reg.manifest.ID
|
|
|
|
fail := func(cause error, startedOK bool) (runningProvider, error) {
|
|
if reg.optional {
|
|
return runningProvider{}, r.abandonProvider(ctx, id, reg, cause, startedOK)
|
|
}
|
|
return runningProvider{}, r.failProvider(ctx, id, reg, started, cause)
|
|
}
|
|
|
|
if err := safeStart(ctx, reg.engine); err != nil {
|
|
// Start failed, so there may or may not be anything to stop. Stop is
|
|
// still attempted: a provider that half-started (spawned a child
|
|
// process, opened a pipe) and then errored would otherwise leak it
|
|
// for the daemon's lifetime.
|
|
return fail(fmt.Errorf("start tool provider %q: %w", id, err), true)
|
|
}
|
|
entries, err := safeDiscover(ctx, reg.engine)
|
|
if err != nil {
|
|
return fail(fmt.Errorf("discover tools from provider %q: %w", id, err), true)
|
|
}
|
|
if err := r.index.RegisterBatch(entries); err != nil {
|
|
return fail(fmt.Errorf("index tools from provider %q: %w", id, err), true)
|
|
}
|
|
return runningProvider{
|
|
registration: reg,
|
|
toolNames: namesOf(entries),
|
|
}, nil
|
|
}
|
|
|
|
// abandonProvider stops one failed optional provider and returns why it was
|
|
// excluded. Nothing else is touched: the rest of the family keeps running.
|
|
func (r *Registry) abandonProvider(ctx context.Context, id string, reg registration, cause error, stop bool) error {
|
|
if !stop {
|
|
return cause
|
|
}
|
|
cleanupCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), cleanupTimeout)
|
|
defer cancel()
|
|
return errors.Join(cause, wrapCleanupError(id, safeStop(cleanupCtx, reg.engine)))
|
|
}
|
|
|
|
// failProvider stops the failing provider, rolls back previously-started
|
|
// providers, and returns a joined error.
|
|
func (r *Registry) failProvider(ctx context.Context, id string, reg registration, started []runningProvider, cause error) error {
|
|
cleanupCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), cleanupTimeout)
|
|
defer cancel()
|
|
cleanupErr := safeStop(cleanupCtx, reg.engine)
|
|
rollbackFailed, rollbackErr := rollback(cleanupCtx, r.index, started)
|
|
if cleanupErr != nil {
|
|
rollbackFailed = append(rollbackFailed, runningProvider{registration: reg})
|
|
}
|
|
r.setFailed(rollbackFailed)
|
|
return errors.Join(cause, wrapCleanupError(id, cleanupErr), rollbackErr)
|
|
}
|
|
|
|
func cloneRegistrations(source map[string]registration) map[string]registration {
|
|
clone := make(map[string]registration, len(source))
|
|
for id, value := range source {
|
|
value.manifest = cloneManifest(value.manifest)
|
|
clone[id] = value
|
|
}
|
|
return clone
|
|
}
|
|
|
|
func dependencyOrder(providers map[string]registration) ([]string, error) {
|
|
ids := make([]string, 0, len(providers))
|
|
for id := range providers {
|
|
ids = append(ids, id)
|
|
}
|
|
slices.Sort(ids)
|
|
|
|
indegree := make(map[string]int, len(providers))
|
|
dependents := make(map[string][]string, len(providers))
|
|
for _, id := range ids {
|
|
for _, dependency := range providers[id].manifest.Dependencies {
|
|
if _, exists := providers[dependency]; !exists {
|
|
return nil, fmt.Errorf("tool provider %q depends on missing provider %q", id, dependency)
|
|
}
|
|
indegree[id]++
|
|
dependents[dependency] = append(dependents[dependency], id)
|
|
}
|
|
}
|
|
|
|
var ready []string
|
|
for _, id := range ids {
|
|
if indegree[id] == 0 {
|
|
ready = append(ready, id)
|
|
}
|
|
}
|
|
var order []string
|
|
for len(ready) > 0 {
|
|
id := ready[0]
|
|
ready = ready[1:]
|
|
order = append(order, id)
|
|
slices.Sort(dependents[id])
|
|
for _, dependent := range dependents[id] {
|
|
indegree[dependent]--
|
|
if indegree[dependent] == 0 {
|
|
ready = append(ready, dependent)
|
|
slices.Sort(ready)
|
|
}
|
|
}
|
|
}
|
|
if len(order) != len(providers) {
|
|
return nil, errors.New("tool provider dependency cycle")
|
|
}
|
|
return order, nil
|
|
}
|
|
|
|
func rollback(
|
|
ctx context.Context,
|
|
index *tools.Registry,
|
|
started []runningProvider,
|
|
) ([]runningProvider, error) {
|
|
var errs []error
|
|
var failed []runningProvider
|
|
for _, current := range slices.Backward(started) {
|
|
|
|
index.Unregister(current.toolNames...)
|
|
if err := safeStop(ctx, current.registration.engine); err != nil {
|
|
failed = append(failed, current)
|
|
errs = append(errs, fmt.Errorf(
|
|
"rollback tool provider %q: %w",
|
|
current.registration.manifest.ID,
|
|
err,
|
|
))
|
|
}
|
|
}
|
|
return reverseRunning(failed), errors.Join(errs...)
|
|
}
|
|
|
|
func reverseRunning(values []runningProvider) []runningProvider {
|
|
out := append([]runningProvider(nil), values...)
|
|
slices.Reverse(out)
|
|
return out
|
|
}
|
|
|
|
func wrapCleanupError(id string, err error) error {
|
|
if err == nil {
|
|
return nil
|
|
}
|
|
return fmt.Errorf("clean up failed tool provider %q: %w", id, err)
|
|
}
|
|
|
|
func namesOf(entries []tools.ToolEntry) []string {
|
|
names := make([]string, len(entries))
|
|
for i, entry := range entries {
|
|
names[i] = entry.Name
|
|
}
|
|
return names
|
|
}
|
|
|
|
func cloneManifest(manifest plugin.Manifest) plugin.Manifest {
|
|
clone := manifest
|
|
clone.Capabilities = append([]plugin.CapabilityKind(nil), manifest.Capabilities...)
|
|
clone.Dependencies = append([]string(nil), manifest.Dependencies...)
|
|
clone.Permissions = append([]plugin.Permission(nil), manifest.Permissions...)
|
|
clone.ConfigSchema = append([]byte(nil), manifest.ConfigSchema...)
|
|
return clone
|
|
}
|
|
|
|
func isNilEngine(engine Engine) bool {
|
|
if engine == nil {
|
|
return true
|
|
}
|
|
value := reflect.ValueOf(engine)
|
|
switch value.Kind() {
|
|
case reflect.Chan, reflect.Func, reflect.Interface, reflect.Map, reflect.Pointer, reflect.Slice:
|
|
return value.IsNil()
|
|
default:
|
|
return false
|
|
}
|
|
}
|
|
|
|
func safeManifest(engine Engine) (manifest plugin.Manifest, err error) {
|
|
defer func() {
|
|
if recovered := recover(); recovered != nil {
|
|
err = fmt.Errorf("tool provider manifest panic: %v", recovered)
|
|
}
|
|
}()
|
|
return engine.Manifest(), nil
|
|
}
|
|
|
|
func safeStart(ctx context.Context, engine Engine) (err error) {
|
|
defer func() {
|
|
if recovered := recover(); recovered != nil {
|
|
err = fmt.Errorf("panic: %v", recovered)
|
|
}
|
|
}()
|
|
return engine.Start(ctx)
|
|
}
|
|
|
|
func safeDiscover(ctx context.Context, engine Engine) (entries []tools.ToolEntry, err error) {
|
|
defer func() {
|
|
if recovered := recover(); recovered != nil {
|
|
err = fmt.Errorf("panic: %v", recovered)
|
|
}
|
|
}()
|
|
return engine.Discover(ctx)
|
|
}
|
|
|
|
func safeStop(ctx context.Context, engine Engine) (err error) {
|
|
defer func() {
|
|
if recovered := recover(); recovered != nil {
|
|
err = fmt.Errorf("panic: %v", recovered)
|
|
}
|
|
}()
|
|
return engine.Stop(ctx)
|
|
}
|