plugins

package
v0.0.0-beta Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 30, 2026 License: MIT Imports: 35 Imported by: 0

Documentation

Overview

Package plugins provides Yaegi-based Go plugin loading for conversation hooks.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AssignHook 

func AssignHook(h *Hook, timing injector.Timing, iface any) error

AssignHook type-asserts iface and assigns to the appropriate function field on h.

func BuildSDKContext 

func BuildSDKContext(state *injector.State) sdk.Context

BuildSDKContext converts injector.State to the SDK Context type.

func DispatchHook 

func DispatchHook(h *Hook, ctx context.Context, state *injector.State, sdkCtx sdk.Context) (sdk.Result, error)

DispatchHook calls the appropriate hook function based on timing. BeforeToolExecution is NOT dispatched here — it has a separate CheckBeforeTool() path that returns BeforeToolCheckItem (not sdk.Result). Check() returns nil for that timing.

func IsSDKCompatible 

func IsSDKCompatible(pluginVersion, hostVersion string) error

IsSDKCompatible checks whether the host SDK version satisfies the plugin's requirement using tilde-range matching. A plugin vendoring SDK 0.1.0 is compatible with any host 0.1.x (same minor, patch >= plugin's patch).

Returns nil when pluginVersion is empty (in-repo plugins without a vendored SDK).

func KnownTimingNames 

func KnownTimingNames() []struct {
	Name   string
	Timing injector.Timing
}

KnownTimingNames returns the ordered list of timing names for plugin probing.

func Vendor 

func Vendor(dir string) error

Vendor runs "go mod tidy && go mod vendor" in dir. Requires the Go toolchain to be available in PATH.

Types

type Cache 

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

