Struct MailboxStore 

pub struct MailboxStore { /* private fields */ }

Implementations

impl MailboxStore

pub fn default_root() -> Result<PathBuf>

pub fn open(root: impl Into<PathBuf>) -> Result<Self>

pub fn from_config(cfg: &MessagesConfig) -> Result<Self>

Open from the messaging config — the single place that resolves the directory override and the limits, so the CLI (mecha msg) and the agents it talks to can never drift on which store or which caps.

pub fn with_keep(self, keep_resolved: usize) -> Self

pub fn with_limits(self, pending_cap: usize, max_body_bytes: usize) -> Self

pub fn root(&self) -> &Path

pub fn send( &self, to: &str, from: &str, from_session: Option<String>, body: &str, reply_to: Option<String>, taint: Taint, ) -> Result<SendOutcome>

Leave a message for to.

The lock makes the duplicate and cap checks atomic against concurrent senders; see the module doc for why this store locks on send where the outbox does not.

pub fn messages_for(&self, recipient: &str) -> Result<Vec<MailboxMessage>>

Every message for recipient, oldest first, quarantining what cannot be read. Missing directory means an empty mailbox, not an error.

pub fn pending_for(&self, recipient: &str) -> Result<Vec<MailboxMessage>>

Pending messages for recipient, oldest first.

pub fn claim_pending( &self, recipient: &str, session_id: &str, ) -> Result<Vec<MailboxMessage>>

Claim everything pending for recipient: mark it delivered to session_id and return it, under the recipient’s lock so two live runs of one producer cannot both fold the same message.

Marked before the caller folds, and that ordering is a decision (see docs/MESSAGING-RESEARCH.md §6): the fold is a synchronous in-memory push in the same thread, so the window where a crash loses the fold is microseconds wide — and even then the full body sits here in the store, delivered_to naming the run that died. Nothing is ever only in a transcript.

A write failure partway through returns the messages already marked delivered rather than an error, and stops there. Those are on disk as delivered, so the caller must fold them or they are lost; the ones after the failure stay pending and are re-claimed next poll. Returning an error (and an empty batch from the route) would strand the already-marked ones — delivered in the store, folded into nothing.

pub fn dismiss(&self, id: &str) -> Result<MailboxMessage>

Set a pending message aside unread. This is the human’s verb — a full mailbox refuses new sends, so there has to be a way to clear a backlog no run is coming to claim that is not deleting files by hand. The file stays as its own record, like a rejected outbox item.

pub fn message(&self, id: &str) -> Result<MailboxMessage>

Find one message by id or unique prefix, across all recipients.

pub fn recipients(&self) -> Result<Vec<String>>

Every recipient that has a mailbox directory.

pub fn announce(&self, producer: &str, session_id: &str) -> Result<()>

Announce a live session, so mecha msg agents can answer “who is running”. One marker per session, grouped by producer — several live sessions of one producer is the normal worktree workflow, and a single per-producer file would make them fight over it. Advisory, like the trigger marker it generalises: the mailbox works without it.

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

Remove a session’s marker. Best-effort: a marker whose pid is dead reads as absent anyway, so a hard kill costs nothing but tidiness.

pub fn agents(&self) -> Result<Vec<AgentMarker>>

Live sessions, liveness-checked; stale markers are cleaned as found.