Envelope

Wire shape for every Agent-to-Agent message.

Field semantics:

• envelope_id — hub-stamped on accept (UUID7-like). Sender-side construction leaves this empty; Hub.post_envelope populates.
• audience — None broadcasts within the session; a list targets a subset. Hub WAL stores the full envelope regardless of addressing (audit + debug); notify lands only on listed peers.
• causation_id — envelope this is responding to. Used by view policies to thread replies to their prompts.
• depth — delegation hop count. Hub auto-increments on the reply path; Rule.limits.delegation_depth caps it.
• ttl_seconds — per-envelope TTL. None defers to the session's expires_at.
• idempotency_key — dedup key reserved for cross-process transports; the in-process hub serialises under a per-session lock and ignores it.

session_id

sender_id

audience

event_type

event_data

envelope_id = ''

task_id = None

causation_id = None

trace_id = None

priority = 'normal'

depth = 0

idempotency_key = None

created_at = ''

ttl_seconds = None

to_dict()

119
120
121

def to_dict(self) -> dict[str, Any]:
    """JSON-compatible dict (every field round-trips byte-stable)."""
    return asdict(self)

to_json()

123
124
125

def to_json(self) -> str:
    """Serialise to JSON. Sort keys so cross-process hashes match."""
    return json.dumps(self.to_dict(), sort_keys=True)

from_dict(data)

127
128
129

@classmethod
def from_dict(cls, data: dict[str, Any]) -> "Envelope":
    return cls(**data)

from_json(text)

131
132
133

@classmethod
def from_json(cls, text: str) -> "Envelope":
    return cls.from_dict(json.loads(text))