Trait ChildContext 

pub trait ChildContext:
    Send
    + Sync
    + Debug {
    // Required methods
    fn parent_id(&self) -> &str;
    fn emit_output(&self, message: &str);
    fn emit_output_with_level(&self, message: &str, level: &str);
    fn spawn_child(
        &self,
        config: ChildConfig,
    ) -> Result<Box<dyn ChildHandle>, SpawnError>;
    fn child_count(&self) -> usize;
    fn max_children(&self) -> usize;
    fn send_to_child(
        &self,
        child_id: &str,
        input: Value,
    ) -> Result<ChildResult, RunError>;
    fn clone_box(&self) -> Box<dyn ChildContext>;

    // Provided methods
    fn emit_approval_request(
        &self,
        _operation: &str,
        _description: &str,
    ) -> String { ... }
    fn send_to_child_async(
        &self,
        _child_id: &str,
        _input: Value,
    ) -> Result<(), RunError> { ... }
    fn send_to_children_batch(
        &self,
        requests: Vec<(String, Value)>,
    ) -> Vec<(String, Result<ChildResult, RunError>)> { ... }
    fn spawn_runner_from_script(
        &self,
        _script: &str,
        _id: Option<&str>,
        _globals: Option<&Map<String, Value>>,
    ) -> Result<(ChannelId, String), SpawnError> { ... }
    fn spawn_runner_from_builtin(
        &self,
        _name: &str,
        _id: Option<&str>,
        _globals: Option<&Map<String, Value>>,
    ) -> Result<(ChannelId, String), SpawnError> { ... }
    fn capabilities(&self) -> Capability { ... }
    fn has_capability(&self, cap: Capability) -> bool { ... }
    fn can_execute_command(&self, _cmd: &str) -> bool { ... }
    fn check_command_permission(&self, _cmd: &str) -> CommandPermission { ... }
    fn is_command_granted(&self, _cmd: &str) -> bool { ... }
    fn grant_command(&self, _pattern: &str) { ... }
    fn can_spawn_child_auth(&self) -> bool { ... }
    fn can_spawn_runner_auth(&self) -> bool { ... }
    fn request(
        &self,
        _target_fqn: &str,
        _operation: &str,
        _payload: Value,
        _timeout_ms: Option<u64>,
    ) -> Result<Value, String> { ... }
    fn request_batch(
        &self,
        requests: Vec<(String, String, Value, Option<u64>)>,
    ) -> Vec<Result<Value, String>> { ... }
    fn extension(&self, _key: &str) -> Option<Box<dyn Any + Send + Sync>> { ... }
    fn request_stop(&self) -> Result<(), String> { ... }
}

Context provided to Children for runtime interaction.

This trait defines the safe interface that Children can use to interact with the runtime. Implementations are provided by the Runner.

Thread Safety

Implementations must be Send + Sync to allow Children to hold references across thread boundaries.

Example

struct MyChild {
    id: String,
    ctx: Option<Box<dyn ChildContext>>,
}

impl RunnableChild for MyChild {
    fn run(&mut self, input: Value) -> ChildResult {
        if let Some(ctx) = &self.ctx {
            ctx.emit_output("Starting work...");

            // Spawn a sub-child
            let config = ChildConfig::from_inline("sub-1", "...");
            if let Ok(mut handle) = ctx.spawn_child(config) {
                let sub_result = handle.run_sync(input.clone());
                // ...
            }
        }
        ChildResult::Ok(input)
    }
}

Required Methods

fn parent_id(&self) -> &str

Returns the parent’s ID (Component or Child that owns this context).

fn emit_output(&self, message: &str)

Emits output to the parent (displayed to user via IO).

Arguments

• message - Message to display

fn emit_output_with_level(&self, message: &str, level: &str)

Emits output with a specific level.

Arguments

• message - Message to display
• level - Log level (“info”, “warn”, “error”)

fn spawn_child( &self, config: ChildConfig, ) -> Result<Box<dyn ChildHandle>, SpawnError>

Spawns a child and returns a sync handle to control it.

For async spawning, see AsyncChildContext::spawn_child.

Arguments

• config - Configuration for the child

Returns

A handle to the spawned child, or an error if spawn failed.

Errors

• SpawnError::MaxChildrenReached if limit exceeded
• SpawnError::ScriptNotFound if script file doesn’t exist
• SpawnError::InvalidScript if script is malformed
• SpawnError::AlreadyExists if ID is already in use

fn child_count(&self) -> usize

Returns the number of active children.

fn max_children(&self) -> usize

Returns the maximum allowed children.

fn send_to_child( &self, child_id: &str, input: Value, ) -> Result<ChildResult, RunError>

Sends input to a child by ID and returns its result.

Arguments

• child_id - The child’s ID
• input - Input data to pass to the child

Returns

The child’s result.

Errors

• RunError::NotFound if child doesn’t exist
• RunError::ExecutionFailed if child execution fails

fn clone_box(&self) -> Box<dyn ChildContext>

Clones this context into a boxed trait object.

Provided Methods

fn emit_approval_request(&self, _operation: &str, _description: &str) -> String

Emits an approval request for HIL flow.

Generates a unique approval ID and emits the request to the output channel so it can be displayed to the user.

Returns

The generated approval ID that can be matched in on_signal.

Default Implementation

Returns empty string (no-op for backward compatibility).

fn send_to_child_async( &self, _child_id: &str, _input: Value, ) -> Result<(), RunError>

Sends input to a child asynchronously (fire-and-forget).

Unlike send_to_child, this method returns immediately without waiting for the child to complete. The child runs in a background thread and its output flows through emit_output automatically.

Arguments

