Communication Manager

Communication Manager is the internal message router for Hiro Server. Channel Manager owns transport and plugin processes. Agent Manager owns LLM execution. Communication Manager sits between them. It validates inbound UnifiedMessage payloads, routes them by message_type, enriches user messages before they reach the agent, and sends outbound messages back to the correct channel. The component is a small runtime facade over focused collaborators. Its job is composition, routing, queue ownership, and lifecycle.

​

Responsibilities

Inbound validation - InboundPipeline.receive() is the Channel Manager’s on_message callback target. It validates raw dictionaries into UnifiedMessage objects before any downstream component sees them. Inbound routing - The inbound pipeline applies the permission placeholder, then dispatches by message_type: message goes to MessageFlow, request goes to RequestHandler, event goes to EventHandler, and unknown types produce a routing-error response. Message acknowledgment - MessageFlow immediately emits a message.received event for each inbound message. This gives the device a delivery signal before adaptation or agent work starts. Content adaptation - MessageFlow runs MessageAdapterPipeline in a background task. Audio and image adapters enrich content items by writing metadata.description; adapter failures write metadata.adapter_error. Post-adapt side effects - Post-adapt hooks run after enrichment. They log adapter errors, emit transcript events, persist inbound messages, and finally enqueue the enriched message for Agent Manager. Request and event dispatch - RequestHandler handles request/response methods such as channels.list, messages.history, and policy.get. EventHandler handles application-level message events carried as UnifiedMessage objects. Outbound dispatch - OutboundPipeline owns the outbound queue. It drains messages, applies the outbound permission placeholder, and calls the configured OutboundSink, currently ChannelManager.send_to_channel().

---

​

Main components

​

CommunicationManager

The facade in runtime/communication_manager.py. It wires the inbound pipeline, outbound pipeline, message flow, adapter pipeline, request handler, event handler, and post-adapt hook chain.

​

InboundPipeline

The inbound router. It validates raw input, runs inbound permission checks, opens logging scope, and dispatches by message_type. It is callback-driven. There is no inbound worker today; Channel Manager calls receive() directly for each channel.receive notification.

​

OutboundPipeline

OutboundPipeline owns the outbound FIFO queue and its worker. OutboundSink is the protocol it depends on.

​

EnvelopeFactory

The central builder for server-originated UnifiedMessage envelopes. It creates:

---

​

Handlers

​

1. Message Handler

MessageFlow The handler for message_type == "message". It does two things: emit message.received immediately, then spawn a detached adaptation task. This keeps channel receive latency low even when audio transcription or image analysis takes time. MessageAdapterPipeline The media enrichment layer. It runs applicable adapters concurrently for a single message. The original ContentItem.body remains unchanged. Post-adapt hooks Post-adapt hooks are ordered side-effect units that run after the adapter pipeline. The order matters. Agent Manager should only see a message after transcript events and persistence attempts have already been handled.

​

2. RequestHandler

The request method registry. It parses the first JSON content item in a request, calls the registered async method, and returns a response UnifiedMessage. The inbound pipeline receives that response and enqueues it through the normal outbound path.

​

3. EventHandler

The dispatcher for application-level message events. These are validated UnifiedMessage objects where message_type == "event". This is separate from ChannelEventHandler, which handles raw plugin infrastructure events such as pairing_request and gateway_connected.

​

Events

Communication Manager handles message events, not channel infrastructure events. Active server-originated message events:

---

​

Related components

​

Channel Manager

Channel Manager is the supplier of UnifiedMessages to Communication Manager through the InboundPipeline. Outbound Pipeline supplies UnifiedMessages back to Channel Manager through the OutboundSink.

​

Agent Manager

The primary consumer of inbound_queue. It is the AI brain of Hiro Server.

​

Resource Change Broadcaster

An outbound producer that emits resource.changed events when workspace resources change. It uses Communication Manager’s outbound queue but does not participate in inbound routing.

---

​

See also