Struct Relay 

pub struct Relay {
    pub base_dir: PathBuf,
}

The main relay hub. All operations are local filesystem — no network.

Create one per repo/project with a shared base_dir path. Every agent that uses the same path will see each other’s messages.

Fields

base_dir: PathBuf

Implementations

impl Relay

pub fn new(base_dir: PathBuf) -> Self

Create a new relay rooted at the given directory.

Typical usage: Relay::new(".relay".into()) at the repo root. All agents must use the same path to see each other.

pub fn register( &self, agent_id: &str, session_id: &str, pid: u32, ) -> AgentRegistration

Register an agent so others can discover it.

pub fn register_with_metadata( &self, agent_id: &str, session_id: &str, pid: u32, metadata: Value, ) -> AgentRegistration

Register with custom metadata (model name, capabilities, etc).

pub fn heartbeat(&self, session_id: &str)

Update heartbeat to signal this agent is still alive.

pub fn unregister(&self, session_id: &str)

Unregister an agent (cleanup on exit).

pub fn agents(&self) -> Vec<AgentRegistration>

List all registered agents.

pub fn cleanup_dead(&self) -> usize

Remove registrations for agents whose PID is no longer alive.

pub fn send( &self, from_session: &str, from_agent: &str, to_session: Option<&str>, content: &str, ) -> Message

Send a message. to_session: None = broadcast to all agents.

pub fn inbox(&self, session_id: &str, limit: usize) -> Vec<(Message, bool)>

Read inbox: returns messages with a flag indicating if newly read. Marks all returned messages as read by this session.

pub fn unread(&self, session_id: &str) -> Vec<Message>

Get unread messages without marking them as read.

pub fn unread_count(&self, session_id: &str) -> u64

Count unread messages for a session.

pub fn cleanup_old(&self, max_age_secs: u64) -> usize

Delete messages older than max_age_secs.

pub fn poll(&self, session_id: &str) -> u64

Poll for new messages. Returns unread count. Useful for integration: call this in a loop and trigger actions (like spawning a background AI session) when count > 0.