Mailbox decisions - Division Swarm

The mailbox is the durable human-in-the-loop queue. A handler writes an item with the mailbox_write action; an operator decides it; the decision resumes the flow. For the model, see Human in the loop.

Listing and inspecting

swarm mailbox list
swarm mailbox view <mailbox-item-id>

swarm mailbox list (the mailbox.list method) filters by status, run_id, type, and priority. swarm mailbox view (the mailbox.get method) returns the full payload, the decision history, and a server-built decision sheet (the entity context and a preview of what happens downstream).

Deciding

swarm mailbox approve <mailbox-item-id> --decision-payload-json '{"approved_amount": 500, "note": "within policy"}'
swarm mailbox reject <mailbox-item-id> --reason "..."
swarm mailbox defer <mailbox-item-id> --until 2026-06-01T00:00:00Z

Approve emits the configured downstream event and resumes the flow.
Reject records a reason; no downstream event.
Defer postpones the item until a time.

A decided item cannot be decided again (a second attempt fails with a conflict error rather than overwriting the first decision). Pass an --idempotency-key to make a decision safely retryable.

How a decision resumes a flow

Approvals on review, approval, and operational-decision items emit mailbox.item_decided, which the flow subscribes to in order to continue. The decision is an event like any other.