UnifiedMessage payloads and channel events.
Plugin topology
The plugin owns translation between its external protocol andUnifiedMessage. Hiro Server owns workspace policy, routing, persistence, and agent execution.
Responsibilities
External protocol adaptation - The plugin translates between its external surface and Hiro’sUnifiedMessage format. For the built-in devices plugin, the external surface is Hiro Gate. For optional plugins, it can be a third-party messaging platform.
Connection to Channel Manager - The plugin process connects to Channel Manager using the WebSocket URL passed at launch. It registers its name, version, and description before it starts normal work.
Inbound emission - When the external surface produces a user message, the plugin validates or normalizes it into a UnifiedMessage and emits it to Channel Manager as channel.receive.
Outbound dispatch - When Hiro Server sends a message through this channel, the plugin receives channel.send and translates the UnifiedMessage into the external protocol’s send operation.
Channel events - The plugin emits channel.event for transport and infrastructure state that is not itself a user message, such as gateway connection state, device connection state, or pairing requests.
Lifecycle handling - The plugin receives configuration after registration, starts its external listeners, handles reconnects where applicable, and stops cleanly when Channel Manager sends channel.stop.
Runtime lifecycle
Channel Manager appends runtime arguments when it starts a plugin: the local Hiro WebSocket URL, log directory, and log level. The plugin’s entry point uses those values to initialize logging and createPluginTransport.
JSON-RPC surface
All plugin-to-server traffic uses JSON-RPC 2.0 over one local WebSocket connection.Plugin to Channel Manager
| Method | Purpose |
|---|---|
channel.register | Announces the plugin connection and metadata. This is the first required frame after connect. |
channel.receive | Sends an inbound UnifiedMessage into Hiro Server. |
channel.event | Sends plugin infrastructure events into Hiro Server. |
Channel Manager to plugin
| Method | Purpose |
|---|---|
channel.configure | Pushes channel-specific settings and credentials from workspace configuration. |
channel.send | Sends an outbound UnifiedMessage through this channel. |
channel.event | Sends server-originated infrastructure events to the plugin. |
channel.status | Probes live plugin status. |
channel.stop | Requests graceful plugin shutdown. |
Persisted configuration
Channel plugin configuration is stored in thechannel_plugins table in workspace.db.
| Item | Purpose |
|---|---|
| Channel name | Stable channel identifier, such as devices, telegram, or echo. |
| Enabled state | Controls whether Channel Manager spawns the plugin at server startup. |
| Launch command | Command used to start the plugin process. |
| Workspace directory | Optional uv workspace directory used for development launches. |
| Config payload | Channel-specific settings pushed to the plugin through channel.configure. |
channels/<channel_name>.pid. Plugin logs are written under logs/channel-<name>.log.
Built-in devices plugin
The devices channel plugin is built in and required. It bridges Hiro Server to Hiro Gate.
| Direction | What it translates |
|---|---|
| Gateway to Hiro Server | Gateway relay frames into inbound UnifiedMessage payloads or channel events. |
| Hiro Server to Gateway | Outbound UnifiedMessage payloads into gateway relay frames. |
| Gateway infrastructure | Pairing requests and device connection state into channel.event. |
| Server infrastructure | Pairing responses from Hiro Server into gateway pairing response frames. |
Related components
Channel Manager
Channel Manager owns plugin process lifecycle, WebSocket accept, JSON-RPC dispatch, and the connection registry. See Channel Manager.Communication Manager
Communication Manager receives validatedUnifiedMessage payloads from Channel Manager and owns message routing inside Hiro Server. See Communication Manager.
Protocol contract
Channel plugins exchangeUnifiedMessage payloads with Hiro Server. See Protocol contract and UnifiedMessage reference.
See also
Channel Manager
The server-side owner of channel plugin subprocesses and JSON-RPC connections.
Creating channel plugins
Build guide for implementing a new plugin.
UnifiedMessage reference
The message envelope exchanged by plugins and Hiro Server.