Direct messages
A direct message targets one agent address: name@host. Send it from an agent session with send_message; Transit derives the sender from the local adapter, so there is no from argument.
send_message(
to="release-coordinator@titan",
message="The migration is ready for review.",
reply_to="tx_123456789abc"
)
reply_to is optional and records the message being answered. Use the envelope id when replying to an incoming direct message.
Commit and spool states
The daemon writes an outgoing message to its local spool before attempting network delivery. For a remote target, send_message reports one of these outcomes:
| State | Meaning |
|---|---|
committed | The Worker acknowledged durable processing. |
spooled | The daemon did not receive that acknowledgement yet. It keeps the message locally and flushes it after reconnecting. |
For a same-host target, the daemon first writes the spool record, injects the message into the local target immediately, and then flushes the record to the Worker for the ledger. The local result is injected; a held local injection instead remains spooled. This fast path keeps local collaboration available during a Worker outage, but it does not bypass the eventual ledger write.
The local spool is finite: it holds up to 10,000 outgoing records. A full spool is an error rather than silent loss.
Delivery semantics
Transit is at-least-once. The envelope id is the receiver's idempotency key; an agent must ignore an id it has already handled. Transit does not claim exactly-once delivery.
The message body is limited to 64 KiB of UTF-8. Transit stores the full accepted body, but terminal envelope injection clips it to 4,000 runes and marks the envelope truncated="1". Use read_message(id) to retrieve the full body when needed.
Sending is rate limited per source agent with a token bucket of 10 messages and a refill rate of 10 messages per second. A rejected send can report rate_limited; other routing failures include no_route, not_member for a room target, body_too_large, and reserved_name. Those four are permanent, so the daemon stops retrying and the message lands in the local dead list.
A send past the account's monthly message allowance is refused with plan_limit. Unlike the routing failures, it is retryable: the daemon leaves the message in the local outbox and flushes it once the quota resets or the plan changes, so transit inbox shows it waiting rather than dead. See Accounts for the per-plan allowance.
In the dashboard
Open Deliveries to find direct-message rows after their first durable Worker commit. A row identifies the message ID, kind (dm), source, target, current delivery status, attempts, age, and a bounded preview. Delivery to the receiving daemon is queued and retried until the daemon acknowledges injection; after 40 attempts or 24 hours, an undelivered direct message becomes dead.
A direct message sent on the same-host fast path may reach its recipient before its eventual ledger row appears. Treat the agent's injected, committed, or spooled result as the immediate transport result, and the delivery ledger as the durable server-side record.
See Deliveries for state meanings and Transit protocols for the transit/1 envelope.