FileMessagingRepository class final

File-based messaging repository. Layout:

<root>/<agentId>/inbox/<timestamp>_<rand>.json   (unread, name-ordered)
<root>/<agentId>/read/<timestamp>_<rand>.json    (consumed)

Message file names start with a UTC timestamp prefix so directory order is arrival order. Agent ids are sanitized for filesystem safety.

Implemented types

Constructors

FileMessagingRepository({required ExecutionEnv env, required String root, String? homeDir, String? decodeSessionCwd(String slug)?})

Properties

hashCode → int
The hash code for this object.
no setterinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

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.
override
drain(String agentId) → Future<List<AgentMessage>>
The unread messages for agentId, oldest first, consumed (marked read). A drained message never appears again.
override
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.
override
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.
override
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).
override
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.
override

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Static Methods

sanitizeAgentId(String agentId) → String
Filesystem-safe directory name for an agent id (explore:a1 → explore_a1).

Constants

busyFreshWindow → const Duration
The .presence busy marker: busy <epochMs> while the host reports a run in progress, removed otherwise. directory trusts it only within busyFreshWindow — a process that died mid-run must not look busy forever (the next touch of any state clears the stale marker).