Help us shape the future of Go! Take the 2026 Go Developer Survey

luaengine

package
v0.625.0 Latest Latest
Warning

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

Go to latest
Published: Jul 17, 2026 License: MIT Imports: 34 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CloseLuaState

func CloseLuaState(L *lua.LState)

CloseLuaState properly closes and cleans up a Lua state.

func GoToLua

func GoToLua(L *lua.LState, val interface{}) lua.LValue

GoToLua converts a Go value to a Lua value. Handles: nil, bool, string, int, int64, float64, map[string]interface{}, []interface{}

func LuaTableToMap

func LuaTableToMap(lt *lua.LTable) map[string]interface{}

LuaTableToMap converts a Lua table to a Go map[string]interface{}. If the table is an array, keys are converted to string indices.

func LuaToGo

func LuaToGo(lv lua.LValue) interface{}

LuaToGo converts a Lua value to a Go value. Handles: LNil, LBool, LNumber, LString, *LTable (auto-detects array vs map)

func MapToLuaTable

func MapToLuaTable(L *lua.LState, m map[string]interface{}) *lua.LTable

MapToLuaTable converts a Go map[string]interface{} to a Lua table.

func NewLuaState

func NewLuaState() *lua.LState

NewLuaState initializes a new Lua state with the supported modules preloaded.

func RegisterPromptFunctions added in v0.26.2

func RegisterPromptFunctions(L *lua.LState, opts *PromptFunctionOptions)

RegisterPromptFunctions registers Pando-specific functions in the Lua state. These are available to Lua scripts for inspecting and manipulating the prompt system.

Types

type FilterManager

type FilterManager struct {
	L *lua.LState
	// contains filtered or unexported fields
}

FilterManager manages Lua filter and hook execution.

func NewFilterManager

func NewFilterManager(scriptPath string, timeout time.Duration, strictMode bool) (*FilterManager, error)

NewFilterManager creates a new FilterManager instance. If scriptPath is empty or the file doesn't exist, filters are disabled. In non-strict mode, script load errors are logged but do not return an error.

func (*FilterManager) ApplyInputFilter

func (fm *FilterManager) ApplyInputFilter(ctx context.Context, hookCtx *HookContext) (*HookResult, error)

ApplyInputFilter applies the input filter for the given MCP tool invocation. It looks for function `<serverName>-input`, with fallback to `global-input`.

func (*FilterManager) ApplyOutputFilter

func (fm *FilterManager) ApplyOutputFilter(ctx context.Context, hookCtx *HookContext) (*HookResult, error)

ApplyOutputFilter applies the output filter for the given MCP tool result. It looks for function `<serverName>-output`, with fallback to `global-output`.

func (*FilterManager) Close

func (fm *FilterManager) Close()

Close releases all resources held by the FilterManager.

func (*FilterManager) ExecuteHook

func (fm *FilterManager) ExecuteHook(ctx context.Context, hookType HookType, data map[string]interface{}) (*HookResult, error)

ExecuteHook executes a lifecycle hook function. It looks for function `hook_<hookType>`, with fallback to `hook_global`.

func (*FilterManager) ExecuteLuaTool added in v0.410.1

func (fm *FilterManager) ExecuteLuaTool(ctx context.Context, toolName string, data map[string]interface{}) (*HookResult, error)

ExecuteLuaTool executes a registered Lua tool through the MVP dispatcher.

func (*FilterManager) IsEnabled

func (fm *FilterManager) IsEnabled() bool

IsEnabled returns whether the filter manager is active.

func (*FilterManager) LoadScript

func (fm *FilterManager) LoadScript() error

LoadScript loads the Lua filter script from the configured path.

func (*FilterManager) LuaTools added in v0.410.1

func (fm *FilterManager) LuaTools() []LuaToolDefinition

LuaTools returns the tools registered by the loaded Lua script.

func (*FilterManager) RegisterPromptFunctions added in v0.26.2

func (fm *FilterManager) RegisterPromptFunctions(opts *PromptFunctionOptions)

RegisterPromptFunctions registers prompt-system functions in the Lua state.

func (*FilterManager) ReloadScript

func (fm *FilterManager) ReloadScript() error

ReloadScript closes the current Lua state, creates a fresh one, and reloads the script.

type FilterType

