small gleam coding and persistent agent daemon with a detachable cli and a canvas ui forked from okami.mom/albedo
albedo robot-docs sessions.md
8.0 kB · 143 lines
Markdown

Session attachment #

A daemon session actor owns the live state of a conversation and coordinates submissions, observation, and kernel lifecycle. Durable conversation data lives in the store. session.gleam defines the actor messages and public calls. the harness runtime owns the prepared composition and kernel.

Submissions and cancellation #

Every submission is first stored in the session's inbox, and the actor hears of it after the commit (mail.register); a person's input is admitted through the actor (session.admit_durable). The actor checks workspace readiness and coordinates turn preparation and kernel acquisition. Its queue is the inbox itself: it reads the waiting rows when a row arrives, when a turn ends, at each step, and when it loads, and holds only the rows its running turn took. session.cancel_input and session.interrupt are separate operations, and so are session.hold_input and session.edit_input, which let a person fix a message that still waits (inbox). The actor also handles shell commands and side questions through separate messages. See session.gleam, session_submission.gleam, and session_run.gleam.

A session retains the runtime reservation for preparation or kernel acquisition. When cancellation removes the last parked turn needing that work, it withdraws the reservation. Other parked commands keep it alive. Completion messages carry a local request generation, so a cancelled request's late reply cannot clear a newer request. Runtime admission, shared requester lifetime and cleanup bounds are described in runtime admission.

ACP cancellation has an additional attachment authorization check at the actor transition. See ACP and acp_session.authorize_cancellation.

Attached files #

http_sessions.input checks the input's durable intent before preparation and admits it with session.admit_durable afterward. Preparation expands pastes and attached files before admission. uploads.gleam validates the files, saves them for a local workspace, and adds their paths to the model's text only. The session actor checks the workspace again when it admits the input. The display text stays as submitted. The submission keeps each file's name and decoded size as history metadata, without the path or bytes. See input admission for retries and errors, and saved pastes and uploads for retention.

Observation and streams #

A Cursor contains a generation and sequence. session.read returns a page of events and may include a capture. Watchers register with watch, acknowledge delivery with consumed, and unregister with unwatch. These interfaces are defined in session.gleam.

http_session_stream.gleam sends a snapshot and a reset event when a client first attaches, the generation changes, or replay is unavailable. A snapshot that exceeds the response budget produces snapshot_too_large. A stopped session has no next batch. Consumers must handle resets and stream failures rather than assume every event remains replayable.

Loaded sessions and unloading #

The session actor can prepare a composition without a kernel and request a kernel when work needs one. It can release an idle kernel and unload session state. session.gleam defines these transitions, including AcquireKernel, Release, and Unload. Durable history and live actor state are different things. Unloading does not itself mean deleting the conversation.

History and recovery #

The actor exposes rewind and history capture operations. history.gleam owns durable forks and rewinds. Each runs in one store transaction. Read-only history folds, boundary snapshots, and session metadata reads live in sdk/history, which daemon and extension readers share. The stored row format lives in sdk/transcript_codec. Transcript writes stay in conversation.gleam. Extensions that index transcript rows by position follow a fork or a cut through FollowPlugin inside that transaction. A follower's error rolls back the fork or rewind. Callers pass runtime.followers, which holds every declared extension's followers, enabled for the session or not, and quarantined or not. Turn completion and salvage have separate paths in session.gleam and session_salvage.gleam. active_output.gleam and active_output_store.gleam flush provisional text output every second (to $ALBEDO_HOME/active-output/draft-<session>.json while inline, and .meta/.data once spilled past 64 KiB) without eagerly flushing thinking deltas. On load of a non-idle session, session_salvage.recover_crashed commits any recovered text matching the transcript's current high_water as an unfinished assistant row within the 15-minute lease_ms retention window. Persistence and recovery can fail, so callers must handle the returned results rather than infer success from a requested transition.

Session deletion coordinates closure with the runtime and durable state. session_deletion.gleam owns the daemon deletion path. Agent code cannot invoke deletion through agents.delete. See agents.

Generated titles #

session_naming.gleam owns title inference and naming intent inside the session actor. The first accepted human message of an unnamed root session starts one tool-free request alongside the answer. It uses the session's profile and model, asks for effort none (the provider sends the lowest level the model takes), bounded output, and a 30-second deadline. Failed initial requests are not retried; the latest-message fallback remains until someone names the session.

/retitle uses POST /sessions/{id}/title-generation with {} and no required If-Match. Admission does not change the configuration revision. A successful regeneration sets the person's name; failure leaves it unchanged and emits a notice without failing the main turn. Context is bounded original human text and visible assistant replies, not expanded skills, pastes, attachments, ACP resource links, system context, or tool output.

One title worker runs per session through session_run.supervised. Newer naming intent, including no-op names and model/profile switches, supersedes pending results. The generation is actor-local; auto_title_attempted is set to 2 when the first accepted human message claims an initial attempt and 1 when it settles or a user stop cancels it. On reload, resume_initial retries only sessions left at 2 (never forks, rewound archives, or settled attempts). Closing the session cancels its title worker. Stop cancels an initial title only within the captured input boundary. See commands.