clawft

IPC and A2A Messaging

Kernel IPC message envelopes, MessageTarget variants, MessagePayload types, A2A routing, GlobalPid for cross-node addressing, and request-response patterns.

WeftOS IPC provides typed message envelopes over the existing MessageBus from clawft-core. The KernelIpc subsystem adds PID-based routing, agent-to-agent delivery with capability checks, and pub/sub topic routing.

Source: crates/clawft-kernel/src/ipc.rs, crates/clawft-kernel/src/a2a.rs, crates/clawft-kernel/src/topic.rs

KernelMessage Envelope

Every message in the kernel IPC system is wrapped in a KernelMessage:

pub struct KernelMessage {
    pub id: String,
    pub from: Pid,
    pub target: MessageTarget,
    pub payload: MessagePayload,
    pub timestamp: DateTime<Utc>,
    pub correlation_id: Option<String>,
    pub trace_id: Option<String>,
}

MessageTarget Variants

pub enum MessageTarget {
    /// Send to a specific process by PID.
    Process(Pid),
    /// Publish to a named topic (all subscribers receive).
    Topic(String),
    /// Broadcast to all processes.
    Broadcast,
    /// Send to a named service (routed via ServiceRegistry).
    Service(String),
    /// Send to a specific method on a named service (K2.1, D19).
    ServiceMethod { service: String, method: String },
    /// Send to the kernel itself.
    Kernel,
    /// Route to a specific process on a remote node (K6).
    RemoteNode { node_id: String, target: Box<MessageTarget> },
}

The Service and ServiceMethod variants (K2.1 Symposium D19) support service-oriented routing through the ServiceRegistry. The RemoteNode variant (K6) wraps an inner MessageTarget with a remote node ID for cross-node messaging.

MessagePayload Variants

pub enum MessagePayload {
    Text(String),
    Json(serde_json::Value),
    ToolCall { name: String, args: serde_json::Value },
    ToolResult { call_id: String, result: serde_json::Value },
    Signal(KernelSignal),
    Binary(Vec<u8>),
    Rvf { segment_type: u8, data: Vec<u8> },
}

pub enum KernelSignal {
    Shutdown, Suspend, Resume, Ping, Pong, ReloadConfig, DumpState,
}

A2ARouter Routing Flow

A2ARouter::send (a2a.rs) does these steps in order:

  1. The sender must exist in the process table and be Running or Suspended.
  2. With exochain, the routing-time gate runs (first layer of dual-layer governance). The gate action is tool.<name> for a tool call, ipc.signal for a signal and ipc.send otherwise. A Deny returns CapabilityDenied before any inbox is reached. A Defer or Permit continues: a deferred message is still delivered, and the handler-time gate in the agent loop makes the final call.
  3. The router routes by target. Process(pid) runs check_ipc_target, Topic(name) runs check_ipc_topic and fans out through the TopicRouter, and the other variants (Broadcast, Service, ServiceMethod, Kernel, RemoteNode) go to their own delivery paths. RemoteNode uses the mesh runtime's remote forwarder.
  4. The message is delivered to the target's inbox.

A2ARouter public API

The main methods (all in a2a.rs):

impl A2ARouter {
    pub fn create_inbox(&self, pid: Pid) -> mpsc::Receiver<KernelMessage>;
    pub fn remove_inbox(&self, pid: Pid);
    pub async fn send(&self, msg: KernelMessage) -> KernelResult<()>;
    pub async fn send_checked(&self, msg: KernelMessage, chain: Option<&ChainManager>) -> KernelResult<()>; // logs ipc.send, then send()
    pub async fn request(&self, msg: KernelMessage, timeout: Duration) -> KernelResult<KernelMessage>;
    pub fn try_complete_request(&self, msg: KernelMessage) -> bool;
    pub fn topic_router(&self) -> &Arc<TopicRouter>;
    pub fn set_gate(&self, gate: Arc<dyn GateBackend>);
    pub fn set_dead_letter_queue(&self, dlq: Arc<DeadLetterQueue>);
    pub fn set_mesh_runtime(&self, runtime: Arc<MeshRuntime>);
}

GlobalPid

For cross-node addressing (K6):

pub struct GlobalPid {
    pub node_id: MeshNodeId,
    pub pid: Pid,
}
// Alias: CompositePid (WEFT-142)

Request-Response Pattern

A2ARouter::request(msg, timeout) registers a pending request keyed by msg.id, sends the message, and waits for a reply up to the timeout, returning KernelError::Timeout if none arrives. The replying agent sets correlation_id to the original id; try_complete_request matches it to the pending request.

Topic Pub/Sub

The TopicRouter (crates/clawft-kernel/src/topic.rs) holds subscriptions in a DashMap. A subscriber is a PID or, since subscriptions were generalized, a SubscriberSink:

impl TopicRouter {
    pub fn subscribe(&self, pid: Pid, topic: &str);
    pub fn subscribe_sink(&self, topic: &str, sink: SubscriberSink) -> SubscriberId;
    pub fn unsubscribe(&self, pid: Pid, topic: &str);
    pub fn unsubscribe_id(&self, topic: &str, id: SubscriberId);
    pub fn subscribers(&self, topic: &str) -> Vec<Pid>;
    pub fn list_topics(&self) -> Vec<(String, usize)>;
    pub fn unsubscribe_all(&self, pid: Pid);
}

Chain Logging

When exochain is enabled, IPC events are logged:

Event KindTrigger
ipc.sendMessage sent via A2ARouter (a2a.rs)
ipc.recvMessage received by agent loop (agent_loop.rs)
ipc.ackMessage processed by agent loop (agent_loop.rs)

Built-in Agent Loop Commands

The kernel agent loop (crates/clawft-kernel/src/agent_loop.rs) processes:

CommandGate ActionDescription
suspend--Pause the agent
resume--Resume a paused agent
exec"tool.exec"Execute a tool (gate checked)
cron.add"service.cron.add"Register a cron job
cron.remove"service.cron.remove"Remove a cron job
cron.list--List cron jobs
ping--Reply with status, PID and uptime

On this page