plugin

type CLIProvider ¶

type CLIProvider interface {
	Plugin

	// CLIRegistrars returns the CLIRegistrars provided by this plugin.
	CLIRegistrars() []CLIRegistrar
}

CLIProvider is an optional plugin interface for plugins that provide CLI commands. This corresponds to openclaw's registerCli() capability.

type CLIRegistrar ¶

type CLIRegistrar interface {
	// RegisterCommands adds subcommands to the given parent command
	RegisterCommands(parent *cobra.Command)
}

CLIRegistrar is the interface for plugins that register CLI commands. This corresponds to openclaw's registerCli() capability.

type Code ¶

type Code int

Code is a status code returned by plugin operations. Modeled after K8s scheduler framework's Code type.

const (
	// Success means the plugin operation completed successfully.
	Success Code = iota
	// Error means the plugin encountered a fatal error.
	Error
	// Skip means the plugin chose to skip this operation.
	Skip
	// Unschedulable means the operation cannot be completed (K8s terminology).
	Unschedulable
)

func (c Code) String() string

type CompletedConfig ¶

type CompletedConfig struct {
	*Config
}

CompletedConfig is the validated and completed framework configuration.

func (c CompletedConfig) New() *Framework

type Config ¶

type Config struct {
	// SlotConfig controls which plugins are active per slot kind.
	SlotConfig SlotConfig

	// RuntimeAPI provides plugins access to core modules.
	RuntimeAPI RuntimeAPI
}

Config holds the configuration for creating a Framework. Follows the K8s Config → Complete() → New() pattern.

func (c *Config) Complete() CompletedConfig

type Definition ¶

type Definition struct {
	ID          string
	Name        string
	Kind        string
	Description string
}

Definition is the static metadata for a plugin. It is used to register plugins into the framework.

type Framework ¶

type Framework struct {
	// contains filtered or unexported fields
}

Framework is the core plugin framework that manages plugin lifecycle. It orchestrates: plugin loading → slot resolution → Init → Start → Stop.

This is modeled after K8s scheduler's frameworkImpl, which: 1. Holds the plugin registry 2. Manages plugin instantiation via factories 3. Drives the scheduling cycle (in our case, plugin lifecycle)

The Framework implements the Handle interface, so plugins can access shared runtime resources through it.

func (f *Framework) Handle() Handle

func (f *Framework) Init() error

func (f *Framework) PromptPipeline() *prompt.Pipeline

func (f *Framework) RegisterFactory(def Definition, factory PluginFactory, args PluginArgs) error

func (f *Framework) Registry() *Registry

func (f *Framework) SetPromptPipeline(pipeline *prompt.Pipeline)

func (f *Framework) Start(ctx context.Context) error

func (f *Framework) Stop(ctx context.Context) error

type Handle ¶

type Handle interface {
	// RuntimeAPI returns the framework's runtime API.
	// This is used to access services, tools, and other plugins.
	RuntimeAPI() RuntimeAPI
}

Handle is the interface that plugins use to access the framework's runtime API. It is passed to the PluginFactory during plugin instantiation.

type HookEvent ¶

type HookEvent string

HookEvent identifies a lifecycle event that plugins can subscribe to. This corresponds to OpenClaw's typed lifecycle hooks (on()).

const (
	// HookServerStart is fired when the hivemind server starts.
	HookServerStart HookEvent = "server_start"

	// HookServerStop is fired during graceful shutdown.
	HookServerStop HookEvent = "server_stop"

	// HookBeforeAgentStart is fired before an Agent session begins.
	// Plugins can inject context (e.g., memory recall) here.
	HookBeforeAgentStart HookEvent = "before_agent_start"

	// HookAgentEnd is fired after an Agent session ends.
	// Plugins can capture/persist data (e.g., memory flush) here.
	HookAgentEnd HookEvent = "agent_end"

	// HookBeforeGenerate is fired before LLM generation.
	HookBeforeGenerate HookEvent = "before_generate"

	// HookAfterGenerate is fired after LLM generation completes.
	HookAfterGenerate HookEvent = "after_generate"

	// HookBeforeCompaction is fired before compaction is about to run.
	// Plugin can perform pre-compaction actions (e.g., LLM-driven memory flush.)
	// Data: {"agent", "session", "window_info", "chat_model"}
	HookBeforeCompaction HookEvent = "before_compaction"

	// HookAfterCompaction is fired after compaction completes successfully.
	// Plugins can perform post-compaction actions (e.g., workspace context refresh.)
	// Data: {"agent", "session", "summary", "compaction_count"}
	HookAfterCompaction HookEvent = "after_compaction"
)

type HookHandler ¶

