plugin

Documentation

Index

• func CreateDefaultPluginsDir(workingDir string) error
• type AgentDef
• type HookDef
• type Loader
  • func NewLoader(workingDir string) *Loader
  • func NewLoaderWithDir(pluginsDir string) *Loader
  • func (l *Loader) Discover() ([]*Manifest, error)
  • func (l *Loader) FilterByType(pluginType PluginType) []*Plugin
  • func (l *Loader) Get(name string) (*Plugin, bool)
  • func (l *Loader) GetAgents() []*Plugin
  • func (l *Loader) GetHooks() []*Plugin
  • func (l *Loader) GetTools() []*Plugin
  • func (l *Loader) Install(sourceDir string) (*Manifest, error)
  • func (l *Loader) List() []*Plugin
  • func (l *Loader) LoadAll() ([]*Plugin, error)
  • func (l *Loader) LoadPlugin(manifest *Manifest) (*Plugin, error)
  • func (l *Loader) Uninstall(name string) error
  • func (l *Loader) Unload(name string) error
  • func (l *Loader) UnloadAll()
• type Manifest
  • func LoadManifest(dir string) (*Manifest, error)
  • func (m *Manifest) CheckCompatibility() error
  • func (m *Manifest) EntryPath() string
  • func (m *Manifest) HasPermission(perm string) bool
  • func (m *Manifest) IsCommandAllowed(cmd string) bool
  • func (m *Manifest) IsPathAllowed(path string) bool
  • func (m *Manifest) MaxMemoryBytes() int64
  • func (m *Manifest) TimeoutDuration() time.Duration
  • func (m *Manifest) Validate() error
• type Permissions
• type Plugin
• type PluginType
• type Runtime
  • func NewRuntime(manifest *Manifest) (*Runtime, error)
  • func (r *Runtime) Execute(ctx context.Context, input string) (string, error)
  • func (r *Runtime) ExecuteScript(ctx context.Context, scriptPath string, args ...string) (string, error)
  • func (r *Runtime) IsStopped() bool
  • func (r *Runtime) Stop()
• type ToolDef

Functions

func CreateDefaultPluginsDir

func CreateDefaultPluginsDir(workingDir string) error

CreateDefaultPluginsDir creates the default plugins directory if it doesn't exist.

Types

type AgentDef

type AgentDef struct {
	Name         string            `json:"name"`
	Description  string            `json:"description"`
	SystemPrompt string            `json:"system_prompt,omitempty"`
	Model        string            `json:"model,omitempty"`
	Tools        []string          `json:"tools,omitempty"`
	Env          map[string]string `json:"env,omitempty"`
}

AgentDef defines an agent provided by a plugin.

type HookDef

type HookDef struct {
	Name    string `json:"name"`
	Trigger string `json:"trigger"`
	Script  string `json:"script,omitempty"`
}

HookDef defines a hook that a plugin can register.

type Loader

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

Loader discovers, validates, and manages plugins.

func NewLoader

func NewLoader(workingDir string) *Loader

NewLoader creates a new plugin loader.

func NewLoaderWithDir

func NewLoaderWithDir(pluginsDir string) *Loader

NewLoaderWithDir creates a new plugin loader with a custom plugins directory.

func (*Loader) Discover

func (l *Loader) Discover() ([]*Manifest, error)

Discover scans the plugins directory and returns found plugins.

func (*Loader) FilterByType

func (l *Loader) FilterByType(pluginType PluginType) []*Plugin

FilterByType returns plugins of a specific type.

func (*Loader) Get

func (l *Loader) Get(name string) (*Plugin, bool)

Get returns a loaded plugin by name.

func (*Loader) GetAgents

func (l *Loader) GetAgents() []*Plugin

GetAgents returns all agent-type plugins.

func (*Loader) GetHooks

func (l *Loader) GetHooks() []*Plugin

GetHooks returns all hook-type plugins.

func (*Loader) GetTools

func (l *Loader) GetTools() []*Plugin

GetTools returns all tool-type plugins.

func (*Loader) Install

func (l *Loader) Install(sourceDir string) (*Manifest, error)

Install installs a plugin from a directory.

func (*Loader) List

func (l *Loader) List() []*Plugin

List returns all loaded plugins.

func (*Loader) LoadAll

func (l *Loader) LoadAll() ([]*Plugin, error)

LoadAll discovers and loads all plugins.

func (*Loader) LoadPlugin

func (l *Loader) LoadPlugin(manifest *Manifest) (*Plugin, error)

LoadPlugin loads a single plugin from its manifest.

func (*Loader) Uninstall

func (l *Loader) Uninstall(name string) error

Uninstall removes a plugin by name.

func (*Loader) Unload

func (l *Loader) Unload(name string) error

Unload unloads a plugin by name.

func (*Loader) UnloadAll

func (l *Loader) UnloadAll()

UnloadAll unloads all plugins.

type Manifest

