# 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`](../src/albedo/daemon/mail.gleam) owns the storage, the `mail` table. [`inbox.gleam`](../src/albedo/daemon/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`](../src/albedo/harness/sdk/input.gleam) 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`](../src/albedo/daemon/mail.gleam) and `mail.letters` build. The host passes them to extensions as a capability in each context that may post or read letters: - `extension.Setup.inbox` reaches 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.inbox` reaches startup callbacks, such as the Discord manager that posts gateway messages. - `extension.Daemon.inbox` reaches services. - `extension.Preparation` carries `letters`, not an inbox, for owned managed contributions. - `host.Context` carries `inbox` and `letters` for 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`](../src/albedo/harness/sdk/mail.gleam), 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](extensions.md#extension-capabilities)). Webhooks reads its deliveries' letters this way ([extension storage](extensions.md#extension-storage)). Letters between agents go through `host.Context.send_mail`, which [`kernels.gleam`](../src/albedo/harness/runtime/kernels.gleam) binds to the calling session and [`forwarding.send`](../src/albedo/daemon/forwarding.gleam). It resolves the address, forwards to another daemon when needed, and posts the letter. The [`mail.Letters`](../src/albedo/harness/sdk/mail.gleam) 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](operations.md)), 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`](../src/albedo/harness/sdk/letter.gleam) 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](../src/albedo/harness/extensions/schedule/extension.gleam) 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`](../src/albedo/daemon/registry.gleam) and the [plugin contract](plugins.md#daemon-contributions). ## 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. An `alone` row 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 1. A producer posts the row, in its own transaction when it has records to commit with it. 2. Once that transaction commits, the session is told ([`store.after_commit`](../src/albedo/harness/sdk/store.gleam), `mail.put`). A running session registered `mail.register` when 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. 3. 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. 4. A session reads its inbox when it loads, and starts a turn when a waiting row starts one. 5. 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`](../priv/python/albedo_notices.py) chooses each notice's key and sends `{key, display, text}` to `jobs.completed` or `cells.completed` ([`sdk/notice`](../src/albedo/harness/sdk/notice.gleam)), 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`](../src/albedo/daemon/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`](../priv/python/albedo_cells.py), ends such a turn without a reply once its step's tool calls finish. It calls `cells.no_reply` ([`kernel/cells`](../src/albedo/harness/kernel/cells.gleam)), 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 offers `no_reply()` as a way to stay idle. ## Managing the queue The mail extension serves the queue in [`mail/queue.gleam`](../src/albedo/harness/extensions/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](../docs/openapi.yaml) has them under `/extensions/mail/sessions/{session_id}/queue`. - The session owns its queue. The routes read and edit it through the `command.Context` that `extension.Daemon.session_state` returns 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 need `Correspondence`, which the mail extension declares ([extension capabilities](extensions.md#extension-capabilities)). - Dropping a person's input cancels its receipt, as cancelling the input does. - A dropped row stays as a record, so a `Once` key 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 `extension` invalidation 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`](../src/albedo/daemon/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_ms` and 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 in `mail.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_waiting` to 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`](../cli/internal/tui/chat_queue_edit.go). The web client keeps it in [`transcript.svelte.ts`](../web/src/lib/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`](../src/albedo/daemon/migrations/mail_kinds.gleam) 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`](../src/albedo/daemon/migrations/pending_inputs_inbox.gleam) 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](migrations.md). ## Related pages - [All topics](README.md) - [Change guidance](contributing.md) - [Durable operation admission](operations.md) - [Session attachment](sessions.md) - [Agents](agent-sessions.md) - [Webhooks](webhooks.md) - [Discord](discord.md) - [Plugins](plugins.md)