Crate orcs_component

Expand description

Component system for ORCS CLI.

This crate provides the component abstraction layer for the ORCS (Orchestrated Runtime for Collaborative Systems) architecture.

§Crate Architecture

This crate is part of the Plugin SDK layer:

┌─────────────────────────────────────────────────────────────┐
│                    Plugin SDK Layer                          │
│  (External, SemVer stable, safe to depend on)               │
├─────────────────────────────────────────────────────────────┤
│  orcs-types     : ID types, Principal, ErrorCode            │
│  orcs-event     : Signal, Request, Event                    │
│  orcs-component : Component trait (WIT target)  ◄── HERE    │
└─────────────────────────────────────────────────────────────┘

§WIT Target

The Component trait is designed to be exportable as a WebAssembly Interface Type (WIT) for WASM component plugins. This enables:

Language-agnostic plugins: Write components in any language
Sandboxed execution: WASM provides security isolation
Dynamic loading: Load plugins at runtime without recompilation

§Component Architecture Overview

Components are the functional units that communicate via the EventBus:

┌──────────────────────────────────────────────────────────────────────┐
│                            OrcsEngine                                │
│  ┌────────────────────────────────────────────────────────────────┐  │
│  │                          EventBus                              │  │
│  │   - Request/Response routing                                   │  │
│  │   - Signal dispatch (highest priority)                         │  │
│  └────────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────────┘
          │ EventBus
          ├──────────────┬──────────────┬──────────────┐
          ▼              ▼              ▼              ▼
    ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐
    │   LLM    │   │  Tools   │   │   HIL    │   │  Skill   │
    │Component │   │Component │   │Component │   │Component │
    └──────────┘   └──────────┘   └──────────┘   └──────────┘
          │
          │ Internal management
          ▼
    ┌────────────────────────────────────────────────────────┐
    │                Child / Agent / Skill                   │
    │            (managed by parent Component)               │
    └────────────────────────────────────────────────────────┘

§Core Traits

§Required Traits (All Components/Children Must Implement)

Trait	Purpose
`Identifiable`	Entity identification
`SignalReceiver`	Human control (abort, cancel)
`Statusable`	Status reporting for monitoring

§Component Traits

Trait	Purpose
`Component`	EventBus participant with request handling
`Child`	Managed entity (no direct EventBus access)
`Agent`	Reactive child (subscribes to events)
`Skill`	Auto-triggered child

§Human as Superpower

A core principle of ORCS: Human controls from above. All components MUST respond to signals:

Veto: Stop everything immediately
Cancel: Stop operations in scope

This is enforced by the SignalReceiver trait.

§Example: Simple Component

use orcs_component::{Component, ComponentError, Status};
use orcs_event::{Request, Signal, SignalResponse};
use orcs_types::ComponentId;
use serde_json::Value;

struct EchoComponent {
    id: ComponentId,
    status: Status,
}

impl EchoComponent {
    fn new() -> Self {
        Self {
            id: ComponentId::builtin("echo"),
            status: Status::Idle,
        }
    }
}

impl Component for EchoComponent {
    fn id(&self) -> &ComponentId {
        &self.id
    }

    fn status(&self) -> Status {
        self.status
    }

    fn on_request(&mut self, request: &Request) -> Result<Value, ComponentError> {
        self.status = Status::Running;
        match request.operation.as_str() {
            "echo" => {
                self.status = Status::Idle;
                Ok(request.payload.clone())
            }
            op => Err(ComponentError::NotSupported(op.into())),
        }
    }

    fn on_signal(&mut self, signal: &Signal) -> SignalResponse {
        if signal.is_veto() {
            self.abort();
            SignalResponse::Abort
        } else {
            SignalResponse::Ignored
        }
    }

    fn abort(&mut self) {
        self.status = Status::Aborted;
    }
}

§Example: Child Entity

use orcs_component::{Child, Identifiable, SignalReceiver, Statusable, Status};
use orcs_event::{Signal, SignalResponse};

struct Worker {
    id: String,
    status: Status,
}

impl Identifiable for Worker {
    fn id(&self) -> &str {
        &self.id
    }
}

impl SignalReceiver for Worker {
    fn on_signal(&mut self, signal: &Signal) -> SignalResponse {
        if signal.is_veto() {
            self.abort();
            SignalResponse::Abort
        } else {
            SignalResponse::Ignored
        }
    }

    fn abort(&mut self) {
        self.status = Status::Aborted;
    }
}

impl Statusable for Worker {
    fn status(&self) -> Status {
        self.status
    }
}

// Mark as Child
impl Child for Worker {}

§Crate Structure

Component - EventBus participant trait
Child, Agent, Skill - Managed entity traits
Identifiable, SignalReceiver, Statusable - Core traits
Status, StatusDetail, Progress - Status types
ComponentError - Error types

orcs_types - Core identifier types (ComponentId, Principal, etc.)
orcs_event - Event types (Signal, Request)
orcs-runtime - Runtime layer (Session, EventBus)

Re-exports§

pub use tool::RustTool;
pub use tool::ToolContext;
pub use tool::ToolError;

Modules§

capability: Re-export of Capability from orcs-auth.
testing: Testing harnesses for Component and Child implementations.
tool: RustTool trait for self-describing, sandboxed tool plugins.

Structs§

Capability: Logical capabilities that a context can grant to child entities.
ChildConfig: Configuration for spawning a child.
ComponentSnapshot: Component state snapshot.
Package: A package that can be installed into a component.
PackageInfo: Package metadata.
Progress: Progress information for long-running operations.
RuntimeHints: Hints from a Component to the Runtime about how it should be spawned.
StatusDetail: Detailed status information.
SubscriptionEntry: A subscription entry with optional operation-level filtering.

Enums§

ChildError: Child execution errors.
ChildResult: Result of a Child’s work execution.
ChildResultDto: Serializable representation of ChildResult.
CommandPermission: Result of a command permission check (trait-level type).
ComponentError: Component layer error.
EventCategory: Event category for subscription-based routing.
PackageError: Errors that can occur during package operations.
PackageSupport: Declares whether a component supports package installation.
RunError: Error when running a child fails.
SnapshotError: Errors that can occur during snapshot operations.
SnapshotSupport: Declares whether a component supports snapshot persistence.
SpawnError: Error when spawning a child fails.
Status: Component execution status.

Constants§

PACKAGE_VERSION: Current package format version.
SNAPSHOT_VERSION: Current snapshot format version.

Traits§

AsyncChildContext: Async context provided to Children for runtime interaction.
AsyncChildHandle: Async handle to a spawned child.
AsyncRunnableChild: Async version of RunnableChild.
Child: A child entity managed by a Component.
ChildContext: Context provided to Children for runtime interaction.
ChildHandle: Handle to a spawned child (synchronous).
Component: Component trait for EventBus participants.
ComponentLoader: Loader for creating Components from scripts.
Emitter: Trait for emitting events from Components.
Identifiable: Identifiable component or child.
Packageable: Trait for components that support package installation.
RunnableChild: A Child that can actively execute work.
SignalReceiver: Signal receiver for human control.
Snapshottable: Trait for components that support state persistence.
Statusable: Status reporting for monitoring.

Attribute Macros§

async_trait