Crate orcs_lua 

Lua scripting support for ORCS components.

This crate enables writing ORCS Components and Children in Lua scripts.

Architecture

┌─────────────────────────────────────────────────────┐
│              LuaComponent (Rust)                    │
│  impl Component for LuaComponent                    │
│  ┌───────────────────────────────────────────────┐  │
│  │  lua: Lua (mlua)                              │  │
│  │  id: ComponentId                              │  │
│  │  callbacks: LuaCallbacks                       │  │
│  └───────────────────────────────────────────────┘  │
│                         │                           │
│                         ▼                           │
│  ┌───────────────────────────────────────────────┐  │
│  │           Lua Script (.lua)                   │  │
│  │  return {                                      │  │
│  │    id = "my-component",                       │  │
│  │    subscriptions = {"Echo"},                  │  │
│  │    on_request = function(req) ... end,        │  │
│  │    on_signal = function(sig) ... end,         │  │
│  │  }                                            │  │
│  └───────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────┘

Example Lua Script

-- echo_component.lua
return {
    id = "lua-echo",
    subscriptions = {"Echo"},

    on_request = function(request)
        if request.operation == "echo" then
            return { success = true, data = request.payload }
        end
        return { success = false, error = "unknown operation" }
    end,

    on_signal = function(signal)
        if signal.kind == "Veto" then
            return "Abort"
        end
        return "Ignored"
    end,
}

Sandbox

All file operations (orcs.read, orcs.write, orcs.grep, orcs.glob, orcs.mkdir, orcs.remove, orcs.mv) are sandboxed via SandboxPolicy. The sandbox is injected at construction time and controls:

• Which filesystem paths are accessible for reads and writes
• The working directory for orcs.exec() commands
• The value of orcs.pwd in Lua

Dangerous Lua stdlib functions (io.*, os.execute, loadfile, etc.) are disabled after registration to prevent sandbox bypass.

Hot Reload

LuaComponent::reload() allows reloading the script from file.

Script Loading

Scripts are loaded from filesystem search paths:

use orcs_lua::ScriptLoader;
use orcs_runtime::sandbox::ProjectSandbox;
use std::sync::Arc;

let sandbox = Arc::new(ProjectSandbox::new(".").expect("sandbox init"));

let loader = ScriptLoader::new(sandbox)
    .with_path("~/.orcs/components")
    .with_path("/versioned/builtins/components");
let component = loader.load("echo")?;

Re-exports

pub use hook_helpers::load_hooks_from_config;

pub use hook_helpers::register_hook_function;

pub use hook_helpers::register_hook_stub;

pub use hook_helpers::register_unhook_function;

pub use hook_helpers::HookLoadError;

pub use hook_helpers::HookLoadResult;

pub use hook_helpers::LuaHook;

pub use llm_command::llm_request_impl;

pub use llm_command::register_llm_deny_stub;

pub use orcs_helpers::ensure_orcs_table;

pub use orcs_helpers::register_base_orcs_functions;

pub use tools::register_tool_functions;

Modules

hook_helpers

Hook helpers for Lua integration.

http_command

Lua-exposed HTTP client for orcs.http().

llm_adapter

LLM response → ActionIntent adapter.

llm_command

Multi-provider LLM client for orcs.llm().

orcs_helpers

Common orcs helper functions for Lua.

sandbox_eval

Sandboxed Lua code evaluation.

sanitize

Input sanitization and structured execution for Lua.

tool_registry

Intent registry: structured intent definitions with unified dispatch.

tools

First-class Rust tool implementations for Lua.

Structs

LoadResult

Result of batch loading operation.

LoadWarning

Warning for a failed script load.

LuaChild

A child entity implemented in Lua.

LuaComponent

A component implemented in Lua.

LuaComponentLoader

ComponentLoader implementation for Lua components.

LuaEnv

Unified Lua environment configuration.

LuaRequest

Request representation for Lua.

LuaResponse

Response from Lua script.

LuaSignal

Signal representation for Lua.

ScriptLoader

Script loader with configurable search paths.

Enums

LuaError

Errors that can occur in Lua component operations.