type HookHandler func(ctx context.Context, data interface{}) error

HookHandler is the callback function for lifecycle hooks. The data parameter is event-specific; plugins should type-assert as needed.

type HookProvider ¶

type HookProvider interface {
	Plugin
	// Hooks returns a mapping of events to handlers.
	Hooks() map[HookEvent]HookHandler
}

HookProvider is an optional plugin interface for plugins that want to register hooks declaratively. The framework probes for this interface and auto-registers the hooks.

type InTreeRegistry ¶

type InTreeRegistry struct {
	// contains filtered or unexported fields
}

InTreeRegistry is a pre-configured set of built-in plugin factories. This mirrors K8s scheduler's in-tree plugin registration pattern, where all default plugins are registered in a single function.

Out-of-tree plugins can be added via Framework.RegisterFactory() directly.

func NewInTreeRegistry() *InTreeRegistry

func (r *InTreeRegistry) ApplyTo(f *Framework) error

func (r *InTreeRegistry) Len() int

func (r *InTreeRegistry) Register(def Definition, factory PluginFactory, args PluginArgs)

type InitPlugin ¶

type InitPlugin interface {
	Plugin

	// Init is called after the plugin is instantiated, allowing it
	// to register Tool/Cli/Hook/Service capabilities via the PluginAPI.
	Init(api PluginAPI) error
}

InitPlugin is an optional interface for plugins that need initialization with access to the pluginAPI, called during framework setup

type LifecyclePlugin ¶

type LifecyclePlugin interface {
	Plugin

	// Start is called when the framework is initializing,
	// after all plugins have been registered.
	Start(ctx context.Context) error

	// Stop is called when the framework is shutting down,
	// before plugins are unregistered.
	Stop(ctx context.Context) error
}

LifecyclePlugin is an optional interface for plugins that have start/stop lifecycle

type ModelManager ¶

type ModelManager interface {
	// GetChatModel returns a chat model by provider ID and model ID.
	// Return nil if the model is not found.
	GetChatModel(ctx context.Context, provideID, modelID string) (model.BaseChatModel, error)

	// GetDefaultChatModel returns the default chat model for the current runtime.
	// Return nil if the default model is not set.
	GetDefaultChatModel(ctx context.Context) (model.BaseChatModel, error)
}

ModelManager is a plugin-facing subset of the LLM ModelManager interface. It exposes only the capabilities that plugins need, decoupling the plugin package from the full llm/domain/service.ModelManager.

type ParameterDef ¶

type ParameterDef struct {
	// Name is the parameter's unique name. (e.g. "query")
	Name string
	// Type is the parameter's data type. (e.g. "string", "number", "object")
	Type string
	// Description is a brief description of the parameter's purpose.
	Description string
	// Required indicates whether the parameter is mandatory.
	Required bool
}

ParameterDef defines a single parameter for a tool.

type Plugin ¶

type Plugin interface {
	// Name returns the unique identifier of this plugin.
	// Must be DNS-compatible (lowercase, hyphens, no spaces).
	Name() string
}

Plugin is the fundamental interface that all plugins must implement. Each Plugin has a static definition and registers its capabilities via the PluginAPI during the Register phase

type PluginAPI ¶

type PluginAPI interface {
	// RegisterTool registers an Agent-callable tool.
	RegisterTool(tool ToolDefinition)

	// RegisterCLI registers a CLI subcommand registrar.
	RegisterCLI(registrar CLIRegistrar)

	// RegisterHook registers a lifecycle event hook.
	RegisterHook(event HookEvent, handler HookHandler)

	// RegisterService registers a background service with Start/Stop lifecycle.
	RegisterService(svc ServiceDefinition)
}

PluginAPI is the registration interface given to plugins during Init(). Through this API, plugins register their capabilities: Tool, CLI, Hook, Service.

This corresponds to OpenClaw's OpenClawPluginApi with registerTool(), registerCli(), registerHook/on(), registerService().

type PluginArgs ¶

type PluginArgs map[string]interface{}

PluginArgs is a map of arguments passed to the PluginFactory. These arguments are typically configuration values or dependencies.

type PluginFactory ¶

type PluginFactory func(args PluginArgs, handle Handle) (Plugin, error)

PluginFactory is a function that creates a new instance of a plugin. It is called during framework initialization, after all plugins have been registered.

type PromptMutatorProvider ¶

type PromptMutatorProvider interface {
	Plugin

	// PromptMutators returns the PromptMutators contributed by this plugin.
	// These are registered into the shared Pipeline during framework init.
	PromptMutators() []prompt.PromptMutator
}

PromptMutatorProvider is an optional plugin interface for plugins that want to contribute PromptMutators to the system prompt pipeline.

