Module mailbox 

Cross-session mailbox: one Maildir per session address.

Every message a session receives from outside its own user — a peer session, a channel, or a notice — is one Envelope filed in the receiving session’s mailbox. The envelope carries a live return address (from) and says how an answer travels back (ReplyVia), because an agent that cannot tell whether its final message already reaches the sender either stays silent when it should answer or posts twice.

Three rules earn their place here:

1. The store is a Maildir. harness serve runs once per client, so several processes read and write one mailbox. A message is written to tmp/, then renamed into new/. A reader claims it exclusively by renaming it into claimed/ under its own pid, hands it on, and only then acknowledges it into cur/. Two readers never both take one message, and a claim left by a reader that died is returned to new/ on the next read, so a crash repeats a message rather than losing it.
2. Ids deduplicate. Delivering an envelope whose id is already filed is a no-op that reports the existing file, so a sender retrying after an ambiguous outcome cannot create a second copy.
3. The rendering is the contract with the agent. The text an agent reads says who sent it, that it is not the user, and — for each ReplyVia — exactly whether and how to answer. Body text is escaped so a body can never close the envelope or forge its attributes.

Structs

Envelope

One message filed in a mailbox.

IdleSubscription

One sender’s wish to hear when a receiver next finishes a turn.

MailAddress

Where one session can be reached: sc:<machine>:<harness>:<session-id>.

MailAddressError

Address parse failure.

Mailbox

One session’s Maildir.

StoredEnvelope

One envelope read back from a mailbox.

Enums

MailKind

What kind of source a message came from. It decides the trust wording the receiving agent reads.

MailState

Where a filed envelope currently sits.

ReplyVia

How an answer to this message travels back.

Constants

ADDRESS_PREFIX

Scheme prefix of a supercode session address.

SEND_COMMAND

Command an agent runs to send or reply. Rendered into every envelope that asks for an explicit reply.

Functions

deliver_to

File envelope in the mailbox of to, on this machine or, through Teams, on the machine to names.

escape_body

Escape message text so it can neither close the envelope nor open a forged one. & goes first so existing entities are preserved literally.

local_machine_name

The name this machine is addressed by: the name it is enrolled under in the current Teams context, else its short host name — in the normal form the Teams mail door also matches (lowercased, anything outside [a-z0-9-_] replaced by -). An address must carry the name Teams routes by, or a reply to it cannot find its way back.

mail_root

Root directory holding every mailbox on this machine.

mailboxes_with_user_turns

Every mailbox holding a user’s turn that has not reached its session yet.

new_message_id

A fresh message id: m- and 24 random hex digits.

normal_machine_name

A machine name in the form addresses use.

subscribed_mailboxes

Every mailbox under root with at least one idle subscription.

teams_mail

Ask another machine’s mail door (through Teams) to take request: the supercode teams mail --machine <machine> verb, with the request on its stdin and one JSON answer on its stdout.