Crate orcs_runtime

Expand description

ORCS Runtime - Internal implementation layer.

This crate provides the internal runtime infrastructure for ORCS (Orchestrated Runtime for Collaborative Systems). It is NOT part of the Plugin SDK and should not be directly depended on by plugins.

§Crate Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Plugin SDK Layer                         │
│  (External, SemVer stable)                                   │
├─────────────────────────────────────────────────────────────┤
│  orcs-types     : ID types, Principal, ErrorCode            │
│  orcs-event     : Signal, Request, Event                    │
│  orcs-component : Component trait (WIT target)              │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                   Runtime Layer (THIS CRATE)                 │
│  (Internal, implementation details)                          │
├─────────────────────────────────────────────────────────────┤
│  auth/     : Session, PrivilegeLevel, PermissionChecker     │
│  channel/  : Channel, World, ChannelState                   │
│  engine/   : OrcsEngine, EventBus, ComponentHandle          │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                   Application Layer                          │
│  (orcs-app: re-exports + AppError)                          │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                   Frontend Layer                             │
│  (orcs-cli, orcs-gui, orcs-net)                             │
└─────────────────────────────────────────────────────────────┘

§Modules

§`auth` - Authentication & Authorization

Internal permission management:

Session — Principal + PrivilegeLevel context
PrivilegeLevel — Standard or Elevated
PermissionChecker — Policy trait

Note: Principal is in orcs-types for Plugin SDK access.

§`channel` - Parallel Execution

Channel lifecycle management:

Channel — Execution unit with state
World — Channel tree manager
ChannelState — Running/Completed/Aborted

§`engine` - Core Runtime

Main runtime infrastructure:

OrcsEngine — Main runtime loop
EventBus — Message routing
ComponentHandle — Component communication

§`components` - Builtin Components

Core components for the runtime:

HilComponent — Human-in-the-Loop approval

§`io` - Human I/O

Input/output for Human interaction:

InputParser: stdin command parsing
ConsoleRenderer: console output rendering

§`config` - Configuration Management

Hierarchical configuration with layered merging:

OrcsConfig: Unified configuration type
ConfigLoader: Multi-source config loader

Configuration priority: Environment > Project > Global > Default

§`session` - Session Persistence

Session data storage (separate from config):

SessionAsset: Conversation history, snapshots
SessionStore: Storage abstraction

§Why This Separation?

The runtime layer is intentionally separate from the Plugin SDK because:

Stability boundary: SDK types are SemVer stable, runtime internals can change
Minimal plugin dependencies: Plugins only need types/event/component
Implementation freedom: Runtime can be refactored without breaking plugins
Clear boundaries: Prevents accidental coupling to internal details

Re-exports§

pub use auth::DefaultGrantStore;
pub use auth::DefaultPolicy;
pub use auth::PermissionChecker;
pub use board::shared_board;
pub use board::shared_board_with_capacity;
pub use board::Board;
pub use board::BoardEntry;
pub use board::BoardEntryKind;
pub use board::SharedBoard;
pub use channel::priority;
pub use channel::BaseChannel;
pub use channel::Channel;
pub use channel::ChannelConfig;
pub use channel::ChannelCore;
pub use channel::ChannelError;
pub use channel::ChannelHandle;
pub use channel::ChannelMut;
pub use channel::ChannelRunner;
pub use channel::ChannelState;
pub use channel::ChildContextImpl;
pub use channel::ChildSpawner;
pub use channel::ClientRunner;
pub use channel::Event;
pub use channel::LuaChildLoader;
pub use channel::MaxPrivilege;
pub use channel::OutputReceiver;
pub use channel::OutputSender;
pub use channel::SpawnedChildHandle;
pub use channel::StateTransition;
pub use channel::World;
pub use channel::WorldCommand;
pub use channel::WorldCommandSender;
pub use channel::WorldManager;
pub use components::ApprovalRequest;
pub use components::ApprovalResult;
pub use components::DecoratorConfig;
pub use components::EchoWithHilComponent;
pub use components::HilComponent;
pub use components::NoopComponent;
pub use config::default_config_dir;
pub use config::default_config_path;
pub use config::save_global_config;
pub use config::ComponentsConfig;
pub use config::ConfigError;
pub use config::ConfigLoader;
pub use config::ConfigResolver;
pub use config::EnvOverrides;
pub use config::HilConfig;
pub use config::ModelConfig;
pub use config::NoOpResolver;
pub use config::OrcsConfig;
pub use config::PathsConfig;
pub use config::ProfileDef;
pub use config::ProfileEntry;
pub use config::ProfileStore;
pub use config::UiConfig;
pub use engine::ComponentHandle;
pub use engine::EngineError;
pub use engine::EventBus;
pub use engine::OrcsEngine;
pub use io::IOInput;
pub use io::IOInputHandle;
pub use io::IOOutput;
pub use io::IOOutputHandle;
pub use io::IOPort;
pub use io::InputCommand;
pub use io::InputContext;
pub use io::OutputStyle;
pub use sandbox::ProjectSandbox;
pub use session::default_session_path;
pub use session::LocalFileStore;
pub use session::SessionAsset;
pub use session::SessionMeta;
pub use session::SessionStore;
pub use session::StorageError;
pub use session::SyncState;
pub use session::SyncStatus;
pub use work_dir::WorkDir;

Modules§

auth: Authentication and authorization for ORCS CLI.
board: SharedBoard - Shared event log for cross-component visibility.
channel: Channel and World management for ORCS CLI.
components: Builtin Components for ORCS runtime.
config: Configuration management with hierarchical layering.
engine: ORCS Engine - Runtime and EventBus.
io: I/O abstraction for Human interaction.
sandbox: File system sandbox implementation.
session: Session persistence and storage.
work_dir: Lifecycle-managed work directory.

Structs§

Session: An active security context combining identity and privilege.

Enums§

AccessDenied: Unified error for access denied across all permission layers.
CommandPermission: Result of a command permission check (trait-level type).
Principal: The actor performing an action.
PrivilegeLevel: The current privilege level of a session.
SandboxError: Errors from sandbox path validation.

Traits§

GrantPolicy: Dynamic command permission management.
PermissionPolicy: Abstract permission policy for session-based access control.
SandboxPolicy: Resource boundary policy for file operations.

Functions§

shared_hook_registry: Creates a new empty SharedHookRegistry.

Type Aliases§

SharedHookRegistry: Thread-safe shared reference to a HookRegistry.