• child_id - The child’s ID
• input - Input data to pass to the child

Returns

Ok(()) if the child was found and background execution started.

Errors

• RunError::NotFound if child doesn’t exist
• RunError::ExecutionFailed if spawner lock fails

Default Implementation

Returns an error indicating async send is not supported.

fn send_to_children_batch( &self, requests: Vec<(String, Value)>, ) -> Vec<(String, Result<ChildResult, RunError>)>

Sends input to multiple children in parallel and returns all results.

Each (child_id, input) pair is executed concurrently using OS threads. The spawner lock is held only briefly to collect child references, then released before execution begins.

Arguments

• requests - Vec of (child_id, input) pairs

Returns

Vec of (child_id, Result<ChildResult, RunError>) in the same order.

Default Implementation

Falls back to sequential send_to_child calls.

fn spawn_runner_from_script( &self, _script: &str, _id: Option<&str>, _globals: Option<&Map<String, Value>>, ) -> Result<(ChannelId, String), SpawnError>

Spawns a Component as a separate ChannelRunner from a script.

This creates a new Channel in the World and spawns a ChannelRunner to execute the Component in parallel. The Component is created from the provided script content.

Arguments

• script - Inline script content (e.g., Lua component script)
• id - Optional component ID (extracted from script if None)
• globals - Optional key-value pairs to inject into the VM. See ComponentLoader::load_from_script for the rationale behind using Map<String, Value> instead of a generic serde_json::Value.

Returns

A tuple of (ChannelId, fqn_string) for the spawned runner, or an error if spawning failed. The FQN enables immediate orcs.request(fqn, ...) communication.

Default Implementation

Returns SpawnError::Internal indicating runner spawning is not supported. Implementations that support runner spawning should override this.

fn spawn_runner_from_builtin( &self, _name: &str, _id: Option<&str>, _globals: Option<&Map<String, Value>>, ) -> Result<(ChannelId, String), SpawnError>

Spawns a ChannelRunner from a builtin component name.

Resolves the builtin name to script content via the component loader, then delegates to spawn_runner_from_script.

Arguments

• name - Builtin component filename (e.g., "delegate_worker.lua")
• id - Optional component ID override
• globals - Optional key-value pairs to inject into the VM as global variables

Default Implementation

Returns SpawnError::Internal indicating builtin spawning is not supported.

fn capabilities(&self) -> Capability

Returns the capabilities granted to this context.

Default Implementation

Returns Capability::ALL (permissive mode for backward compatibility). Override this to restrict the capabilities available to children.

fn has_capability(&self, cap: Capability) -> bool

Checks if this context has a specific capability.

Equivalent to self.capabilities().contains(cap).

fn can_execute_command(&self, _cmd: &str) -> bool

Checks if command execution is allowed.

Default Implementation

Returns true (permissive mode for backward compatibility). Implementations with session/checker support should override this.

fn check_command_permission(&self, _cmd: &str) -> CommandPermission

Checks command with granular permission result.

Returns CommandPermission with three possible states:

• Allowed: Execute immediately
• Denied: Block with reason
• RequiresApproval: Needs user approval before execution

Default Implementation

Returns Allowed (permissive mode for backward compatibility).

fn is_command_granted(&self, _cmd: &str) -> bool

Checks if a command pattern has been granted (without elevation bypass).

Returns true if the command matches a previously granted pattern. Unlike check_command_permission, this does NOT consider session elevation — only explicit grants.

Default Implementation

Returns false (no grants in permissive mode).

fn grant_command(&self, _pattern: &str)

Grants a command pattern for future execution.

After HIL approval, call this to allow matching commands without re-approval.

Default Implementation

No-op (for backward compatibility).

fn can_spawn_child_auth(&self) -> bool

Checks if child spawning is allowed.

Default Implementation

Returns true (permissive mode for backward compatibility).

fn can_spawn_runner_auth(&self) -> bool

Checks if runner spawning is allowed.

Default Implementation

Returns true (permissive mode for backward compatibility).

fn request( &self, _target_fqn: &str, _operation: &str, _payload: Value, _timeout_ms: Option<u64>, ) -> Result<Value, String>

Sends an RPC request to another Component by FQN.

Arguments

• target_fqn - FQN of the target component (e.g. "skill::skill_manager")
• operation - The operation to invoke (e.g. "list", "catalog")
• payload - JSON payload for the operation
• timeout_ms - Optional timeout in milliseconds

Returns

The response value from the target component.

Default Implementation

Returns an error indicating RPC is not supported.

fn request_batch( &self, requests: Vec<(String, String, Value, Option<u64>)>, ) -> Vec<Result<Value, String>>

Sends multiple RPC requests in parallel and returns all results.

Each request is a tuple of (target_fqn, operation, payload, timeout_ms). Results are returned in the same order as the input.

Default Implementation

Falls back to sequential request() calls.

fn extension(&self, _key: &str) -> Option<Box<dyn Any + Send + Sync>>

Returns a type-erased runtime extension by key.

Enables runtime-layer constructs (e.g., hook registries) to pass through the Plugin SDK layer without introducing layer-breaking dependencies.

Default Implementation

Returns None (no extensions available).

fn request_stop(&self) -> Result<(), String>

Requests graceful termination of this component’s own ChannelRunner.

Sends an Abort transition to the WorldManager, causing the runner to exit its event loop cleanly after the current request completes. The RunnerMonitor will broadcast a Lifecycle::runner_exited event.

Use Cases

• Per-delegation workers that complete a single task and should release resources
• Components that detect they are no longer needed

Default Implementation

Returns an error indicating self-stop is not supported.

Trait Implementations

impl Clone for Box<dyn ChildContext>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

Implementors