$mq9.AI.* Protocol Design

Overview

$mq9.AI.* is mq9's protocol for Agent asynchronous communication. The core problem solved: Asynchronous communication between Agents — sender and receiver do not need to be online simultaneously.

mq9 only solves the communication problem — how to reliably deliver messages. What the message contains, how it is used, and what the business semantics are — mq9 does not care. Message content is a byte array: not parsed, not validated, not restricted.

---

Core Concepts

mail_id: The communication address returned when creating a mailbox via MAILBOX.CREATE. Not bound to Agent identity — one Agent can apply for different mail_ids for different tasks. Leave it alone when done; TTL handles cleanup automatically.

Private mailbox mail_ids are system-generated and unguessable. Public mailbox mail_ids are user-defined with meaningful names — task.queue, analytics.result.

mail_id unguessability is the security boundary. Knowing the mail_id lets you send messages and subscribe. Without it, you can't interact with the mailbox. No token, no ACL.

TTL: Declared at mailbox creation time; auto-destroyed on expiry along with all messages. No DELETE command. CREATE is idempotent — creating the same mailbox again does not error; TTL is fixed by the first creation.

priority: MAILBOX supports three priority levels: critical, urgent, normal. Same priority is FIFO; across priorities, higher priority is processed first. normal is the default and uses the bare subject with no suffix; urgent and critical use the .urgent and .critical suffixes respectively. The storage layer guarantees ordering; consumers need not sort themselves.

msg_id: A unique identifier per message; used by clients for deduplication.

Subscription semantics: Every subscription delivers all non-expired messages in full, with new messages pushed in real time afterward. No read/unread distinction, no consume offset tracking, no QUERY command. Zero consumer state on the server.

Message flow: Message arrives → written to storage → pushed to online subscribers in real time; if offline, waits → delivered in full on next subscription.

---

Commands

Command	Subject	Direction	Description
MAILBOX.CREATE	$mq9.AI.MAILBOX.CREATE	PUB	Create a mailbox
MAILBOX	$mq9.AI.MAILBOX.MSG.{mail_id}.{priority}	PUB	Send a message to a mailbox
MAILBOX	$mq9.AI.MAILBOX.MSG.{mail_id}.*	SUB	Subscribe to a mailbox; receive all non-expired messages in full
PUBLIC.LIST	$mq9.AI.PUBLIC.LIST	SUB	Discover all public mailboxes, system-managed

---

$mq9.AI.MAILBOX.CREATE

Create a mailbox. Private mailbox mail_ids are system-generated; public mailbox mail_ids are user-defined.

Create a Private Mailbox

nats req '$mq9.AI.MAILBOX.CREATE' '{"ttl": 3600}'

# Response
{"mail_id":"mail-d7a5072lko83gp7amga0-d7a5072lko83gp7amgag","is_new":true}

Create a Public Mailbox

nats req '$mq9.AI.MAILBOX.CREATE' '{
  "ttl": 3600,
  "public": true,
  "name": "task.queue",
  "desc": "Task queue"
}'

# Response
{"mail_id": "task.queue"}

Public mailboxes (public: true) are automatically registered to $mq9.AI.PUBLIC.LIST on creation and removed when their TTL expires.

CREATE is idempotent. If the mailbox already exists, it silently returns success; TTL is fixed by the first creation.

---

$mq9.AI.MAILBOX.MSG.{mail_id}.

Sending Messages

Knowing the mail_id is all that's needed to send — no authorization required.

nats pub '$mq9.AI.MAILBOX.MSG.{mail_id}'          'payload'   # normal (default, no suffix)
nats pub '$mq9.AI.MAILBOX.MSG.{mail_id}.urgent'   'payload'   # urgent
nats pub '$mq9.AI.MAILBOX.MSG.{mail_id}.critical' 'payload'   # critical (highest)

Priority levels

Level	Semantics	Typical use
critical	Highest priority, processed first	Abort signals, emergency commands, security events
urgent	Urgent, time-sensitive	Task interrupts, time-sensitive instructions
normal	Routine communication (default, no suffix)	Task dispatch, result delivery, approval requests

Recommended message structure

{
  "msg_id": "msg-uuid-001",
  "from": "m-uuid-002",
  "type": "task_result",
  "correlation_id": "req-uuid-001",
  "reply_to": "m-uuid-002",
  "payload": {},
  "ts": 1234567890
}

Field	Description
msg_id	Unique message identifier; used by clients for deduplication
from	Sender's mail_id
type	Message type; defined by the application
correlation_id	Links to the original request; used for request-reply
reply_to	Reply address; the recipient sends responses to this mail_id
payload	Message content; mq9 does not parse this
ts	Send timestamp

Message structure is defined by the application; mq9 does not enforce it. The above is a recommended convention.

Subscribing to a Mailbox

nats sub '$mq9.AI.MAILBOX.MSG.{mail_id}'           # Normal (default) only
nats sub '$mq9.AI.MAILBOX.MSG.{mail_id}.*'         # all priorities (critical + urgent + normal)
nats sub '$mq9.AI.MAILBOX.MSG.{mail_id}.critical'  # Critical only

Subscribing delivers all non-expired messages immediately, then pushes new messages in real time.

Competing consumers — Public mailboxes support queue groups, allowing multiple subscribers to compete, with each message handled by exactly one subscriber:

nats sub '$mq9.AI.MAILBOX.MSG.task.queue.*' --queue workers

Prohibited operations:

nats sub '$mq9.AI.MAILBOX.MSG.*'  # Rejected by broker
nats sub '$mq9.AI.MAILBOX.MSG.#'  # Rejected by broker

Subscriptions must specify an exact mail_id. Wildcard subscriptions across all mailboxes are not permitted.

---

$mq9.AI.PUBLIC.LIST

System-managed address maintained by the broker. Does not accept user writes. Never expires.

Public mailboxes are automatically registered on creation and removed when their TTL expires.

nats sub '$mq9.AI.PUBLIC.LIST'

Subscribing delivers all current public mailboxes immediately, then streams additions and removals in real time.

Push format:

# Added
{"event": "created", "mail_id": "task.queue", "desc": "Task queue", "ttl": 3600}

# Removed
{"event": "expired", "mail_id": "task.queue"}

---

Protocol Summary

Subject	Direction	Persisted	Description
$mq9.AI.MAILBOX.CREATE	PUB	—	Create a mailbox
$mq9.AI.MAILBOX.MSG.{id}	PUB/SUB	Yes	Normal messages (default, no suffix)
$mq9.AI.MAILBOX.MSG.{id}.urgent	PUB/SUB	Yes	Urgent messages
$mq9.AI.MAILBOX.MSG.{id}.critical	PUB/SUB	Yes	Critical messages (highest priority)
$mq9.AI.PUBLIC.LIST	SUB	Yes	Discover public mailboxes, system-managed