Struct PluginRegistry 

pub struct PluginRegistry { /* private fields */ }

Manages registered plugin instances and hook handler mappings.

Stores PluginRef wrappers by name and HookEntry (PluginRef + handler) by hook name. The executor reads scheduling decisions from PluginRef.trusted_config and dispatches through the type-erased handler.

Supports two registration patterns:

• register::<H>() — typed registration for a single hook name (derived from H::NAME).
• register_for_names::<H>() — typed registration for multiple hook names (the CMF pattern where one handler covers cmf.tool_pre_invoke, cmf.llm_input, etc.).

Clone is cheap-ish: the HashMaps duplicate, but their values are all Arc-counted (Arc<PluginRef>, Arc<dyn AnyHookHandler>), so the inner data is shared. Used by PluginManager’s ArcSwap snapshot pattern, where every mutating method clones the registry, mutates the clone, and atomically swaps in a new snapshot.

Implementations

impl PluginRegistry

pub fn new() -> Self

Create an empty registry.

pub fn register<H: HookTypeDef>( &mut self, plugin: Arc<dyn Plugin>, config: PluginConfig, handler: Arc<dyn AnyHookHandler>, ) -> Result<(), String>

Register a typed hook handler for its primary hook name.

The handler is registered under H::NAME. The config must come from the config loader — not from the plugin. The plugin must implement the handler trait generated by define_hook!.

Type Parameters

• H — the hook type (implements HookTypeDef).

Arguments

• plugin — the plugin implementation (must also implement the handler trait).
• config — authoritative config from the config loader.
• handler — type-erased handler wrapping the plugin’s handler trait impl.

pub fn register_for_names<H: HookTypeDef>( &mut self, plugin: Arc<dyn Plugin>, config: PluginConfig, handler: Arc<dyn AnyHookHandler>, names: &[&str], ) -> Result<(), String>

Register a typed hook handler for multiple hook names.

This is the CMF pattern — one handler trait impl covers multiple hook names (cmf.tool_pre_invoke, cmf.llm_input, etc.).

Arguments

• plugin — the plugin implementation.
• config — authoritative config from the config loader.
• handler — type-erased handler.
• names — hook names to register under.

pub fn register_for_names_with_handler( &mut self, plugin: Arc<dyn Plugin>, config: PluginConfig, handler: Arc<dyn AnyHookHandler>, names: &[&str], ) -> Result<(), String>

Register a plugin with a handler for multiple hook names.

Like register_for_names but without requiring a HookTypeDef type parameter. Used by the config-driven factory path where the hook type is not known at compile time — the factory provides the handler directly.

pub fn register_multi_handler( &mut self, plugin: Arc<dyn Plugin>, config: PluginConfig, handlers: Vec<(&str, Arc<dyn AnyHookHandler>)>, ) -> Result<(), String>

Register a plugin with multiple handlers, each for a specific hook.

Used when a plugin implements multiple hook types with different payloads (e.g., ToolPreInvoke and ToolPostInvoke). Each handler is registered under its paired hook name.

The plugin is registered once in the name index. Each handler gets its own HookEntry in the hook index under the specified name.

pub fn unregister(&mut self, name: &str) -> Option<Arc<PluginRef>>

Unregister a plugin by name.

Removes the PluginRef from the name index and all HookEntries from the hook index. Returns the (Arc-wrapped) PluginRef if found.

pub fn get(&self, name: &str) -> Option<Arc<PluginRef>>

Look up a PluginRef by name. Returns an Arc clone so callers don’t hold borrows on internal storage — works with snapshot-based dispatch where the registry may sit behind a transient guard.

pub fn entries_for_hook(&self, hook_type: &HookType) -> &[HookEntry]

Returns all HookEntries for a given hook name, sorted by priority.

Returns an empty slice if no plugins are registered for the hook.

pub fn has_hooks_for(&self, hook_type: &HookType) -> bool

Whether any plugins are registered for the given hook name.

pub fn plugin_count(&self) -> usize

Total number of registered plugins.

pub fn plugin_names(&self) -> Vec<String>

All registered plugin names. Returns owned Strings so callers don’t hold borrows on internal storage — works with snapshot-based dispatch where the registry may sit behind a transient guard.

pub fn entries_for_plugin(&self, plugin_name: &str) -> Vec<(String, HookEntry)>

Returns every (hook_name, HookEntry) pair where the entry’s plugin matches the given name. Used by external orchestrators that need to build pre-resolved dispatch lineups for a single plugin across every hook it registered to (e.g. apl-cpex deciding which entry handles step-style invocations vs field-style invocations for the same plugin). Owned tuples — no borrows held on the registry.

Trait Implementations

impl Clone for PluginRegistry

fn clone(&self) -> PluginRegistry

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for PluginRegistry

fn default() -> Self

Returns the “default value” for a type.