@kairos/hive-protocol

Universal message envelope for the KAIROS agent ecosystem — typed, traceable, domain-tagged envelopes for multi-agent communication.

Features

• Typed envelopes — event | command | query | response | heartbeat
• Domain layers — infrastructure | agent | communication | business | world
• Trace chains — link related messages across distributed workflows
• Priority + TTL — priority 0–9, optional expiry in seconds
• Zero runtime dependencies — pure TypeScript, ships ESM + CJS + .d.ts

Install

npm install @kairos/hive-protocol

Usage

import { createEnvelope, validateEnvelope, filterByDomain } from '@kairos/hive-protocol';

// Create a typed envelope
const envelope = createEnvelope({
  from: 'falcon',
  to: 'kairos',
  type: 'event',
  domain: 'agent',
  payload: { status: 'healthy', uptime: 99.9 },
});

// Validate an incoming message
const result = validateEnvelope(rawMessage);
if (result.ok) {
  console.log(result.envelope);
}

// Filter a stream by domain
const agentMessages = filterByDomain(envelopes, 'agent');

Envelope Schema

interface Envelope {
  id: string;        // UUID v7 (time-sortable)
  ts: string;        // ISO 8601 timestamp
  from: string;      // Source: "falcon", "ollama", "hive-governor"
  to: string;        // Target: "kairos", "*" (broadcast), "cell:intelligence"
  type: EnvelopeType;
  domain: EnvelopeDomain;
  pri: number;       // Priority 0 (background) to 9 (critical)
  ttl: number;       // Seconds until expiry. 0 = no expiry
  trace: string;     // Links related messages across a workflow
  payload: unknown;
}

API

createEnvelope(partial)

Creates a valid envelope with auto-generated id, ts, and trace if not provided.

validateEnvelope(raw)

Returns { ok: true, envelope } or { ok: false, errors: string[] }.

filterByDomain(envelopes, domain)

Filters an envelope array to a specific domain layer.

groupByTrace(envelopes)

Groups envelopes by their trace field — useful for reconstructing workflows.

getTraceChain(envelopes, traceId)

Returns all envelopes belonging to a trace, sorted by timestamp.

Domain Layers

| Domain | Use | |--------|-----| | infrastructure | Services, healthchecks, resource metrics | | agent | Agent status, task events | | communication | Telegram, Discord, voice | | business | Revenue, spend, pipeline events | | world | External integrations, APIs |

License

Apache-2.0 — see LICENSE