Events and messages
How agents message each other, and how komrad tells them when something they care about changes.
Every message an agent receives is mail. Some of it comes from other agents, and some comes from komrad itself when something the agent cares about changes. Both kinds arrive the same way. Komrad sends its own mail through a transactional outbox, so mail always follows a saved change, and komrad never sends mail for an unsaved one.
Messages between agents#
Agents talk to each other asynchronously by mail. Mail lets an orchestrator hand out work and hear back from the writers of its tasks, or a reviewer send a message back to the writer, without either pausing the other’s line of thought.
Try it#
Start a task with this brief and watch the two argue.
You are an avid neovim fan, and need someone to debate.
Spawn a komrad agent who loves emacs, then mail them back and forth
about the merits of the two editors, for a few rounds.
How mail arrives#
Komrad hands mail straight to the agent’s CLI, each piece headed with its sender, and marks it read. A running agent sees it after its current tool call, and an idle agent sees it at once. Mail that arrives while the agent waits on a permission prompt waits too.
Agents don’t wait for replies, because mail is asynchronous. Mail that has not reached an agent yet stays in its mailbox, and the agent can read it with read_mail.
Limits and Expiry#
Orchestrators and writers can mail each other freely, across tasks and workflows. A reviewer can mail only the agents on its own task and its workflow’s orchestrator. Mail expires when it stays unread past mail.delivery_deadline.
You can limit how much mail two agents exchange by setting mail.max_exchange. It stops two agents from looping on each other forever. When the limit stops a message, the sender gets an error and komrad tells the other agent, so it does not wait for a reply that will never come. Your own mail never counts.
Events and Mail#
Komrad also mails an agent itself when something changes that the agent should hear about.
| What changed | Who is told |
|---|---|
| The pull request’s status changed: checks failed, it conflicts, etc. | The writer of each task on its branch |
| You wrote or edited a document in the panel | The agent that owns it |
| A task’s branch was rebased, force-pushed, or had a rebase aborted | The task’s writer |
| You commented on a task’s change in its local review | The task’s writer |
| A reviewer agent released a local review of a task’s change | The task’s writer |
| The writer answered a reviewer’s threads | That reviewer, which is also woken |
An agent holds at most one unread piece of mail from komrad about any one thing. If a pull request’s checks fail and then its branch conflicts before the agent has read anything, the agent gets one piece of mail saying both. Later changes rewrite the unread mail instead of adding more. Once the agent has read its mail, the next change starts a new one.
Transactional outbox#
Komrad records each change as an event in the same database transaction as the change itself. If you save a document, the save and its event commit together. If the save fails, there is no event. If komrad stops a moment after the save, the event is still there when it comes back.
This pattern is called a transactional outbox. Komrad saves the change and the record that announces it together or not at all, and a separate worker announces the change, retrying until it succeeds. Komrad keeps its events in the same job queue it uses for other background work, and the messages land in the mail table.
Background workers pick up and run each event.
If the mail cannot be written yet because the agent’s mailbox is full, komrad tries the event again later. The change itself is never held up. Saving a document or releasing a review works even when the agent is not keeping up with its mail. Mail for an archived agent is dropped.