BeamAgent.Plugins (beam_agent_ex v0.1.0)

Copy Markdown View Source

Plugin management for the BeamAgent SDK.

This module provides global plugin registration -- listing, registering, unregistering, and querying plugins that are shared across all sessions. Mutations notify the reload bus so live sessions react without restart.

When to use directly vs through BeamAgent

Most callers interact with plugins through BeamAgent. Use this module directly when you need focused access to plugin operations -- for example, in a plugin management UI, a plugin marketplace browser, or a configuration tool that bulk-enables/disables plugins.

Quick example

# Register a plugin:
:ok = BeamAgent.Plugins.register("my-plugin", %{
  name: "My Plugin",
  description: "Does cool stuff",
  version: "1.0.0",
  enabled: true
})

# List all plugins:
plugins = BeamAgent.Plugins.list()
for p <- plugins, do: IO.puts(p.name)

# Unregister:
:ok = BeamAgent.Plugins.unregister("my-plugin")

Architecture deep dive

This module is a thin Elixir facade that delegates every call to the :beam_agent_catalog Erlang module's global registry functions. Zero business logic, zero state, zero processes live here -- the Erlang module owns the implementation. The underlying plugin data is stored in the unified ETS table managed by :beam_agent_registry.

See also: BeamAgent, BeamAgent.Catalog, BeamAgent.Agents.

Summary

Types

plugin_def()

A plugin definition stored in the global registry.

Functions

clear()

Remove all registered plugins.

ensure_table()

Create the global registry ETS table. Idempotent.

get(id)

Fetch a single plugin by id.

list()

List all registered plugins.

register(id, opts)

Register a plugin globally (shared across all sessions).

unregister(id)

Unregister a plugin by id. Idempotent.

Types

plugin_def()

@type plugin_def() :: %{
  :id => binary(),
  :name => binary(),
  :kind => :agent | :plugin | :slash,
  :enabled => boolean(),
  optional(:description) => binary(),
  optional(:version) => binary(),
  optional(:config) => map()
}

A plugin definition stored in the global registry.

Functions

clear()

@spec clear() :: :ok

Remove all registered plugins.

ensure_table()

@spec ensure_table() :: :ok

Create the global registry ETS table. Idempotent.

get(id)

@spec get(binary()) :: {:ok, plugin_def()} | {:error, :not_found}

Fetch a single plugin by id.

list()

@spec list() :: [plugin_def()]

List all registered plugins.

register(id, opts)

@spec register(binary(), map()) :: :ok

Register a plugin globally (shared across all sessions).

Parameters

  • id -- unique binary identifier for the plugin.
  • opts -- map of plugin options (:name, :description, :version, :enabled, :config).

unregister(id)

@spec unregister(binary()) :: :ok

Unregister a plugin by id. Idempotent.