// Package provider defines the typed tool-provider capability family. package provider import ( "context" "errors" "fmt" "maps" "slices" "sync" "time" "github.com/samcharles93/archie-core/internal/domain/lifecycle" "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) } // prepareRegistration validates an engine and builds its registration, the // validation Register, Add and Replace all share. func prepareRegistration(engine Engine, optional bool) (registration, error) { if lifecycle.IsNil(engine) { return registration{}, errors.New("tool provider is nil") } manifest, err := safeManifest(engine) if err != nil { return registration{}, err } if err := manifest.Validate(); err != nil { return registration{}, fmt.Errorf("tool provider manifest: %w", err) } if !slices.Contains(manifest.Capabilities, toolCapability) { return registration{}, fmt.Errorf("tool provider %q does not declare %q capability", manifest.ID, toolCapability) } return registration{engine: engine, manifest: cloneManifest(manifest), optional: optional}, nil } // RegisterOptional adds a provider whose failure is logged and excluded // rather than fatal. func (r *Registry) RegisterOptional(engine Engine) error { return r.register(engine, true) } func (r *Registry) register(engine Engine, optional bool) error { reg, err := prepareRegistration(engine, optional) if err != nil { return err } r.mu.Lock() defer r.mu.Unlock() if r.state != stateIdle { return ErrRegistryStarted } if _, exists := r.providers[reg.manifest.ID]; exists { return fmt.Errorf("%w: %q", ErrDuplicateProvider, reg.manifest.ID) } r.providers[reg.manifest.ID] = reg 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 and indexes one provider. A required failure rolls // back the started providers; an optional one stops only itself. 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 := slices.Sorted(maps.Keys(providers)) 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 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) }