zulip-platform-plugins/docs/adr/ADR-008-native-message-format.md

ADR 8: Platform-Native Message Formats

Date: 2026-04-28

Decision

Each plugin sends and receives messages using its platform's native format (Hermes MessageEvent, openclaw message objects, Agent Zero message types) rather than a cross-platform envelope.

Context

Platform-native message formats carry richer context (threading, state, metadata) that the platform's event loop depends on. Wrapping them in a cross-platform envelope would strip useful metadata and increase parsing overhead on every message.

Consequences

• Plugin implementations must understand their platform's message types
• Enriched metadata (sender, topic, stream, message_id) is available to the agent naturally
• No serialization/deserialization overhead for local messages
• Each plugin's message handling code is cleaner and more idiomatic