Two ordered queues of messages waiting to enter a run: next_turn and next_step.

This is what makes an agent something you can talk to while it is working. A run claims from the inbox at two boundaries — once when a turn opens, and again at every step boundary — so a message that arrives mid-run joins the next model request instead of being lost, queued behind a minutes-long tool call, or cancelling the work already in flight.

One primitive, three presets

send/4 is the primitive: a message, a target queue, and whether the send should wakeup an idle agent. The three presets are the only combinations anyone has needed:

The fourth combination — :next_turn without a wake — is deliberately not a preset: a turn only opens when something starts it, so a non-waking turn message would sit until an unrelated run happened to begin. send/4 still allows it for anyone who wants exactly that.

inject/2 is the subtle one, and it is the whole reason the primitive takes wakeup separately from target: injected context waits for the next admitted request rather than starting one. Injecting into an idle agent costs nothing and does nothing observable until the agent runs again for some other reason. Steering an idle agent starts it.

Ordering

Each queue is FIFO: messages are claimed in the order they were sent.

The two queues are never merged and never compete. They are drained at different moments in a run, and that ordering — not a priority rule — is what decides who goes first when both hold messages:

turn opens ──▶ claim(:next_turn) ──▶ step boundary ──▶ claim(:next_step) ──▶ model request

So with both queues populated, everything in next_turn lands in the transcript ahead of everything in next_step, because the turn's claim happens before the first step's. Within each queue, send order is preserved. On later steps of the same turn only next_step is claimed — next_turn is already empty, and anything arriving there afterwards waits for a genuinely new turn.

Pure data

No processes, no timers, no pids. The inbox is a value its owner keeps (for agents driven by Nous.AgentServer, that owner is the server's state), and claiming returns the drained inbox rather than mutating anything.

It is also serializable: send/4 normalizes a binary to a Nous.Message, and nothing else ever enters the queues. A pid in here would fail Nous.Session.Event.new/4's serializability validation the moment it reached the log, and would be meaningless after a restart anyway.

Not part of streaming

Nous.AgentRunner.run_stream/3 runs exactly one iteration and is out of scope for turns, steps and the inbox by design. It never claims, so nothing queued here can reach it.

Example

iex> alias Nous.Session.Inbox
iex> inbox = Inbox.new() |> Inbox.inject("recall: the deploy is frozen") |> Inbox.steer("stop and summarize")
iex> Inbox.wake?(inbox)
true
iex> {claimed, inbox} = Inbox.claim(inbox, :next_step)
iex> Enum.map(claimed, & &1.content)
["recall: the deploy is frozen", "stop and summarize"]
iex> Inbox.pending?(inbox)
false