small gleam coding and (not yet) persistent agent daemon with a detachable cli forked from okami.mom/albedo
albedo robot-docs inbox.md
20 kB · 354 lines
Markdown
at main

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.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, 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. 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, 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 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 offers no_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.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).
  • 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):

  • 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. 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.