orcs_runtime/lib.rs
1//! ORCS Runtime - Internal implementation layer.
2//!
3//! This crate provides the internal runtime infrastructure for ORCS
4//! (Orchestrated Runtime for Collaborative Systems). It is NOT part
5//! of the Plugin SDK and should not be directly depended on by plugins.
6//!
7//! # Crate Architecture
8//!
9//! ```text
10//! ┌─────────────────────────────────────────────────────────────┐
11//! │ Plugin SDK Layer │
12//! │ (External, SemVer stable) │
13//! ├─────────────────────────────────────────────────────────────┤
14//! │ orcs-types : ID types, Principal, ErrorCode │
15//! │ orcs-event : Signal, Request, Event │
16//! │ orcs-component : Component trait (WIT target) │
17//! └─────────────────────────────────────────────────────────────┘
18//! ↓
19//! ┌─────────────────────────────────────────────────────────────┐
20//! │ Runtime Layer (THIS CRATE) │
21//! │ (Internal, implementation details) │
22//! ├─────────────────────────────────────────────────────────────┤
23//! │ auth/ : Session, PrivilegeLevel, PermissionChecker │
24//! │ channel/ : Channel, World, ChannelState │
25//! │ engine/ : OrcsEngine, EventBus, ComponentHandle │
26//! └─────────────────────────────────────────────────────────────┘
27//! ↓
28//! ┌─────────────────────────────────────────────────────────────┐
29//! │ Application Layer │
30//! │ (orcs-app: re-exports + AppError) │
31//! └─────────────────────────────────────────────────────────────┘
32//! ↓
33//! ┌─────────────────────────────────────────────────────────────┐
34//! │ Frontend Layer │
35//! │ (orcs-cli, orcs-gui, orcs-net) │
36//! └─────────────────────────────────────────────────────────────┘
37//! ```
38//!
39//! # Modules
40//!
41//! ## [`auth`] - Authentication & Authorization
42//!
43//! Internal permission management:
44//!
45//! - [`Session`] — Principal + PrivilegeLevel context
46//! - [`PrivilegeLevel`] — Standard or Elevated
47//! - [`PermissionChecker`] — Policy trait
48//!
49//! Note: [`Principal`] is in `orcs-types` for Plugin SDK access.
50//!
51//! ## [`channel`] - Parallel Execution
52//!
53//! Channel lifecycle management:
54//!
55//! - [`Channel`] — Execution unit with state
56//! - [`World`] — Channel tree manager
57//! - [`ChannelState`] — Running/Completed/Aborted
58//!
59//! ## [`engine`] - Core Runtime
60//!
61//! Main runtime infrastructure:
62//!
63//! - [`OrcsEngine`] — Main runtime loop
64//! - [`EventBus`] — Message routing
65//! - [`ComponentHandle`] — Component communication
66//!
67//! ## [`components`] - Builtin Components
68//!
69//! Core components for the runtime:
70//!
71//! - [`HilComponent`] — Human-in-the-Loop approval
72//!
73//! ## [`io`] - Human I/O
74//!
75//! Input/output for Human interaction:
76//!
77//! - [`InputParser`](io::InputParser): stdin command parsing
78//! - [`ConsoleRenderer`](io::ConsoleRenderer): console output rendering
79//!
80//! ## [`config`] - Configuration Management
81//!
82//! Hierarchical configuration with layered merging:
83//!
84//! - [`OrcsConfig`]: Unified configuration type
85//! - [`ConfigLoader`]: Multi-source config loader
86//!
87//! Configuration priority: Environment > Project > Global > Default
88//!
89//! ## [`session`] - Session Persistence
90//!
91//! Session data storage (separate from config):
92//!
93//! - [`SessionAsset`]: Conversation history, snapshots
94//! - [`SessionStore`]: Storage abstraction
95//!
96//! # Why This Separation?
97//!
98//! The runtime layer is intentionally separate from the Plugin SDK because:
99//!
100//! 1. **Stability boundary**: SDK types are SemVer stable, runtime internals can change
101//! 2. **Minimal plugin dependencies**: Plugins only need types/event/component
102//! 3. **Implementation freedom**: Runtime can be refactored without breaking plugins
103//! 4. **Clear boundaries**: Prevents accidental coupling to internal details
104
105pub mod auth;
106pub mod board;
107pub mod channel;
108pub mod components;
109pub mod config;
110pub mod engine;
111pub mod io;
112pub mod sandbox;
113pub mod session;
114pub mod work_dir;
115
116// Re-exports for convenience
117pub use auth::{
118 AccessDenied, CommandPermission, DefaultGrantStore, DefaultPolicy, GrantPolicy,
119 PermissionChecker, PermissionPolicy, PrivilegeLevel, Session,
120};
121pub use board::{
122 shared_board, shared_board_with_capacity, Board, BoardEntry, BoardEntryKind, SharedBoard,
123};
124pub use channel::{
125 priority, BaseChannel, Channel, ChannelConfig, ChannelCore, ChannelError, ChannelHandle,
126 ChannelMut, ChannelRunner, ChannelState, ChildContextImpl, ChildSpawner, ClientRunner, Event,
127 LuaChildLoader, MaxPrivilege, OutputReceiver, OutputSender, SpawnedChildHandle,
128 StateTransition, World, WorldCommand, WorldCommandSender, WorldManager,
129};
130pub use components::{
131 ApprovalRequest, ApprovalResult, DecoratorConfig, EchoWithHilComponent, HilComponent,
132 NoopComponent,
133};
134pub use config::{
135 default_config_dir, default_config_path, save_global_config, ComponentsConfig, ConfigError,
136 ConfigLoader, ConfigResolver, EnvOverrides, HilConfig, ModelConfig, NoOpResolver, OrcsConfig,
137 PathsConfig, ProfileDef, ProfileEntry, ProfileStore, UiConfig,
138};
139pub use engine::{ComponentHandle, EngineError, EventBus, OrcsEngine};
140pub use io::{
141 IOInput, IOInputHandle, IOOutput, IOOutputHandle, IOPort, InputCommand, InputContext,
142 OutputStyle,
143};
144pub use orcs_hook::{shared_hook_registry, SharedHookRegistry};
145pub use sandbox::{ProjectSandbox, SandboxError, SandboxPolicy};
146pub use session::{
147 default_session_path, LocalFileStore, SessionAsset, SessionMeta, SessionStore, StorageError,
148 SyncState, SyncStatus,
149};
150
151// Re-export Principal from orcs_types (it's part of the public API)
152pub use orcs_types::Principal;
153pub use work_dir::WorkDir;