Struct OrcsEngine 

pub struct OrcsEngine { /* private fields */ }

OrcsEngine - Main runtime for ORCS CLI.

Coordinates parallel execution of ChannelRunners and manages the World (channel hierarchy).

Parallel Execution Model

Engine operates in parallel mode with:

• WorldManager for concurrent World access
• ChannelRunner per channel
• Event injection via channel handles
• Snapshot collection via graceful runner shutdown

Example

use orcs_runtime::{World, ChannelConfig};

// Create World with IO channel
let mut world = World::new();
let io = world.create_channel(ChannelConfig::interactive());

// Inject into engine with IO channel (required)
let engine = OrcsEngine::new(world, io);

// Spawn channel runners with bound components
engine.spawn_runner(io, Box::new(MyComponent::new()));

// Run the engine (parallel execution)
engine.run().await;

Signal Priority

Signals are broadcast to all Runners. A Veto signal immediately stops the engine without processing further.

Implementations

impl OrcsEngine

pub fn new(world: World, io_channel: ChannelId) -> Self

Create new engine with injected World and IO channel.

The World is immediately transferred to a WorldManager which starts processing commands. The IO channel is required for Human input/output.

Arguments

• world - The World containing the IO channel
• io_channel - The IO channel ID (must exist in World)

Example

let mut world = World::new();
let io = world.create_channel(ChannelConfig::interactive());

let engine = OrcsEngine::new(world, io);

pub fn set_mcp_manager(&mut self, manager: Arc<McpClientManager>)

Sets the shared MCP client manager for all spawned runners.

Must be called before spawning runners to ensure they receive the manager.

pub fn set_hook_registry(&mut self, registry: SharedHookRegistry)

Sets the shared hook registry for all spawned runners.

Must be called before spawning runners to ensure they receive the registry.

pub fn hook_registry(&self) -> Option<&SharedHookRegistry>

Returns a reference to the hook registry, if configured.

pub fn spawn_runner( &mut self, channel_id: ChannelId, component: Box<dyn Component>, ) -> ChannelHandle

Spawn a channel runner for a channel with a bound Component.

Returns the channel handle for event injection.

Arguments

• channel_id - The channel to run
• component - The Component to bind (1:1 relationship)

pub fn spawn_client_runner( &mut self, channel_id: ChannelId, io_port: IOPort, principal: Principal, ) -> (ChannelHandle, OutputSender)

Spawn a channel runner with an EventEmitter injected into the Component.

This enables IO-less (event-only) execution for Components that support the Emitter trait. The Component can emit output via emit_output().

Use this for ChannelRunner-based execution instead of ClientRunner. Spawn a ClientRunner for an IO channel (no component).

ClientRunner is dedicated to Human I/O bridging. It broadcasts UserInput events to all channels and displays Output events from other channels.

Arguments

• channel_id - The channel to run
• io_port - IO port for View communication
• principal - Principal for signal creation from IO input

Returns

A tuple of (ChannelHandle, event_tx) where event_tx can be used by other runners to send Output events to this runner for display.

pub async fn spawn_channel( &mut self, parent: ChannelId, config: ChannelConfig, component: Box<dyn Component>, ) -> Option<ChannelId>

Spawn a child channel with configuration and bound Component.

Creates a new channel in World and spawns its runner.

Arguments

• parent - Parent channel ID
• config - Channel configuration
• component - Component to bind to the new channel (1:1)

pub async fn spawn_channel_with_auth( &mut self, parent: ChannelId, config: ChannelConfig, component: Box<dyn Component>, session: Arc<Session>, checker: Arc<dyn PermissionChecker>, ) -> Option<ChannelId>

Spawn a child channel with authentication/authorization.

Creates a new channel in World and spawns its runner with Session and PermissionChecker configured.

Authorization Check

Before spawning, checks if the session is allowed to spawn children using the provided checker. Returns None if unauthorized.

Arguments

• parent - Parent channel ID
• config - Channel configuration
• component - Component to bind to the new channel (1:1)
• session - Session for permission checking (Arc for shared grants)
• checker - Permission checker policy

Returns

• Some(ChannelId) if spawn succeeded
• None if parent doesn’t exist or permission denied

pub fn spawn_runner_with_auth( &mut self, channel_id: ChannelId, component: Box<dyn Component>, session: Arc<Session>, checker: Arc<dyn PermissionChecker>, ) -> ChannelHandle

