Messaging Contract (v1.0)

Overview

This document defines the Universal Message Contract for the VOX ecosystem, facilitating communication between subordinate agents (specialists) and orchestrated agents (the coordinator and root agent).

Goals:

• Standardize inter-agent communication via an Envelope/Payload message structure.
• Maintain clear trust boundaries without overlapping agent responsibilities.
• Enable future expansion (new agents, responsibilities, data structures) with minimal refactoring.

---

Design Principles

1. Envelope vs. Payload separation — The envelope is stable, minimal, and machine-validated. The payload (details) is variable and event-specific.

2. Identification by UUID — Source and target must be validated against UUIDs defined in each agent's configuration.

3. Immutability — Once emitted, a message cannot be modified.

4. Separation of Concerns — Extra fields (e.g., note_to_human) are never parsed by agents; they are exclusive to the report that the root agent displays to the master.

5. Trust boundaries — Subordinate agents retain full business context. Orchestrated agents receive only what they need to notify and (later) schedule.

6. Message-first logging — Logs reference messages, not jobs or clients. Business details are retrievable from the source system if needed.

---

Standard Message

All messages MUST contain the following top-level fields:

{
  "message_id": "uuid-v4",
  "message_source": "string",
  "emitted_at": "ISO-8601 datetime with timezone",
  "source": "string (UUID)",
  "target": "string (UUID)",
  "type": "string",
  "details": { }
}

Field Definitions

Field	Description
message_id	Globally unique UUID for the message
message_source	Source of truth (e.g., email address)
emitted_at	When the message was emitted by the source
source	UUID of the sender agent
target	UUID of the recipient agent
type	Semantic intent of the message
details	Event-specific payload

---

Agent-Specific Event Types and Payloads

1. job_detected (Specialist → coordinator)

Emitted by a specialist agent when it detects a potential job or lead.

"type": "job_detected",
"details": {
  "start_time": "ISO-8601 datetime with timezone",
  "end_time": "ISO-8601 datetime with timezone",
  "estimated_effort_minutes": "int",
  "price": {
    "currency": "ISO-4217 string",
    "value": "int"
  },
  "note_to_human": "string"
}

Notes:

• note_to_human is explicitly non-machine-readable. The coordinator MUST NOT parse or log it.
• Business identifiers (client, project, job_id) are owned by the source system.
• Both start/end times and estimated effort are included because deadlines ≠ workload and calendar slots ≠ cognitive effort.

2. data_request (root → coordinator)

The root agent requests administrative information (e.g., company financial statements) upon request from the master.

"type": "data_request",
"details": {
  "subject": "financial_summary",
  "parameters": {
    "start_date": "ISO-8601 datetime with timezone",
    "end_date": "ISO-8601 datetime with timezone"
  }
}

3. data_response (coordinator → root)

The coordinator responds to the root agent's data_request with a processed data structure or a path to a generated file.

"type": "data_response",
"details": {
  "request_id": "UUID of the data_request object",
  "total": {
    "currency": "ISO-4217 string",
    "value": "int"
  },
  "attachments": [
    "path/to/file.pdf"
  ]
}

4. system_failure (Any Agent → War Room)

A system failure is the only event where any agent other than the root agent may post directly to the War Room. Used as a last resort when all other communication channels are broken.

"type": "system_failure",
"details": {
  "error_code": "VM_CONNECTION_LOST",
  "severity": "CRITICAL",
  "description": "Associated Virtual Machine is unreachable"
}

5. message_acknowledged (Any Agent → Any Agent)

Confirms that a message was received. Does not imply approval or rejection — only successful receipt and logging.

"type": "message_acknowledged",
"details": {
  "in_response_to": "UUID of the received message"
}

---

Logging Contract

Agents maintain an internal append-only log of message-flow events in logs.db via VOXAgentMemory. All database I/O is fully asynchronous (non-blocking) using aiosqlite. Every write or query must be prefixed with await:

await agent.memory.record(
    event_type="message",
    action="received",
    source=msg["source"],
    target=msg["target"],
    details={"message_id": msg["message_id"], "emitted_at": msg["emitted_at"]},
)
rows = await agent.memory.get_recent(limit=10)

The database schema is created lazily during the agent's async boot cycle (await agent.memory.init_db()), decoupling object construction from connection setup. Logs are never modified or deleted after creation.

Each entry follows this schema:

---

Example Flow

A specialist detects a potential job in the inbox and sends a message to the coordinator:

{
  "message_id": "fa703dc8-0003-46f0-b4be-8dd0a5f398ac",
  "message_source": "email address",
  "emitted_at": "2026-01-11T08:00:00-03:00",
  "source": "<specialist_uuid>",
  "target": "<coordinator_uuid>",
  "type": "job_detected",
  "details": {
    "start_time": "2026-01-11T08:15:00-03:00",
    "end_time": "2026-01-11T16:00:00-03:00",
    "estimated_effort_minutes": 60,
    "price": { "currency": "USD", "value": 30 },
    "note_to_human": "Client: Netwire\nProject O-26-XXXXX-TRA-YYY"
  }
}

The coordinator confirms receipt:

{
  "message_id": "a0f9e6f3-f611-4c55-940d-4cf72c624ad5",
  "emitted_at": "2026-01-11T08:00:01-03:00",
  "source": "<coordinator_uuid>",
  "target": "<specialist_uuid>",
  "type": "message_acknowledged",
  "details": {
    "in_response_to": "fa703dc8-0003-46f0-b4be-8dd0a5f398ac"
  }
}

At this point:

• The coordinator checks the allotted work time and, if the job fits the timeframe, notifies the root agent.
• The root agent sends a notification to the master, who decides manually.

---

Versioning and Evolution

• This document defines v1 of the contract.
• New message types may be added without breaking existing ones.
• Envelope fields are considered stable.

Future versions may introduce:

• Decisions (approve / reject)
• Scheduling instructions
• Accounting events
• Authentication and signatures

---

Phase 1 Constraints

• The coordinator does not make decisions.
• The coordinator does not mutate jobs.
• The coordinator does not contact clients.
• The human remains the sole authority.

---

Status: Stable — Approved for implementation.