Protocol contract - Hiro League

The protocol contract is the language-neutral wire contract for Hiro League messages. It defines the JSON shapes that move between Hiro Server, channel plugins, Hiro Gate, and device apps. Python, Dart, and any future client implementation must parse and emit the same contract.

Contract surfaces

Surface	Owner	Purpose
`UnifiedMessage`	Hiro protocol	Canonical message, event, request, and response envelope.
Gateway relay envelope	Hiro Gate protocol	Routes payloads between connected devices and the devices channel plugin.
Auth frames	Hiro Gate protocol	Authenticates an already-paired device connection.
Pairing frames	Hiro Gate protocol	Pairs a new device with a workspace.
Request and response body	Hiro protocol	Carries device RPC calls and server replies inside JSON content items.
Metadata keys	Hiro protocol	Carries routing extras such as device identity and channel context.

The machine-readable contract lives under the repo-level protocol/ folder. The explanatory protocol references live under docs/protocol/.

UnifiedMessage

UnifiedMessage is the canonical cross-channel message envelope.

Field	Type	Required	Meaning
`version`	string	yes	Protocol version. Current value is `"0.1"`.
`message_type`	string	yes	One of `message`, `event`, `request`, `response`, or reserved `stream`.
`request_id`	string or null	no	Correlation ID for request/response messages.
`routing`	object	yes	Sender, recipient, channel, direction, timestamp, and metadata.
`content`	array	yes	Ordered content items. Empty for event messages.
`event`	object or null	no	Event payload. Present only for event messages.

Message type rules

`message_type`	Required shape
`message`	`content` has at least one item. `event` is absent or null.
`event`	`event` is present. `content` is empty.
`request`	`request_id` is present. `content` contains a JSON request body.
`response`	`request_id` matches the request. `content` contains a JSON response body.
`stream`	Reserved for future streaming chunks.

Routing

routing identifies where the message came from, where it should go, and how it should be grouped.

Field	Meaning
`id`	Message identifier.
`channel`	Channel name, such as `devices` or `telegram`.
`direction`	Direction from the Hiro Server perspective.
`sender_id`	Originating device, user, service, or server actor.
`recipient_id`	Target device, user, service, or null for broadcast or server-directed messages.
`timestamp`	Message timestamp.
`metadata`	Protocol-defined routing extras.

direction is normalized before a message enters Hiro Server:

Value	Meaning
`inbound`	Arriving into Hiro Server from a device, plugin, or third-party app.
`outbound`	Leaving Hiro Server toward a device, plugin, or third-party app.

Device-originated messages are normalized by the devices channel before they enter Communication Manager. Inside Hiro Server, consumers can treat direction as server-relative.

Content items

Each content item represents one authored payload.

Field	Meaning
`content_type`	Payload kind, such as `text`, `audio`, `image`, `file`, or `json`.
`body`	Payload value. Text content is plain text. Binary media is represented by a URL, path, or encoded value according to the content type.
`metadata`	Content-specific extras such as filename, MIME type, duration, transcript, or adapter error.

Content order is meaningful. Consumers preserve the order emitted by the sender.

Events

Event messages use message_type: "event" and carry an event payload.

Field	Meaning
`type`	Dotted event name.
`ref_id`	Optional ID of the message or entity the event refers to.
`data`	Event-specific payload.

Active message events:

Event	Purpose
`message.received`	Acknowledges that an inbound message was accepted.
`message.transcribed`	Adds transcript data for an audio message.
`message.voiced`	Adds synthesized voice data for a text reply.
`resource.changed`	Tells connected devices to refresh a workspace resource.

Requests and responses

Requests and responses are UnifiedMessage objects with content_type: "json". Request body:

{
  "method": "channels.list",
  "params": {}
}

Response body:

{
  "status": "ok",
  "data": {}
}

Error response body:

{
  "status": "error",
  "error": {
    "code": "method_not_found",
    "message": "Unknown method"
  }
}

request_id is generated by the caller and echoed by the responder.

Gateway envelopes

Hiro Gate wraps forwarded device payloads in a relay envelope.

{
  "sender_device_id": "device-id",
  "target_device_id": "optional-target-device-id",
  "payload": {}
}

sender_device_id identifies the connected device that produced the payload. target_device_id is optional and targets a specific connected device when present. payload contains the protocol payload being relayed.

Auth and pairing frames

Gateway auth and pairing frames are type-discriminated JSON objects.

Frame type	Direction	Purpose
`auth_challenge`	Gateway to device	Starts device authentication.
`auth_response`	Device to gateway	Proves the device has valid pairing credentials.
`auth_ok`	Gateway to device	Confirms the authenticated connection.
`pairing_request`	Device to gateway	Starts pairing for a new device.
`pairing_pending`	Gateway to device	Confirms that pairing is waiting for server approval.
`pairing_response`	Gateway to device	Returns approved pairing credentials or a rejection.

Metadata keys

Protocol metadata keys are part of the contract when behavior depends on them.

Key	Location	Meaning
`channel_id`	`routing.metadata`	Conversation or channel grouping key.
`device_name`	`routing.metadata`	Human-readable device name.
`sender_device_id`	`routing.metadata`	Device ID attached by the gateway or devices channel.
`friendly_name`	`routing.metadata`	Display name for a device or participant.
`request_voice_reply`	`routing.metadata`	Requests a voice reply when the server can produce one.

Compatibility contract

The protocol is valid when all supported implementations agree on the same fixtures:

Fixture class	Requirement
Valid fixtures	Python and Dart parse them successfully.
Invalid fixtures	Python and Dart reject them consistently.
Outbound fixtures	Serialization from each implementation matches the documented wire shape.

Schema files and fixtures are the reviewable source of truth. Runtime models in Python and Dart implement that contract.

UnifiedMessage reference

Detailed field reference, validation rules, constants, and wire examples.

Communication Manager

How Hiro Server validates, routes, adapts, and dispatches UnifiedMessages.

Channel Manager

How channel plugins send and receive UnifiedMessages through Hiro Server.

Gateway runtime

How Hiro Gate handles device connections.

Channel Plugins

The plugin-side JSON-RPC contract around UnifiedMessage payloads.

​Contract surfaces

​UnifiedMessage

​Message type rules

​Routing

​Content items

​Events

​Requests and responses

​Gateway envelopes

​Auth and pairing frames

​Metadata keys

​Compatibility contract

​See also