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.