Spawn a runner with Session and PermissionChecker.

The Session and Checker are passed to the ChildContext for command permission checking.

Arguments

• channel_id - The channel to run
• component - The Component to bind
• session - Session for permission checking
• checker - Permission checker policy

pub fn spawn_runner_full_auth( &mut self, channel_id: ChannelId, component: Box<dyn Component>, output_tx: Option<OutputSender>, lua_loader: Option<Arc<dyn LuaChildLoader>>, component_loader: Option<Arc<dyn ComponentLoader>>, session: Arc<Session>, checker: Arc<dyn PermissionChecker>, grants: Arc<dyn GrantPolicy>, ) -> ChannelHandle

Spawn a ChannelRunner with all options including auth.

This is the most complete spawn method that supports:

• Event emission (signal broadcasting)
• Output routing to IO channel
• Child spawning via LuaChildLoader
• Component loading for spawn_runner_from_script
• Session-based permission checking

Arguments

• channel_id - The channel to run
• component - The Component to bind
• output_tx - Optional channel for Output event routing
• lua_loader - Optional loader for spawning Lua children
• component_loader - Optional loader for spawning Components as runners
• session - Session for permission checking
• checker - Permission checker policy

Returns

A handle for injecting Events into the Channel.

pub fn spawn_runner_full_auth_with_snapshot( &mut self, channel_id: ChannelId, component: Box<dyn Component>, output_tx: Option<OutputSender>, lua_loader: Option<Arc<dyn LuaChildLoader>>, component_loader: Option<Arc<dyn ComponentLoader>>, session: Arc<Session>, checker: Arc<dyn PermissionChecker>, grants: Arc<dyn GrantPolicy>, initial_snapshot: Option<ComponentSnapshot>, component_config: Value, ) -> ChannelHandle

Spawns a ChannelRunner with full auth and an optional initial snapshot.

Same as Self::spawn_runner_full_auth but accepts an optional ComponentSnapshot to restore before init() (session resume).

pub fn world_read(&self) -> &Arc<RwLock<World>>

Returns the read-only World handle for parallel access.

pub fn world_tx(&self) -> &WorldCommandSender

Returns the world command sender.

pub fn inject_event( &self, channel_id: ChannelId, event: Event, ) -> Result<(), EngineError>

Injects an event to a specific channel (targeted delivery).

Unlike signal broadcast, this sends to a single channel only. Used for @component message routing.

Errors

Returns EngineError::ChannelNotFound if channel doesn’t exist, or EngineError::SendFailed if the buffer is full.

pub fn signal(&self, signal: Signal)

Send signal (from external, e.g., human input)

Broadcasts to all ChannelRunners via signal_tx.

pub fn is_running(&self) -> bool

Check if engine is running

pub fn start(&mut self)

Start the engine (set running flag) and spawn the runner monitor.

Use this when you need to start the engine without entering the run loop, for example in interactive mode where you control the polling yourself.

pub fn stop(&self)

Stop the engine by sending a Veto signal.

This triggers graceful shutdown via the signal broadcast channel. Call shutdown() after this to await runner completion and collect snapshots.

pub async fn shutdown(&mut self)

Awaits all runners, collects snapshots, and cleans up.

Must be called after stop() to complete the shutdown sequence. Snapshots are available via collected_snapshots() after this returns.

pub fn board(&self) -> &SharedBoard

Returns the shared Board handle.

External code (e.g., Lua API registration) can use this to query the Board for recent events.

pub fn io_channel(&self) -> ChannelId

Returns the IO channel ID.

The IO channel is required and always available.

pub async fn run(&mut self)

Main run loop with parallel execution.

This method:

1. Waits for stop signal (running flag set to false)
2. Shuts down all runners on exit

Note

Caller must spawn runners via spawn_runner() before calling run(). Each runner requires a bound Component (1:1 relationship).

Example

let mut engine = OrcsEngine::new(world);
engine.spawn_runner(io_id, Box::new(MyComponent::new()));
engine.run().await;

pub fn collected_snapshots(&self) -> &HashMap<String, ComponentSnapshot>

Returns a reference to snapshots collected during graceful shutdown.

Populated by shutdown_parallel() when runners complete their shutdown sequence. Keyed by component FQN.

Usage

Call this after run() completes to retrieve snapshots for session persistence.