Crate orcs_app

Expand description

ORCS Application Layer.

This crate provides:

OrcsApp: High-level application wrapper with HIL integration
Re-exports: Convenient access to all ORCS crates
AppError: Unified application-level error type

§Quick Start

use orcs_app::{OrcsApp, NoOpResolver};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let mut app = OrcsApp::builder(NoOpResolver).build().await?;
    app.run_interactive().await?;
    Ok(())
}

§Crate Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Plugin SDK Layer                          │
├─────────────────────────────────────────────────────────────┤
│  orcs-types, orcs-event, orcs-component                     │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                    Runtime Layer                             │
├─────────────────────────────────────────────────────────────┤
│  orcs-runtime (auth, channel, engine, components, io)       │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                 Application Layer  ◄── HERE                  │
├─────────────────────────────────────────────────────────────┤
│  orcs-app (OrcsApp + re-exports + AppError)                 │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                   Frontend Layer                             │
├─────────────────────────────────────────────────────────────┤
│  orcs-cli (uses OrcsApp → interactive mode)                 │
└─────────────────────────────────────────────────────────────┘

§Error Handling Strategy

Internal Errors (ChannelError, EngineError, etc.)
                   ↓ From impl
              AppError (this crate)
                   ↓ anyhow::Error / eprintln
              CLI output

Modules§

builtins: Builtin components shipped with the binary.
priority: Priority constants for common channel types.

Structs§

ChannelConfig: Configuration for a Channel.
ChannelHandle: Handle for injecting events into a ChannelRunner.
ChannelId: Identifier for a Channel in the ORCS architecture.
ChannelRunner: Execution context for a single Channel.
ClientRunner: Runner with IO bridging for Human-interactive channels.
ComponentHandle: Handle for component to receive messages
ComponentId: Identifier for a Component in the ORCS architecture.
ComponentsConfig: Component loading configuration.
ConfigLoader: Configuration loader with builder pattern.
DecoratorConfig: Decorator package configuration.
DefaultPolicy: Default permission policy.
EchoWithHilComponent: Echo component with HIL integration.
EnvOverrides: Environment variable overrides.
Event: An event that can be injected into a channel.
EventBus: EventBus - routes messages between components and channels.
EventId: Identifier for an Event in the ORCS EventBus.
HilConfig: Human-in-the-loop configuration.
ModelConfig: Model configuration.
NoOpResolver: No-op resolver that returns default configuration.
OrcsApp: ORCS Application.
OrcsAppBuilder: Builder for OrcsApp.
OrcsConfig: Main configuration structure.
OrcsEngine: OrcsEngine - Main runtime for ORCS CLI.
OutputReceiver: Receiver end of an OutputSender channel.
OutputSender: Opaque handle for sending events into a channel as InboundEvent::Direct.
PathsConfig: Path configuration.
PrincipalId: Identifier for a Principal (actor) in the ORCS system.
Progress: Progress information for long-running operations.
ProjectSandbox: Default sandbox rooted at the project directory.
Request: A synchronous request message between Components.
RequestId: Identifier for a Request in the ORCS EventBus.
Session: An active security context combining identity and privilege.
SharedPrinterSlot: Shared slot holding an optional [NonBlockingPrinter].
Signal: A control signal message.
StatusDetail: Detailed status information.
UiConfig: UI configuration.
World: Central manager for all Channels.
WorldManager: Manages World state with concurrent access support.

Enums§

AppError: Unified application error.
ChannelError: Channel layer error.
ChannelState: State of a channel.
ComponentError: Component layer error.
ConfigError: Configuration error type.
EngineError: Engine layer error.
EventError: Event layer error.
Principal: The actor performing an action.
PrintResult: Result of attempting to print through the shared slot.
PrivilegeLevel: The current privilege level of a session.
SandboxError: Errors from sandbox path validation.
SignalKind: The type of signal being sent.
SignalResponse: Response from a component after receiving a signal.
SignalScope: The scope affected by a signal or permission check.
StateTransition: State transition operations.
Status: Component execution status.
WorkDir: A directory whose existence is guaranteed while this value is alive.
WorldCommand: Commands for modifying World state.

Constants§

DEFAULT_TIMEOUT_MS: Default request timeout in milliseconds (30 seconds).

Traits§

Child: A child entity managed by a Component.
Component: Component trait for EventBus participants.
ConfigResolver: Trait for resolving configuration from all sources.
ErrorCode: Unified error code interface for ORCS errors.
Identifiable: Identifiable component or child.
PermissionChecker: Runtime-level permission checker with HIL integration.
SandboxPolicy: Resource boundary policy for file operations.
SignalReceiver: Signal receiver for human control.
Statusable: Status reporting for monitoring.
TryNew: Trait for fallible construction with validation.

Type Aliases§

Channel: Type alias for backward compatibility.
WorldCommandSender: Handle for sending commands to WorldManager.

Crate orcs_app

Crate orcs_app Copy item path

§Quick Start

§Crate Architecture

§Error Handling Strategy

Modules§

Structs§

Enums§

Constants§

Traits§

Type Aliases§

Crate orcs_app