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:
- The sender must exist in the process table and be
RunningorSuspended. - With
exochain, the routing-time gate runs (first layer of dual-layer governance). The gate action istool.<name>for a tool call,ipc.signalfor a signal andipc.sendotherwise. ADenyreturnsCapabilityDeniedbefore any inbox is reached. ADeferorPermitcontinues: a deferred message is still delivered, and the handler-time gate in the agent loop makes the final call. - The router routes by target.
Process(pid)runscheck_ipc_target,Topic(name)runscheck_ipc_topicand fans out through theTopicRouter, and the other variants (Broadcast,Service,ServiceMethod,Kernel,RemoteNode) go to their own delivery paths.RemoteNodeuses the mesh runtime's remote forwarder. - 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 Kind | Trigger |
|---|---|
ipc.send | Message sent via A2ARouter (a2a.rs) |
ipc.recv | Message received by agent loop (agent_loop.rs) |
ipc.ack | Message processed by agent loop (agent_loop.rs) |
Built-in Agent Loop Commands
The kernel agent loop (crates/clawft-kernel/src/agent_loop.rs) processes:
| Command | Gate Action | Description |
|---|---|---|
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 |
Process Table
PID allocation, process state machine, ProcessEntry fields, resource tracking, and agent supervisor integration in WeftOS.
Capabilities and RBAC
Agent capability model: AgentCapabilities, IpcScope, ToolPermissions, SandboxPolicy, ResourceLimits, the CapabilityChecker, and governance-gated elevation.