MessagingRepository class abstract interface

Methods

directory() → Future<List<MailboxEntry>>

The known mailboxes in the fabric, with optional cwd metadata. The FULL set (live and stale alike) — live/dead filtering is a display policy above this layer, not a repository concern.

drain(String agentId) → Future<List<AgentMessage>>

The unread messages for agentId, oldest first, consumed (marked read). A drained message never appears again.

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

peek(String agentId) → Future<List<AgentMessage>>

The unread messages for agentId, oldest first, without consuming them.

register(String agentId, {String? sessionName, List<AgentCapability> capabilities = const []}) → Future<void>

Announces agentId's mailbox in the directory (presence): an agent with no mail yet is still discoverable. sessionName, when non-empty, publishes the session's display name so peers can address this mailbox by name (goal_builder instead of sess1/main). capabilities publishes the host's discovery metadata (fabric.enable(name, capabilities) — see AgentCapability); an empty list clears any previously announced set. Called by hosts on session start/switch.

send(AgentMessage message) → Future<void>

Delivers message to the recipient's inbox. Implementations must assign/keep a unique AgentMessage.id and never lose a message silently (a failed delivery throws).

toString() → String

A string representation of this object.

inherited

touch(String agentId, {bool busy = false}) → Future<void>

Refreshes agentId's liveness marker (a heartbeat): hosts call this periodically while the agent runs so directory consumers can tell live mailboxes from abandoned ones WITHOUT any pending mail. busy reports an agent run in progress (mail still accepted — steering semantics); a fresh busy beats the liveness heuristics in directory views. Best-effort by contract — a failing backend never breaks the caller's loop.