luaengine

Documentation

Index

• func CloseLuaState(L *lua.LState)
• func GoToLua(L *lua.LState, val interface{}) lua.LValue
• func LuaTableToMap(lt *lua.LTable) map[string]interface{}
• func LuaToGo(lv lua.LValue) interface{}
• func MapToLuaTable(L *lua.LState, m map[string]interface{}) *lua.LTable
• func NewLuaState() *lua.LState
• type FilterManager
  • func NewFilterManager(scriptPath string, timeout time.Duration, strictMode bool) (*FilterManager, error)
  • func (fm *FilterManager) ApplyInputFilter(ctx context.Context, hookCtx *HookContext) (*HookResult, error)
  • func (fm *FilterManager) ApplyOutputFilter(ctx context.Context, hookCtx *HookContext) (*HookResult, error)
  • func (fm *FilterManager) Close()
  • func (fm *FilterManager) ExecuteHook(ctx context.Context, hookType HookType, data map[string]interface{}) (*HookResult, error)
  • func (fm *FilterManager) IsEnabled() bool
  • func (fm *FilterManager) LoadScript() error
  • func (fm *FilterManager) ReloadScript() error
• type FilterType
• type HookContext
  • func NewInputContext(serverName, toolName string, parameters map[string]interface{}, ...) *HookContext
  • func NewOutputContext(serverName, toolName string, result map[string]interface{}, requestID string, ...) *HookContext
• type HookResult
  • func NewHookResult() *HookResult
• type HookType

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 sandboxed Lua state with required modules preloaded. The shell/os execution modules are intentionally excluded for security.

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) 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) 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"
	HookConversationStart   HookType = "conversation_start"
	HookUserPrompt          HookType = "user_prompt"
	HookAgentResponseFinish HookType = "agent_response_finish"
)