komrad

read_mail

Read the caller's waiting mail, oldest first.

writesnot idempotentMCP toolAgent

Reading claims the mail, so a second call returns nothing. Passing another agent's id claims that agent's mail.

Calling it#

curl -X POST http://127.0.0.1:8787/komrad.agent.v1.AgentService/ReadMail \
  -H 'Content-Type: application/json' \
  -d '{}'

Request#

ReadMailRequest#

FieldTypeDescription
iduuid

The agent whose unread mail to read, by id. Unset reads the caller's own.

Response#

ReadMailResponse#

FieldTypeDescription
mailMail[]

All the unread mail, oldest first, now marked read.

Types#

Mail#

Mail is one message in an agent's mailbox.

FieldTypeDescription
iduuid*

The mail's id. Pass it as reply_to to answer.

from_agent_iduuid

The id of the agent that sent the mail. Unset when komrad sent it.

from_namestring

The sender's name. Mail komrad sent carries komrad's name.

to_agent_iduuid*

The id of the agent the mail is for.

bodystring

The mail's text.

reply_touuid

The id of the mail this one answers. Unset when the mail starts a thread.

created_attimestamp

When the mail was sent.

claimed_attimestamp

When the recipient read the mail. Unset while it is unread.

expires_attimestamp

When the mail expires, read or not.

kindMailKind

Who wrote the mail and why.

MailKind#

MailKind is who wrote a piece of mail and why.

ValueDescription
plain

Mail from an agent or the person.

review_activity

From komrad: a review changed. The mail names the review.

exchange_capped

From komrad: the agent and one other agent have used up their mail limit with each other.

document_edited

From komrad: the person wrote or edited one of the agent's documents.

pull_request_changed

From komrad: a pull request on the agent's branch changed on the forge.

worktree_rebased

From komrad: komrad rebased the agent's worktree, or tried to.

worktree_pushed

From komrad: the agent's branch was force-pushed to origin.

worktree_aborted

From komrad: the sequence stopped in the agent's worktree was aborted.

review_comment

From komrad: the person commented on the agent's work. The mail carries the comment.

agent_failed_to_start

From komrad: an agent this agent created exited as its CLI launched. The mail names the agent.

agent_turn_failed

From komrad: a turn of an agent this agent created ended on an error. The mail names the agent.

guide_requested

From komrad: the person asked the agent for a guide to its diff. The mail names the snapshot to explain.

dormant_mid_turn

From komrad: komrad closed the agent's pane mid-turn to stay inside its memory limit, stopping every process the agent started.

task_quiet

From komrad: every agent on a task whose writer the agent created went quiet with the task neither parked nor waiting on komrad.

worktree_shrunk

From komrad: komrad deleted build output from the agent's worktree while its task was archived.