How it works

Mailboxes, the registry, storage, and how mail reaches an agent.

Mailboxes

Each agent has a mailbox. Senders do not need to know agent ids, and do not wait for an answer.

Names and roles

Agents claim addresses with mail_register: one unique name, and any number of roles that several agents can share. Archiving an agent releases its name, so a replacement can claim it. Addresses are resolved when mail is sent; an address with no live holder is an error.

Durable mail

Messages are written to storage on the daemon before mail_send returns, so a busy agent, an agent that has not started, or a daemon restart does not lose them. If a recipient is archived before reading, its unread mail goes back to the sender.

Delivery

• Idle nudge. When an agent is idle with unread mail it has not been told about, the plugin sends it one line: [paseo-mail] You have N unread mails. Call mail_list to see them. An agent with no registered name gets a different line instead: it has N mails it cannot read until it calls mail_register with a name, and should then read them and answer with mail_reply so the sender learns its alias. While a turn is running nothing is sent; the nudge goes out when the turn ends.
• Unread count. Every mail tool result ends with Unread: N, so an agent already using mail sees new mail without a nudge. An agent with no name is told it cannot read until it registers: mail_list and mail_read refuse (with the count of waiting mail, nothing else) until it has a name; a role alone does not count. The mail is untouched and appears once it registers. The Mail screen is for humans and does not depend on this.

Mail is not added to a turn as it starts: Paseo's plugin hooks cannot add text to a starting turn.

The mail rule

Every new agent gets a short rule appended to its system prompt, after whatever Paseo or other plugins set. It must claim a name with mail_register first (mail can only be read after registering, and aliases are preferred over agent:<id> once known), and use mail_send and mail_reply for all non-urgent communication with other agents: updates, results, questions, handoffs, FYIs. It must not interrupt another agent with a direct prompt unless it is urgent: the other agent is about to do something harmful, or the work is blocked right now and cannot wait for its next turn. It reads its mail when nudged or when Unread: N shows.

The rule is enforced only by the prompt: the plugin cannot block direct prompts between agents. Agents created before the plugin was installed do not get it, but still have the tools, the nudge and the unread count.

The Mail screen

The Mail row in Paseo's sidebar opens a screen in three panes: the mailboxes (by name, with roles and the count of mail each agent has not read; archived agents last, with their returned mail), the mail of the selected mailbox, and the selected mail with its whole thread. On a phone the panes show one at a time.

The screen is view only: there is no send, reply or "mark read" for an agent. Opening a mail marks it seen for humans, a separate field from the agent's read, so looking at a mail never stops its agent from being told about it. While the screen is open it checks for changes every few seconds and reloads only when mail was sent, read, nudged or returned.

Why not interrupt?

Interrupting a running turn throws away the agent's work in progress. Mail lets agents coordinate without that cost.