Inbox #
A session's inbox is its queue. Everything the session will read waits there in order, and nowhere else:
- a person's messages with their attachments, editor prompts, and continuations
- letters between agents, webhook deliveries, and Discord events
- scheduled prompts, notes from extensions and the daemon, and the kernel's notices about its namespace
- job and cell completion notices, shell command receipts, and the notice a turn resumed after a restart reads first
mail.gleam owns the storage, the mail
table. inbox.gleam turns rows into
submissions and queue items. The session keeps no queue of its own. It holds
only the rows its running turn took, until the commit that writes them marks
them delivered.
Some inputs are written by the turn itself rather than read from the inbox: the model's own output, tool results, and hook context after a call. So are notes written in the same commit as a change the session applies to itself: a model switch, changed capabilities or context with the pinned prompt, a rewind's summary, image fitting, and the salvage of a cut-off reply.
Posting an input #
sdk/input is the one way an extension
or a daemon module gives a session something to read. An Input says who it is
for and from, what it is, its text and the line people see for it, when it is
read, and an optional key. An extension posts it through the input.Inbox its
context carries, as in daemon.inbox.post(daemon.storage, input). The record's
post stores it. Its post_in stores it in the caller's transaction, so it
commits with the producer's own records or not at all: a webhook delivery, a
Discord message's channel cursor, a schedule's advance. input.note builds a
note.
| From | Who |
|---|---|
Person |
the person the session works for |
Agent(session, name) |
another agent session |
Outside(name) |
someone outside the daemon: a webhook's sender, a Discord user |
Daemon(origin) |
the daemon or an extension; origin labels it |
| Key | Meaning |
|---|---|
Unkeyed |
every post stores a row |
Once(k) |
the row's id is k; posting k again stores nothing, even after it was read |
Filed(k, g) |
as Once(k), and the row is filed under g, the producer's grouping |
Latest(k) |
a newer post under k replaces the row still waiting under it |
The record's withdraw takes the row posted under a key out of the queue while
it still waits. Withdrawing one already read changes nothing. Its waiting says
which keys still wait. Both reach one session's letters, so they keep the
session rule of the history reads: a handle withdraws from or reads the queue of
the session it is bound to, and another session's only when its extension
declares Correspondence. A post reaches any session under Inbox. A post
refused for a full inbox answers Full, which a producer reports in its own
terms. Producers never name rows, positions, or sessions' actors.
The SDK does not import the inbox's daemon module. An input.Inbox and a
mail.Letters are records of the daemon's own functions, which
mail.inbox and mail.letters build. The
host passes them to extensions as a capability in each context that may post or
read letters:
extension.Setup.inboxreaches initialisers. The webhooks, Discord, and mail extensions create the inbox tables first because their own tables refer to them. Webhooks also moves deliveries stored before the inbox into it.extension.Startup.inboxreaches startup callbacks, such as the Discord manager that posts gateway messages.extension.Daemon.inboxreaches services.extension.Preparationcarriesletters, not an inbox, for owned managed contributions.host.Contextcarriesinboxandlettersfor kernel host routes.
Each operation runs the daemon's code on the caller's connection, so commit and
after-commit order are the same as a direct call. Daemon modules call
mail.post_input, mail.post_input_in, and mail.withdraw directly. Do not
keep an inbox in process-wide state, and do not build another one in an
extension.
A producer that shows where its posts stand reads them through
sdk/mail, not through SQL on mail:
statuses_in reads letters by ID, which is a Once key, queued_in reads the
letters still waiting for some sessions, and undelivered_in and delivered_in
page the letters filed under one grouping by whether they were delivered. A
filed letter keeps its grouping as its key, the column a Latest key uses, so
filing adds no column a transfer would carry; partial indexes on the key hold
the delivered and the undelivered ones apart. Choose a grouping no Latest key
of the recipient can equal, such as a prefixed id. file_in files letters a
producer posted before it filed them, and leaves a letter that has a key alone.
All run on the caller's connection and need the Inbox capability. They keep
the session rule of the history reads: a handle reaches the letters to the
session it is bound to, and another session's only when its extension declares
Correspondence
(extension capabilities). Webhooks reads
its deliveries' letters this way
(extension storage).
Letters between agents go through host.Context.send_mail, which
kernels.gleam binds to the
calling session and forwarding.send.
It resolves the address, forwards to another daemon when needed, and posts the
letter. The mail.Letters in a context
reads which requests a session owes and has open, under the same session rule.
The session itself stores two inputs: a person's input, in the transaction that
records its operation receipt (inbox.insert, see operations),
and the restart notice, at the front of the queue (inbox.post_first).
Rows #
A row waits while its delivered_at and dropped_at are null. Its position
orders the waiting rows of one recipient. A new row goes last; the restart
notice goes first. deliver says when the session reads it, and key names a
Latest row. A person's input carries its whole submission in payload,
attachments included, and the line people see in display; the payload is
released when the row is delivered or dropped. Its id is its operation
receipt's.
sdk/letter names the kinds and the
deliveries. The kind says what a row is; the delivery says when it is read:
| Delivery | Meaning | Default for |
|---|---|---|
steer |
joins a running turn at its next step | chat, continue, agent letters, event |
wait |
waits for the running turn to end | webhook, job |
alone |
takes a turn of its own | acp |
next_turn |
joins a running turn at its next step; never starts one | note |
attach |
joins a running turn at its next step; written now at rest | shell |
A producer may choose another delivery: a Discord channel set to wait for the
turn posts event rows that wait. A resting session starts a turn for
steer, wait, and alone rows. A scheduled prompt is a chat row from
schedule, so it steers like a typed message. A heartbeat skips a busy session.
The registry's dispatcher delivers scheduled prompts on its tick. It asks the
due callback of every declared extension's SchedulePlugin, quarantined ones
included, for occurrences due now. Core reads them with runtime.schedules. The
schedule extension
answers from its own table. For each occurrence the dispatcher checks the
session's move state and calls the occurrence's advance in the same
transaction that posts the prompt. A failed due read is logged and the next
tick reads again. See
dispatch_schedules and the
plugin contract.
Reading the queue #
The session reads its inbox whenever it decides something: when a row arrives,
when a turn ends, at each step of a running turn, and when it loads. It first
reads an index of the waiting rows it has not taken: id, kind, delivery, and
stored bytes (mail.index). The rules in turn.gleam pick from that index, and
only the picked rows are read whole (inbox.take).
turn.opening: the rows a new turn starts with. Analonerow goes by itself, and the rows ahead of one go without it. Rows that only ride along go ahead of the rows that start the turn, so what started it is the last input the model reads; each group keeps its queue order.turn.steering: the rows that join the running turn at its next step. None join a turn read alone.turn.attached: the rows a resting session writes into its transcript at once, without a turn: shell receipts, and the notes a moved session is left about what still reached it.turn.left_behind: what a session that moved away writes into its transcript for whoever reads it there: every row that never starts a turn. The dispatcher settles the rows that would: a letter is refused or forwarded, and anything else is dropped with the reason.
Each batch takes at most 64 rows and 32 MiB of stored bytes; the first row is always taken. A new turn whose bounds stop short of any row that starts a turn takes the first such row too. The rest wait in the inbox for the next step or turn, so a session's memory does not grow with its queue.
A closed agent leaves the letters it was sent, from agents and from outside, and the notices of its finished jobs and cells in its inbox, and reads none of them: a job that finishes after the close does not wake it to keep working. It still reads a person's input and the daemon's notes.
Telling the session #
- A producer posts the row, in its own transaction when it has records to commit with it.
- Once that transaction commits, the session is told
(
store.after_commit,mail.put). A running session registeredmail.registerwhen it started; it rereads its inbox, publishes the queue change, and starts a turn when it rests and a waiting row starts one. A running turn reads the row at its next step or when it ends. - A session that is not running wakes the registry's dispatcher
(
mail.waiting). The dispatcher also runs on its tick. It loads each session holding a waiting row that starts a turn (mail.recipients), and settles the rows of a session that moved to another daemon. A row that does not start a turn never makes it load a session. - A session reads its inbox when it loads, and starts a turn when a waiting row starts one.
- The commit that writes a row into the transcript marks it delivered
(
mail.receive).
Children that fail together land in one turn: a resting parent holds for 400 ms after a child's failure letter arrives, so its siblings' join it.
Store before telling, and tell only after the commit. Do not hand a session a submission directly: an input that skips the inbox is lost on restart and invisible to the queue.
Notices #
A finished job or background cell whose result nobody read is posted as a job
row that waits for the running turn to end. The kernel's
albedo_notices chooses each notice's key
and sends {key, display, text} to jobs.completed or cells.completed
(sdk/notice), posted Once under
that key. It watches the notice until everything it names was read, awaited, or
stopped here, then withdraws it by key (jobs.withdraw, cells.withdraw). A
cell awaits albedo_notices.settle before it reports its result, so a notice
the cell made old news is withdrawn before the turn can end. The kernel never
learns row ids and never polls.
A kernel started before notice keys outlives a daemon upgrade and keeps the
older protocol until it is replaced: it sends no key, keeps the key the route
answers, withdraws by ids, and asks jobs.waiting or cells.waiting which
still wait. The routes accept all of it, so a job or cell that finishes across
an upgrade still reports. A kernel that is upgraded to the new bundle loses the
old one's watchers, so a notice it posted may still start a turn after its
result was read.
The kernel's own notice (variables restored or lost, a restart) is a note from
kernel posted under Latest("kernel-notice")
(session_namespace.set_notice), so a newer notice replaces one no turn has
read yet.
A finished shell command's receipt is the person's own input, posted Once
under the command's id (shell_commands.receipt), and again for any receipt a
session finds unattached when it loads.
shell_commands.gleam keeps the
command's output and its attachment and delivery state.
Ending a turn without a reply #
A letter, a notice or an event often needs no answer. no_reply(reason=""), a
core kernel name in albedo_cells.py, ends
such a turn without a reply once its step's tool calls finish. It calls
cells.no_reply (kernel/cells),
which raises the running turn's quiet slot (turn.quiet, through
command.QuietTurn). When the step's tool calls finish, the turn ends without
another model request unless steering inputs or a Stopping hook hold it open
(and any subsequent empty step also ends cleanly). The optional reason stays
in the cell and is sent nowhere. Without a running turn the call fails with "no
turn is running".
- The quiet slot belongs to the run that raised it, so the next turn starts without it.
- It does not excuse a request. The agents extension still reminds a turn that
owes a requester a reply, and a turn that ends owing one sends each requester
its last words. Those are read from the rows of the run that ended
(
conversation.last_assistant_text), so a quiet turn sends "(finished without writing anything)" rather than an earlier turn's text. - Job and cell notices end with
albedo_notices.IDLE, which offersno_reply()as a way to stay idle.
Managing the queue #
The mail extension serves the queue in
mail/queue.gleam, and
/queue opens it. The terminal client shows it as a page with drop (ctrl+x),
move to the front (ctrl+t), and clear actions. The web client's queue panel
uses the same routes. The OpenAPI document has them
under /extensions/mail/sessions/{session_id}/queue.
- The session owns its queue. The routes read and edit it through the
command.Contextthatextension.Daemon.session_statereturns for the session (command.QueueRead,QueueDrop,QueueArrange), and the edits are made in the inbox itself. The service's handle is bound to no session, so those operations needCorrespondence, which the mail extension declares (extension capabilities). - Dropping a person's input cancels its receipt, as cancelling the input does.
- A dropped row stays as a record, so a
Oncekey dropped from the queue, such as a Discord message on catch-up or a repeated webhook delivery, is not posted again. - A row the running turn already took cannot be dropped or moved.
- When what waits changes, the session publishes an
extensioninvalidation for the queue page's URL (queue.url).
A stop cancels a person's waiting inputs. Every other row stays in the inbox and can start the next turn. Clear the queue to drop them all.
Editing a waiting message #
A person fixes a message they sent while the agent works by editing it where it
waits. The input resource has the routes (…/inputs/{input_id}/hold and
…/edit, in http_sessions.gleam):
- A hold (
session.hold_input) keeps a person's typed message from being read while they edit it. The session's queue stops at the first held row (queued), so neither it nor anything behind it joins the running turn or starts the next one, and the order the person sent things in holds. - A hold lasts
session.hold_msand is renewed by asking again. One nobody renews lapses and the message is read as it was, so a client that went away cannot keep the queue stopped. Holds persist inmail.held_until, survive a restart, and restore a clamped timer for the remaining window. - An edit (
session.edit_input) puts a new message body in place of the waiting one: same id, same receipt, same position. It releases the hold. Pasted text and files of the edit are saved under a key of their own, so an edit that loses the race never rewrites a file the version already read points to. - A message the running turn took, or one already delivered or cancelled,
answers
409 input_not_waitingto both. Only typed messages are held or edited.
Cancelling one waiting message without touching the turn is the queue's drop,
not inputs/{input_id}/cancel, which interrupts a turn that input started.
Both clients edit a person's own queued message the same way. Up in an empty
composer holds the latest one and loads it, with its attachments, into the
composer; the draft that was there waits until the edit ends. Enter saves the
edit, Escape lets the message go as it was, and sending the composer empty drops
it. The terminal client keeps this in
chat_queue_edit.go. The web client
keeps it in transcript.svelte.ts, and
its queue panel shows a pencil on your waiting messages (clicking the text edits
too), and their × takes the message back into the composer instead of dropping
its text. Besides the messages it sent itself, it edits any item the queue marks
editable: a typed message whose text the queue holds whole, with no images,
files, pasted text or skills an edit from the queue would lose.
Limits #
The inbox holds at most 1000 waiting rows per session (mail.pending_limit),
counting every kind. A person's input that finds it full is rejected with
429 queue_full. A letter producer gets the error and keeps its own record. A
due schedule is not advanced and tries again on the next tick. The queue page
reads and lists only the first 200 rows (command.QueueRead takes the limit)
and counts the rest.
Storage upgrades #
mail_kinds copies an older
table into the current kind check. An older event kind said when it was read;
the copy splits it into event or note and its delivery. It keeps the
mail_remote rows that cascade from the old table.
pending_inputs_inbox
moves inputs from the retired pending_inputs table into the inbox at startup,
and again when a transfer from an older daemon activates. See
storage migrations.