Module comms 

Fixed-vocab agent-to-agent communication (comms) surface (issue #274). Fixed-vocab agent-to-agent communication (Phase 1 of epic #266).

This module introduces discrete, fixed-vocabulary comms as a non-breaking, reusable capability layered on top of the existing crate::multi_agent::environment::MultiAgentEnvironment surface. It follows the design note docs/COMMS_DESIGN.md, section 5 (the authoritative phase breakdown).

The action-space-extension model

A message is just extra action dims on the sender and extra observation dims on the receiver — exactly the pattern the Bucket Brigade env proves end-to-end with its 1-bit signal channel (src/env/games/bucket_brigade/env.rs, read-only reference here). Concretely, an agent’s action vector is laid out as

[ ...task action dims (agent_action_space)... , ...message dims (message_vocab)... ]

The env slices the message dims off inside step_multi (split_action), applies Delivery, and writes the received tokens into the observation layout it already controls (place_message). No change to crate::multi_agent::environment::MultiAgentResult is required for Phase 1; a first-class messages field is deliberately deferred to Phase 3.

Non-breaking by construction

CommunicatingEnvironment is a supertrait of MultiAgentEnvironment whose methods are all defaulted to describe a zero-width channel (message_vocab -> [], message_obs_size -> 0, delivery -> Broadcast). Existing implementors (snake, matching pennies, bucket brigade, the joint env) satisfy it for free without any code change.

Host-payload discipline

Like crate::multi_agent::messages, everything here is plain Vec<f32> / Vec<i64> host data — no tensor types cross this surface, so producer and consumer stay free to pick different Burn backends.

Structs

AgentMessage

A message emitted by one agent for delivery to others within a rollout.

Enums

Delivery

Delivery routing for messages emitted in a single step.

Traits

CommunicatingEnvironment

Opt-in extension of MultiAgentEnvironment for environments that expose a first-class agent-to-agent message channel.

Functions

place_message

Write received message tokens into an observation slice starting at offset, one f32 per token.

split_action

Split a flat action vector into its (task, message) halves at task_len.