type Manifest struct {
	Name        string     `json:"name"`
	Version     string     `json:"version"`
	Description string     `json:"description,omitempty"`
	Author      string     `json:"author,omitempty"`
	License     string     `json:"license,omitempty"`
	Homepage    string     `json:"homepage,omitempty"`
	Type        PluginType `json:"type"`
	Icon        string     `json:"icon,omitempty"`

	// Entry points
	Main       string `json:"main,omitempty"`
	Entrypoint string `json:"entrypoint,omitempty"`

	// Runtime configuration
	Runtime string            `json:"runtime,omitempty"`
	Args    []string          `json:"args,omitempty"`
	Env     map[string]string `json:"env,omitempty"`
	Timeout time.Duration     `json:"timeout,omitempty"`

	// Permissions
	Permissions Permissions `json:"permissions,omitempty"`

	// Hooks (for hook-type plugins)
	Hooks []HookDef `json:"hooks,omitempty"`

	// Tool definition (for tool-type plugins)
	ToolDef *ToolDef `json:"tool,omitempty"`

	// Agent definition (for agent-type plugins)
	AgentDef *AgentDef `json:"agent,omitempty"`

	// Dependencies
	Dependencies map[string]string `json:"dependencies,omitempty"`

	// Compatibility
	MinGhostVersion string   `json:"min_ghost_version,omitempty"`
	MaxGhostVersion string   `json:"max_ghost_version,omitempty"`
	OS              []string `json:"os,omitempty"`
	Arch            []string `json:"arch,omitempty"`

	// Internal state
	InstallPath string `json:"-"`
	Enabled     bool   `json:"-"`
	Loaded      bool   `json:"-"`
	LoadError   string `json:"-"`
}

Manifest defines the plugin metadata and configuration.

func LoadManifest

func LoadManifest(dir string) (*Manifest, error)

LoadManifest reads and validates a plugin manifest from the given directory.

func (*Manifest) CheckCompatibility

func (m *Manifest) CheckCompatibility() error

CheckCompatibility checks if the plugin is compatible with the current environment.

func (*Manifest) EntryPath

func (m *Manifest) EntryPath() string

EntryPath returns the path to the plugin's entrypoint script.

func (*Manifest) HasPermission

func (m *Manifest) HasPermission(perm string) bool

HasPermission checks if the plugin has a specific permission.

func (*Manifest) IsCommandAllowed

func (m *Manifest) IsCommandAllowed(cmd string) bool

IsCommandAllowed checks if a command is in the plugin's allowed commands.

func (*Manifest) IsPathAllowed

func (m *Manifest) IsPathAllowed(path string) bool

IsPathAllowed checks if a file path is within the plugin's allowed paths.

func (*Manifest) MaxMemoryBytes

func (m *Manifest) MaxMemoryBytes() int64

MaxMemory returns the plugin's memory limit in bytes.

func (*Manifest) TimeoutDuration

func (m *Manifest) TimeoutDuration() time.Duration

Timeout returns the plugin's execution timeout with a default fallback.

func (*Manifest) Validate

func (m *Manifest) Validate() error

Validate checks that the manifest has all required fields.

type Permissions

type Permissions struct {
	Network      bool          `json:"network,omitempty"`
	FileSystem   bool          `json:"filesystem,omitempty"`
	AllowedPaths []string      `json:"allowed_paths,omitempty"`
	EnvVars      []string      `json:"allowed_env,omitempty"`
	Commands     []string      `json:"allowed_commands,omitempty"`
	MaxMemoryMB  int           `json:"max_memory_mb,omitempty"`
	MaxTimeout   time.Duration `json:"max_timeout,omitempty"`
}

Permissions defines what a plugin is allowed to do.

type Plugin

type Plugin struct {
	Manifest *Manifest
	Runtime  *Runtime
}

Plugin holds a loaded plugin with its runtime state.

type PluginType

type PluginType string

PluginType defines the type of plugin.

const (
	PluginTypeTool   PluginType = "tool"
	PluginTypeHook   PluginType = "hook"
	PluginTypeTheme  PluginType = "theme"
	PluginTypeScript PluginType = "script"
	PluginTypeAgent  PluginType = "agent"
)

type Runtime

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

Runtime manages the execution environment for a plugin.

func NewRuntime

func NewRuntime(manifest *Manifest) (*Runtime, error)

NewRuntime creates a new runtime for a plugin.

func (*Runtime) Execute

func (r *Runtime) Execute(ctx context.Context, input string) (string, error)

Execute runs the plugin's entrypoint with the given input.

func (*Runtime) ExecuteScript

func (r *Runtime) ExecuteScript(ctx context.Context, scriptPath string, args ...string) (string, error)

ExecuteScript runs an arbitrary script from the plugin directory.

func (*Runtime) IsStopped

func (r *Runtime) IsStopped() bool

IsStopped returns whether the runtime is stopped.

func (*Runtime) Stop

func (r *Runtime) Stop()

Stop gracefully stops the plugin runtime.

type ToolDef

type ToolDef struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	Parameters  string `json:"parameters,omitempty"`
	Script      string `json:"script,omitempty"`
}

ToolDef defines a tool provided by a plugin.