PromptMutators returns the PromptMutators contributed by this plugin. These are registered into the shared Pipeline during framework init.

type PromptProvider ¶

type PromptProvider interface {
	Plugin

	// PromptSections returns the PromptSections contributed by this plugin.
	// These are registered into the shared Pipeline during framework init.
	PromptSections() []prompt.PromptSection
}

PromptProvider is an optional plugin interface for plugins that want to contribute PromptSections and/or PromptMutators to the system prompt pipeline.

This is the fifth capability injection channel, alongside:

• ToolProvider (tools for Agent to call)
• HookProvider (lifecycle hooks)
• ServiceProvider (background services)
• CLIProvider (CLI commands)

The framework probes for this interface during Init() and auto-registers sections/mutators into the shared PromptPipeline.

type Registry ¶

type Registry struct {
	// contains filtered or unexported fields
}

Registry is the central plugin registry that holds all loaded plugins and their registered capabilities (tools, CLI, hooks, services).

This follows K8s scheduler's frameworkImpl pattern: the framework maintains ordered lists of plugins per extension point.

Thread-safe: all mutations are guarded by a mutex.

func NewRegistry() *Registry

func (r *Registry) GetHooks(event HookEvent) []HookHandler

func (r *Registry) GetPlugin(name string) (Plugin, bool)

func (r *Registry) GetServices() []ServiceDefinition

func (r *Registry) GetTools() map[string]ToolDefinition

func (r *Registry) Len() int

func (r *Registry) PluginNames() []string

func (r *Registry) RegisterCLICommands(parent *cobra.Command)

type RuntimeAPI ¶

type RuntimeAPI interface {
	// ModelManager returns the LLM model manager for building/retrieving chat models.
	// Return nil if the LLM module is not available.
	ModelManager() ModelManager
}

RuntimeAPI is the bridge between plugins and core runtime modules. Plugins access core capabilities (LLM, Memory, etc.) through this interface.

func NewRuntimeAPI(modelManager ModelManager) RuntimeAPI

type ServiceDefinition ¶

type ServiceDefinition struct {
	// Name is the service's unique name.
	Name string

	// Start launches the service. It should be non-blocking
	Start func(ctx context.Context) error
	// Stop gracefully shuts down the service. It should be non-blocking.
	Stop func(ctx context.Context) error
}

ServiceDefinition describes a background service registered by a plugin. Service have a Start/Stop lifecycle managed by the framework.

type ServiceProvider ¶

type ServiceProvider interface {
	Plugin
	// Services returns the list of background services provided by the plugin.
	Services() []ServiceDefinition
}

ServiceProvider is an optional plugin interface that allows plugins to register background services. The framework probes for this interface when loading plugins.

type SlotConfig ¶

type SlotConfig map[string]string

SlotConfig maps slot kind → desired plugin name. For example: {"memory": "memory-core"} means only the "memory-core" plugin should be active for the "memory" slot.

Special values:

• "none": disable all plugins of this kind
• "": use the default plugin for this kind

type Status ¶

type Status struct {
	// contains filtered or unexported fields
}

Status indicates the result of running a plugin operation. This is modeled after K8s scheduler framework's Status type.

func NewStatus(code Code, reasons ...string) *Status

func NewStatusWithError(err error) *Status

func (s *Status) AsError() error

func (s *Status) Code() Code

func (s *Status) Err() error

func (s *Status) IsSuccess() bool

func (s *Status) Message() string

func (s *Status) WithPlugin(name string) *Status

type ToolDefinition ¶

type ToolDefinition struct {
	// Name is the tool's unique name. (e.g. "memory_search")
	Name string
	// Description is a brief description of the tool's purpose.
	Description string
	// Parameters defines the input schema for the tool.
	Parameters []ParameterDef
	// Handler is the function that is called when the tool is invoked.
	Handler ToolHandler
}

ToolDefinition describes a tool registered by a plugin. Tools have a single Handler function that is called when the tool is invoked. Tools are invoked by the Agent to perform actions.

type ToolHandler ¶

type ToolHandler func(ctx context.Context, params map[string]interface{}) (interface{}, error)

ToolHandler is the function that is called when the tool is invoked. It receives the context and a map of parameter values, and returns the result or an error.

type ToolProvider ¶

type ToolProvider interface {
	Plugin
	// Tools returns the Tools contributed by this plugin.
	// These are registered into the shared ToolRegistry during framework init.
	Tools() []ToolDefinition
}

ToolProvider is an optional plugin interface for plugins that want to contribute Tools to the system.

Tools are invoked by the Agent to perform actions.

Tools are registered into the shared ToolRegistry during framework init.