type FilterType string

FilterType represents the type of filter (input or output)

const (
	// FilterInput processes parameters before tool execution
	FilterInput FilterType = "input"
	// FilterOutput processes results after tool execution
	FilterOutput FilterType = "output"
)

type HookContext

type HookContext struct {
	// ServerName is the name of the downstream MCP server
	ServerName string `json:"server_name"`

	// ToolName is the name of the tool being executed
	ToolName string `json:"tool_name"`

	// HookType indicates the lifecycle hook type (for ExecuteHook)
	HookType HookType `json:"hook_type,omitempty"`

	// Parameters contains the input parameters (for input filters)
	Parameters map[string]interface{} `json:"parameters,omitempty"`

	// Result contains the execution result (for output filters)
	Result map[string]interface{} `json:"result,omitempty"`

	// RequestID is a unique identifier for this request
	RequestID string `json:"request_id"`

	// SessionID is the current session identifier
	SessionID string `json:"session_id,omitempty"`

	// Timestamp is when the hook was triggered
	Timestamp int64 `json:"timestamp"`

	// Duration is the execution time in milliseconds (for output filters only)
	Duration int64 `json:"duration,omitempty"`

	// FilterType indicates whether this is an input or output filter
	FilterType FilterType `json:"filter_type"`
}

HookContext contains the context information passed to Lua filter functions. This structure is converted to a Lua table and passed to filter functions.

func NewInputContext

func NewInputContext(serverName, toolName string, parameters map[string]interface{}, requestID string) *HookContext

NewInputContext creates a new HookContext for an input filter.

func NewOutputContext

func NewOutputContext(serverName, toolName string, result map[string]interface{}, requestID string, duration time.Duration) *HookContext

NewOutputContext creates a new HookContext for an output filter.

type HookResult

type HookResult struct {
	// Modified indicates whether the filter made any changes
	Modified bool

	// Data contains the filtered data (parameters or result)
	Data map[string]interface{}

	// Error contains any error that occurred during filter execution
	Error error

	// ExecutionTime is how long the filter took to execute
	ExecutionTime time.Duration

	// Logs contains any log messages generated by the filter
	Logs []string
}

HookResult represents the result of applying a filter or executing a hook.

func NewHookResult

func NewHookResult() *HookResult

NewHookResult creates a new HookResult with default values.

type HookType

type HookType string

HookType represents the type of lifecycle hook

const (
	HookSystemPrompt        HookType = "system_prompt"
	HookSessionStart        HookType = "session_start"
	HookSessionRestore      HookType = "session_restore"
	HookSessionEnd          HookType = "session_end"
	HookConversationStart   HookType = "conversation_start"
	HookUserPrompt          HookType = "user_prompt"
	HookAgentResponseFinish HookType = "agent_response_finish"

	// Template system hooks
	HookTemplateSection HookType = "template_section"
	HookCapabilityCheck HookType = "capability_check"
	HookProviderSelect  HookType = "provider_select"
	HookPromptCompose   HookType = "prompt_compose"

	// Self-improvement hooks
	HookEvaluationComplete HookType = "hook_evaluation_complete"

	// Cache lifecycle hooks
	HookCacheStore HookType = "hook_cache_store" // fired when a tool response is auto-cached
	HookCacheEvict HookType = "hook_cache_evict" // fired when an entry is LRU-evicted
	HookCacheClear HookType = "hook_cache_clear" // fired when the session cache is cleared
)

type LuaToolDefinition added in v0.410.1

type LuaToolDefinition struct {
	Name        string
	Description string
	Parameters  map[string]any
	Required    []string
}

LuaToolDefinition describes a tool registered from Lua.

func CollectRegisteredTools added in v0.410.1

func CollectRegisteredTools(L *lua.LState) ([]LuaToolDefinition, error)

CollectRegisteredTools validates and converts Lua-declared tool definitions.

type PromptFunctionOptions added in v0.26.2

type PromptFunctionOptions struct {
	GetConfig      lua.LGFunction
	GetGitStatus   lua.LGFunction
	ListMCPServers lua.LGFunction
	ListTools      lua.LGFunction
	LoadFile       lua.LGFunction
}

PromptFunctionOptions holds callbacks for Lua prompt functions. These are injected from the calling package to avoid circular dependencies.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL