Channels Module

Overview

Channels receive messages from external sources (CLI, HTTP, WebSockets, etc.) and convert them to a unified message format for the agent to process. The channel system supports:

Multiple concurrent input channels
Unified message abstraction
Streaming message delivery
Channel-specific metadata
WASM-based dynamic channel loading

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                         ChannelManager                              │
│                                                                     │
│   ┌──────────────┐   ┌─────────────┐   ┌─────────────┐             │
│   │ ReplChannel  │   │ HttpChannel │   │ WasmChannel │   ...       │
│   └──────┬───────┘   └──────┬──────┘   └──────┬──────┘             │
│          │                 │                 │                      │
│          └─────────────────┴─────────────────┘                      │
│                            │                                        │
│                   select_all (futures)                              │
│                            │                                        │
│                            ▼                                        │
│                     MessageStream                                   │
└─────────────────────────────────────────────────────────────────────┘

Core Types

Channel Trait

The main trait that all channels must implement.

#[async_trait]
pub trait Channel: Send + Sync {
    fn name(&self) -> &str;
    fn message_stream(&self) -> MessageStream;
    async fn send(&self, response: OutgoingResponse) -> Result<(), ChannelError>;
    async fn send_status(&self, status: StatusUpdate) -> Result<(), ChannelError>;
}

Methods

fn(&self) -> &str

Return the channel name (must be unique)

fn(&self) -> MessageStream

Get a stream of incoming messages from this channel

async fn(&self, response: OutgoingResponse) -> Result<()>

Send a response back through this channel

async fn(&self, status: StatusUpdate) -> Result<()>

Send a status update (typing indicator, progress, etc.)

IncomingMessage

A message received from an external channel.

Uuid

Unique message identifier

String

Channel this message came from

String

User identifier within the channel

Option<String>

Optional display name for the user

String

Message content/text

Option<String>

Thread/conversation ID for threaded conversations

DateTime<Utc>

When the message was received

serde_json::Value

Channel-specific metadata

Constructors

fn(channel: impl Into<String>, user_id: impl Into<String>, content: impl Into<String>) -> Self

Create a new incoming message

fn(self, thread_id: impl Into<String>) -> Self

Set the thread ID

fn(self, metadata: serde_json::Value) -> Self

Set channel-specific metadata

fn(self, name: impl Into<String>) -> Self

Set the user’s display name

Example

use ironclaw::channels::IncomingMessage;

let msg = IncomingMessage::new("slack", "U12345", "Hello agent!")
    .with_thread("C67890")
    .with_user_name("Alice");

OutgoingResponse

A response to send back through a channel.

String

The content to send

Option<String>

Optional thread ID to reply in

Vec<String>

Optional file paths to attach

serde_json::Value

Channel-specific metadata for the response

Constructors

fn(content: impl Into<String>) -> Self

Create a simple text response

fn(self, thread_id: impl Into<String>) -> Self

Set the thread ID for the response

fn(self, attachments: Vec<String>) -> Self

Add file attachments

fn(self, metadata: serde_json::Value) -> Self

Set channel-specific metadata

Example

use ironclaw::channels::OutgoingResponse;

let response = OutgoingResponse::text("Task completed!")
    .in_thread("C67890")
    .with_attachments(vec!["report.pdf".to_string()]);

channel.send(response).await?;

StatusUpdate

Status updates sent during processing (typing indicators, progress, etc.).

StatusKind

Type of status update

Option<String>

Optional status message

Option<f32>

Optional progress (0.0 to 1.0)

StatusKind

()

Agent is typing/thinking

()

Agent is processing the request

String

Agent is executing a tool (includes tool name)

()

Processing is complete

Example

use ironclaw::channels::{StatusUpdate, StatusKind};

let status = StatusUpdate {
    kind: StatusKind::ToolExecution("http".to_string()),
    message: Some("Fetching data...".to_string()),
    progress: Some(0.5),
};

channel.send_status(status).await?;

MessageStream

A stream of incoming messages from a channel.

pub type MessageStream = Pin<Box<dyn Stream<Item = IncomingMessage> + Send>>;

Use with async stream combinators:

use futures::StreamExt;

let mut stream = channel.message_stream();
while let Some(msg) = stream.next().await {
    println!("Received: {} from {}", msg.content, msg.user_id);
}

Built-in Channels

ReplChannel

Interactive command-line REPL channel.

fn() -> Self

Create a new REPL channel with stdin/stdout

fn(prompt: impl Into<String>) -> Self

Set a custom prompt string

use ironclaw::channels::ReplChannel;

let repl = ReplChannel::new().with_prompt("ironclaw> ");

HttpChannel

HTTP webhook receiver channel.

fn(addr: impl Into<SocketAddr>) -> Self

Create a new HTTP channel listening on the given address

fn(self, token: impl Into<String>) -> Self

Add bearer token authentication

use ironclaw::channels::HttpChannel;

let http = HttpChannel::new("127.0.0.1:8080")
    .with_auth("secret-token-123");

HTTP Endpoint

The HTTP channel exposes a POST endpoint:

curl -X POST http://localhost:8080/message \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer secret-token-123" \
  -d '{
    "user_id": "user_123",
    "content": "Hello agent!",
    "thread_id": "thread_456"
  }'

SignalChannel

Unix signal handler channel (SIGUSR1, SIGUSR2, etc.).

fn(signals: Vec<Signal>) -> Self

Create a signal channel that listens for the specified Unix signals

use ironclaw::channels::SignalChannel;
use signal_hook::consts::signal::*;

let signal_ch = SignalChannel::new(vec![SIGUSR1, SIGUSR2]);

GatewayChannel

WebSocket gateway for real-time bidirectional communication.

fn(addr: impl Into<SocketAddr>) -> Self

Create a WebSocket gateway listening on the given address

fn(self, auth_fn: AuthFn) -> Self

Add custom authentication function

use ironclaw::channels::GatewayChannel;

let gateway = GatewayChannel::new("127.0.0.1:9000");

Channel Manager

ChannelManager

Manages multiple channels and multiplexes their message streams.

fn() -> Self

Create a new channel manager

fn(&mut self, channel: Arc<dyn Channel>)

fn(&self) -> MessageStream

Get a unified stream of messages from all registered channels

async fn(&self, channel_name: &str, response: OutgoingResponse) -> Result<()>

Send a response to a specific channel

Example

use ironclaw::channels::{ChannelManager, ReplChannel, HttpChannel};
use futures::StreamExt;

let mut manager = ChannelManager::new();
manager.register(Arc::new(ReplChannel::new()));
manager.register(Arc::new(HttpChannel::new("127.0.0.1:8080")));

let mut stream = manager.message_stream();
while let Some(msg) = stream.next().await {
    // Process messages from all channels
    println!("[{}] {}: {}", msg.channel, msg.user_id, msg.content);
    
    // Send response back through the originating channel
    manager.send(
        &msg.channel,
        OutgoingResponse::text("Received!")
    ).await?;
}

WASM Channels

Dynamically load channel implementations at runtime using WebAssembly.

WasmChannel

A channel implementation loaded from a WASM module.

async fn(wasm_bytes: &[u8]) -> Result<Self>

Load a WASM module as a channel

async fn(path: &Path) -> Result<Self>

Load a WASM channel from a file

use ironclaw::channels::wasm::WasmChannel;

let wasm_bytes = std::fs::read("channels/discord.wasm")?;
let channel = WasmChannel::load(&wasm_bytes).await?;

manager.register(Arc::new(channel));

WASM Channel Interface

WASM channels must implement the following interface:

// Export these functions from your WASM module
#[no_mangle]
pub extern "C" fn channel_name() -> *const u8;

#[no_mangle]
pub extern "C" fn channel_init() -> i32;

#[no_mangle]
pub extern "C" fn channel_poll_message() -> *const u8;

#[no_mangle]
pub extern "C" fn channel_send_response(response_ptr: *const u8, response_len: usize) -> i32;

See the wasm module documentation for full details on the WASM channel ABI.

Error Handling

ChannelError

Errors that can occur during channel operations.

String

Failed to establish connection

String

Failed to send message/response

String

Received malformed message

String

Authentication/authorization failed

String

Channel or resource not found

WebSocket Gateway

The GatewayChannel provides a production-ready WebSocket server for real-time communication.

Client Connection

const ws = new WebSocket('ws://localhost:9000');

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'message',
    user_id: 'user_123',
    content: 'Hello agent!',
    thread_id: 'thread_456'
  }));
};

ws.onmessage = (event) => {
  const response = JSON.parse(event.data);
  console.log('Agent:', response.content);
};

Status Updates

The gateway sends real-time status updates:

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  
  if (msg.type === 'status') {
    console.log('Status:', msg.kind, msg.message);
  } else if (msg.type === 'response') {
    console.log('Response:', msg.content);
  }
};

Best Practices

Channel isolation: Each channel should handle its own protocol/transport details
Unified messages: Convert channel-specific formats to IncomingMessage early
Metadata: Use the metadata field for channel-specific context (message IDs, etc.)
Error handling: Channels should gracefully handle disconnections and reconnect
Authentication: Validate users before accepting messages
Rate limiting: Consider rate limiting per user/channel to prevent abuse

Agent Module

Agent orchestration and message processing

Tools Module

Tools that agents can use to respond to messages

Core Modules

Built-in Tools

Overview

Architecture

Core Types

Channel Trait

Methods

IncomingMessage

Constructors

Example

OutgoingResponse

Constructors

Example

StatusUpdate

StatusKind

Example

MessageStream

Built-in Channels

ReplChannel

HttpChannel

HTTP Endpoint

SignalChannel

GatewayChannel

Channel Manager

ChannelManager

Example

WASM Channels

WasmChannel

WASM Channel Interface

Error Handling

ChannelError

WebSocket Gateway

Client Connection

Status Updates

Best Practices

Agent Module

Tools Module

​Overview

​Architecture

​Core Types

​Channel Trait

​Methods

​IncomingMessage

​Constructors

​Example

​OutgoingResponse

​Constructors

​Example

​StatusUpdate

​StatusKind

​Example

​MessageStream

​Built-in Channels

​ReplChannel

​HttpChannel

​HTTP Endpoint

​SignalChannel

​GatewayChannel

​Channel Manager

​ChannelManager

​Example

​WASM Channels

​WasmChannel

​WASM Channel Interface

​Error Handling

​ChannelError

​WebSocket Gateway

​Client Connection

​Status Updates

​Best Practices

​Related Modules

Agent Module

Tools Module

Overview

Architecture

Core Types

Channel Trait

Methods

IncomingMessage

Constructors

Example

OutgoingResponse

Constructors

Example

StatusUpdate

StatusKind

Example

MessageStream

Built-in Channels

ReplChannel

HttpChannel

HTTP Endpoint

SignalChannel

GatewayChannel

Channel Manager

ChannelManager

Example

WASM Channels

WasmChannel

WASM Channel Interface

Error Handling

ChannelError

WebSocket Gateway

Client Connection

Status Updates

Best Practices

Related Modules