Documentation
¶
Overview ¶
Package runtime provides sandboxed execution environments for grut extensions. Each runtime (Lua, WASM, MCP) implements the Runtime interface, allowing the extension manager to load and execute user extensions uniformly.
Index ¶
Constants ¶
const DefaultTimeout = 100 * time.Millisecond
DefaultTimeout is the maximum time a Lua script may execute before being cancelled. The value mirrors the default from config (lua_timeout_ms = 100).
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type HostAPI ¶
type HostAPI interface {
// ShowToast displays a notification to the user.
// Level should be "info", "warn", or "error".
ShowToast(title, message, level string)
// RegisterCommand adds a user-invokable command to the command palette.
RegisterCommand(name, description string, handler func() error)
// SetStatusBarItem sets a key-value pair displayed in the status bar.
SetStatusBarItem(key, value string)
// Log writes an informational message to the host log.
Log(msg string)
}
HostAPI exposes grut functionality to extension code. Implementations bridge calls from sandboxed extension code into the host application.
type LuaRuntime ¶
type LuaRuntime struct {
// contains filtered or unexported fields
}
LuaRuntime executes extension code inside a sandboxed gopher-lua VM.
func NewLuaRuntime ¶
func NewLuaRuntime(manifest *extension.Manifest, api HostAPI) (*LuaRuntime, error)
NewLuaRuntime creates a sandboxed Lua VM wired to the provided host API. The VM has dangerous modules removed and grut host functions registered.
func (*LuaRuntime) Close ¶
func (r *LuaRuntime) Close()
Close shuts down the Lua VM and releases associated resources.
func (*LuaRuntime) Load ¶
func (r *LuaRuntime) Load(entryPoint string) error
Load reads the Lua file at entryPoint and executes it inside the sandbox. Execution is subject to the configured timeout.
func (*LuaRuntime) SetTimeout ¶
func (r *LuaRuntime) SetTimeout(d time.Duration)
SetTimeout overrides the default execution timeout. A zero or negative duration disables the timeout (useful for testing only).
type MCPRuntime ¶
type MCPRuntime struct {
// contains filtered or unexported fields
}
MCPRuntime manages an MCP extension server as a subprocess, communicating via JSON-RPC 2.0 over stdin/stdout pipes.
func NewMCPRuntime ¶
func NewMCPRuntime(manifest *extension.Manifest) (*MCPRuntime, error)
NewMCPRuntime creates a new MCP runtime for the given extension manifest. The runtime is not started until Load is called.
func (*MCPRuntime) Close ¶
func (m *MCPRuntime) Close()
Close stops the MCP server subprocess. It closes stdin first, then kills the process and waits for it to exit. Safe to call multiple times or on an already-exited process.
func (*MCPRuntime) Load ¶
func (m *MCPRuntime) Load(entryPoint string) error
Security: MCP extension trust model
MCP extension subprocesses inherit the invoking user's full OS permissions. Unlike the Lua runtime (sandboxed VM) or the WASM runtime (wazero with memory and time limits), an MCP subprocess can access the filesystem, network, and any other resource available to the user's account. This is the same trust model used by VS Code extensions — users must trust installed extensions before running them.
The CheckPermission() function in package extension declares a permission system (file_read, network, process, etc.) and manifests can list required permissions, but enforcement is not currently wired into this runtime. Planned work: a future release will gate subprocess capabilities behind the permission system so that, for example, an MCP extension without "network" permission cannot open outbound connections. Load starts the MCP server subprocess using the given entry point. The interpreter is determined from the entry point file extension:
- .py → python3 (python on Windows)
- .js → node
- .ts → npx tsx
- binary (no ext or .exe) → direct execution
func (*MCPRuntime) Name ¶
func (m *MCPRuntime) Name() string
Name returns the runtime type identifier.
func (*MCPRuntime) Running ¶
func (m *MCPRuntime) Running() bool
Running reports whether the subprocess is still alive.
func (*MCPRuntime) SendRequest ¶
func (m *MCPRuntime) SendRequest(method string, params any) (json.RawMessage, error)
SendRequest sends a JSON-RPC 2.0 request to the subprocess and returns the result. Requests are serialized; only one is in flight at a time.
type Runtime ¶
type Runtime interface {
// Load reads and executes the extension entry-point script or module.
Load(entryPoint string) error
// Close releases all resources owned by the runtime.
Close()
// Name returns the runtime identifier (e.g. "lua", "wasm", "mcp").
Name() string
}
Runtime is the common interface for all extension runtimes.
type WASMRuntime ¶
type WASMRuntime struct {
// contains filtered or unexported fields
}
WASMRuntime executes WASM extensions inside a sandboxed wazero instance.
func NewWASMRuntime ¶
func NewWASMRuntime(manifest *extension.Manifest, hostAPI HostAPI) (*WASMRuntime, error)
NewWASMRuntime creates a new WASM runtime configured with a 64 MiB memory cap and no filesystem access. The returned runtime is ready for Load.
func (*WASMRuntime) Close ¶
func (w *WASMRuntime) Close()
Close releases all resources held by the wazero runtime.
func (*WASMRuntime) Load ¶
func (w *WASMRuntime) Load(entryPoint string) error
Load reads a WASM binary from entryPoint, compiles it, registers host imports, and instantiates the module.
Source Files