ctx.mail

Service type: MailInterface (from apollia.context.mail).

MailInterface

Bases: Protocol

Durable, at-least-once inter-agent messaging surface.

Reachable from the desktop application only. Both command-line runners build the agent context with no mailbox handle (apollia-os start in task mode, and the chat runner), so every call there raises RuntimeError("mailbox not available in this runtime context"). The context must also carry the mailbox capability, or the call is refused before the handle is even looked up.

send

async def send(self, to: str, payload: dict[str, Any]) -> str

Post a message to to's inbox, returning its message id.

receive

async def receive(self, timeout_secs: float | None=None) -> MailMessage | None

Lease the next message, waiting up to timeout_secs seconds.

poll

async def poll(self) -> MailMessage | None

Non-blocking receive: the next leased message or None.

pending

async def pending(self) -> int

Number of non-expired messages in the caller's inbox.

list

async def list(self, limit: int=50) -> list[MailMessage]

List up to limit messages (most recent first) without consuming.

ack

async def ack(self, message_id: str) -> None

Acknowledge a leased message, deleting it from the store.

nack

async def nack(self, message_id: str) -> None

Refuse a leased message, making it deliverable again.

MailMessage

Bases: TypedDict

A message pulled from an agent's durable inbox.

Field	Type	Default
message_id	str
from_agent	str
payload	dict[str, Any]
sent_at	str