luaengine

package
v0.411.0 Latest Latest
Warning

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

 Go to latest Published: Jun 1, 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.

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.