Struct Runtime 

pub struct Runtime { /* private fields */ }

The main runtime structure that executes Lua scripts.

All shared dependencies (scheduler, run context, journal, tokio handle) are captured by the SDK closures during construction; the struct itself only needs to retain the VM and the report sink.

Implementations

impl Runtime

pub fn new( scheduler: Arc<Scheduler>, run_ctx: RunContext, args: Value, _limits: ExecLimits, journal: Option<Arc<JournalStore>>, handle: Handle, ) -> Result<Self, ScriptError>

Create a new Runtime with sandbox applied.

handle is the tokio runtime handle used by SDK primitives to block on the async scheduler. It is captured here (in async context) so it can be used later from the blocking execution thread.

pub fn execute(&self, script: &str) -> Result<Value, ScriptError>

Execute the script and return the report value (if any).

The script MUST declare a meta = { ... } table at the top level and a function main() ... end entry point. Execution proceeds in two phases:

1. Top-level exec: runs all assignments and function definitions (meta = {...}, schema locals, function main() ... end). This is safe — no agent/phase calls happen here.
2. Extract meta: reads the meta global, emits a AgentEvent::PlanPreview.
3. Call main(): invokes the main function which contains the real orchestration logic.

MUST be called from a blocking context (not an async worker thread), because the SDK primitives call Handle::block_on internally.

pub fn set_completed_spans(&self, names: &[String]) -> Result<(), ScriptError>

Inject completed phase span names as the completed_spans Lua global, so resume scripts can skip already-finished structural units.