Cache holds all loaded plugins for a session. It owns a shared temp GOPATH used by all plugin interpreters (following Traefik's Manager pattern).

func LoadAll 

func LoadAll(cfgPlugins config.StringCollection[config.Plugin], features config.PluginConfig, configDir string) (*Cache, error)

LoadAll creates a Cache by loading all enabled plugins from config. Returns a nil Cache if no plugins are configured or all are disabled. The features parameter controls unsafe mode and include/exclude filtering. configDir is the project .aura/ directory, passed to plugin Init() as ToolConfig.ConfigDir.

func (*Cache) Close 

func (c *Cache) Close()

Close releases all plugin interpreters and removes the shared temp GOPATH.

func (*Cache) Commands 

func (c *Cache) Commands() []slash.Command

Commands returns all command exports from loaded plugins as slash commands.

func (*Cache) Hooks 

func (c *Cache) Hooks() []injector.Injector

Hooks returns all hook injectors from all loaded plugins.

func (*Cache) Tools 

func (c *Cache) Tools() []*PluginTool

Tools returns all tool exports from loaded plugins.

type Capabilities 

type Capabilities struct {
	SDKVersion  string   // empty if no vendored SDK
	Hooks       []string // timing strings: "BeforeChat", etc.
	ToolName    string   // empty if no tool
	CommandName string   // empty if no command
}

Capabilities describes what a plugin exports.

func ProbeCapabilities 

func ProbeCapabilities(dir string) (Capabilities, error)

ProbeCapabilities discovers which exports a plugin directory implements without creating a full Plugin struct. Creates a throwaway Yaegi interpreter — suitable for CLI commands, not hot paths.

type Hook 

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

Hook implements injector.Injector by calling a plugin function.

func (*Hook) Check 

func (h *Hook) Check(ctx context.Context, state *injector.State) *injector.Injection

Check evaluates the plugin hook and returns an Injection if the hook produces a message. Only handles generic timings (AfterCompaction, OnAgentSwitch). All other timings use typed CheckXxx methods or the existing CheckBeforeTool/TransformMessages.

func (*Hook) CheckAfterResponse 

func (h *Hook) CheckAfterResponse(ctx context.Context, state *injector.State) *injector.AfterResponseInjection

CheckAfterResponse implements injector.AfterResponseChecker.

func (*Hook) CheckAfterTool 

func (h *Hook) CheckAfterTool(ctx context.Context, state *injector.State) *injector.AfterToolInjection

CheckAfterTool implements injector.AfterToolChecker.

func (*Hook) CheckBeforeChat 

func (h *Hook) CheckBeforeChat(ctx context.Context, state *injector.State) *injector.BeforeChatInjection

CheckBeforeChat implements injector.BeforeChatChecker.

func (*Hook) CheckBeforeCompaction 

func (h *Hook) CheckBeforeCompaction(ctx context.Context, state *injector.State) *injector.BeforeCompactionInjection

CheckBeforeCompaction implements injector.BeforeCompactionChecker.

func (*Hook) CheckBeforeTool 

func (h *Hook) CheckBeforeTool(ctx context.Context, state *injector.State, toolName string, args map[string]any) (*injector.BeforeToolCheckItem, error)

CheckBeforeTool implements injector.BeforeToolChecker. It evaluates the hook with tool-specific context and returns argument modifications and/or block decisions instead of a standard Injection.

func (*Hook) CheckOnError 

func (h *Hook) CheckOnError(ctx context.Context, state *injector.State) *injector.OnErrorInjection

CheckOnError implements injector.OnErrorChecker.

func (*Hook) Describe 

func (h *Hook) Describe() string

Describe returns extra display info for the /plugins listing.

func (*Hook) Enabled 

func (h *Hook) Enabled() bool

func (*Hook) HasFired 

func (h *Hook) HasFired() bool

func (*Hook) MarkFired 

func (h *Hook) MarkFired(v bool)

func (*Hook) Name 

func (h *Hook) Name() string

func (*Hook) PanicCount 

func (h *Hook) PanicCount() int

func (*Hook) Timing 

func (h *Hook) Timing() injector.Timing

func (*Hook) TransformMessages 

func (h *Hook) TransformMessages(ctx context.Context, state *injector.State, messages []sdk.Message) ([]sdk.Message, error)

TransformMessages implements injector.MessageTransformer. It evaluates the hook with the message array and returns the transformed result.

type Plugin 

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

Plugin holds a loaded Yaegi interpreter and its discovered hooks and/or tool.

func Load 

func Load(name string, cfg config.Plugin, goPath string, unsafe bool, configDir string, mergedConfig map[string]any) (*Plugin, error)

Load creates a Plugin, initializes the Yaegi interpreter with GOPATH-based package loading, and probes for hook and tool functions. The goPath parameter is the shared temp GOPATH owned by Cache. When unsafe is true, os/exec and other restricted imports are available to the plugin. configDir is the project .aura/ directory.

func (*Plugin) Close 

func (p *Plugin) Close()

Close releases resources. Currently a no-op (Yaegi has no explicit close).

func (*Plugin) Command 

func (p *Plugin) Command() *PluginCommand

Command returns the command exported by this plugin, or nil if none.

func (*Plugin) Hooks 

func (p *Plugin) Hooks() []*Hook

Hooks returns the injector wrappers for all discovered hooks.

func (*Plugin) InjectEnv 

func (p *Plugin) InjectEnv(e env.Env)

InjectEnv injects task-scoped env vars into the Yaegi interpreter. Only vars in the plugin's whitelist are injected. Unrestricted plugins get all vars.

func (*Plugin) Tool 

func (p *Plugin) Tool() *PluginTool

Tool returns the tool exported by this plugin, or nil if it's hook-only.

type PluginCommand 

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

PluginCommand wraps a Yaegi-interpreted plugin's command exports.

func (*PluginCommand) Name 

func (pc *PluginCommand) Name() string

Name returns the command name with "/" prefix.

func (*PluginCommand) ToSlashCommand 

func (pc *PluginCommand) ToSlashCommand() slash.Command

ToSlashCommand converts the plugin command to a slash.Command for registration.

type PluginTool 

type PluginTool struct {
	tool.Base
	// contains filtered or unexported fields
}

PluginTool wraps a Yaegi-interpreted plugin's tool exports as a compiled tool.Tool. Bridges plugin-declared Schema/Execute/Paths to the host's sandbox and filetime infrastructure.

func (*PluginTool) Available 

func (t *PluginTool) Available() bool

func (*PluginTool) Execute 

func (t *PluginTool) Execute(ctx context.Context, args map[string]any) (string, error)

func (*PluginTool) IsOptIn 

func (t *PluginTool) IsOptIn() bool

func (*PluginTool) Name 

func (t *PluginTool) Name() string

func (*PluginTool) Overrides 

func (t *PluginTool) Overrides() bool

func (*PluginTool) Parallel 

func (t *PluginTool) Parallel() bool

Parallel returns whether the tool is safe to run concurrently with other tools. Default is true. Plugins can override by exporting Parallel() bool. Implements tool.ParallelOverride.

func (*PluginTool) Paths 

func (t *PluginTool) Paths(ctx context.Context, args map[string]any) (read, write []string, err error)

Paths returns read/write paths for the sandbox fast-path.

func (*PluginTool) Post 

func (t *PluginTool) Post(ctx context.Context, args map[string]any)

Post records filetime reads using the Record list and clears using the Clear list.

func (*PluginTool) Pre 

func (t *PluginTool) Pre(ctx context.Context, args map[string]any) error

Pre enforces read-before-write via filetime using the Guard list. All Guard paths are write-type operations, so enforcement is gated on policy.Write.

func (*PluginTool) Sandboxable 

func (t *PluginTool) Sandboxable() bool

Sandboxable returns whether the tool supports sandbox re-exec. Default is true. Plugins can override by exporting Sandboxable() bool. Implements tool.SandboxOverride.

func (*PluginTool) Schema 

func (t *PluginTool) Schema() tool.Schema

Schema composes the full schema dynamically so that MergeText overrides are visible.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.