Sessions
Keep conversation history across turns, read and resume Framework sessions, and choose how session state persists.
An Agent is immutable reusable behavior. An Engine owns session identity,
history, and runtime state. A Session is an engine-bound live conversation.
use everruns::{Agent, Engine, OpenAI};
let agent = Agent::builder() .instructions("Remember the conversation.") .provider(OpenAI::from_env()?) .model("gpt-6.1-sol") .build()?;
let engine = Engine::new();let session = engine.create(agent);let first = session.send_and_wait("My project is Atlas.").await?;let second = session.send_and_wait("Continue with that project.").await?;
assert!(first.success);assert!(second.success);Session is always a live conversation. send accepts a message without
waiting for a response. If a turn is active, the message steers that turn; if
the previous turn has already finished, it starts a follow-up turn. Admission returns before the executor assigns a turn. The receipt
reports Pending; query its authoritative assignment to learn whether it
started or steered a turn:
let session = engine.create(agent);let initial = session.send("Plan my trip.").await?;let latest = session.send("Prefer trains.").await?;
let result = latest.wait().await?;if let Some(assignment) = latest.assignment().await? { println!("turn: {}, steered: {}", assignment.turn_id, assignment.steered);}Waiting on the latest receipt works before or after assignment. send_and_wait (also
available as the shorter run alias) is request/response convenience over the
same live session, not a separate mode.
The first asynchronous operation materializes the in-process host. Later turns
reuse it and send accumulated history through the same context-assembly path.
Two sessions opened on one engine have different opaque IDs and isolated
histories. The engine retains each immutable Agent snapshot, so a session keeps
working after the original Agent handle is dropped. Volatile resume is
engine-scoped: another Engine rejects the id rather than guessing its
configuration. A local profile can be attached to another Engine with the
trusted Agent snapshot; live Engines for the same profile share its backend
bundle.
Conversation isolation does not imply filesystem isolation. The concise
engine.create(agent) path permanently selects the Agent’s default head before its
first inspection or turn; call session.start().await to make that selection
observable earlier. To fix a session to an isolated project view, bind an
Environment before execution. A
session can never switch heads after it starts.
Session::inspect returns the context assembled for the next model call. Use it
for application assertions and debugging rather than reaching into runtime
records or backend stores.
Keep Session::session_id() when the application may need to reopen a
conversation. History and resume below covers typed
resume, bounded transcript pages, and cursor snapshots, and
Persistence covers engine-lifetime memory and the
crash-durable local profile. See
Workspaces and Environments for
exact-head resume, isolation, sharing, and lifecycle, and Events and
cancellation to observe a turn in flight.
Send files
Section titled “Send files”Session::attach keeps a file in the session’s own files at
/attachments/<id>/<name>, read-only, and returns the part that sends it with a
message. The model gets images and PDFs as content and other files by name and
path, and can open any of them again with read_file, including after
compaction. A zip is unpacked into a read-only folder next to it.
use everruns::InputMessage;
let report = session .attach("report.pdf", Some("application/pdf"), std::fs::read("report.pdf")?) .await?;let mut message = InputMessage::user("Summarize the attached report.");message.content.push(report);session.run(message).await?;The bytes decide the file’s type, whatever the caller declared. Embedded channels keep the files people send (a Slack file, for example) the same way.
History and resume
Section titled “History and resume”Every Framework session has a typed SessionId. Keep that value when an
application may need to reopen the conversation:
use everruns::{Agent, Engine, OpenAI, SessionId};
let agent = Agent::builder() .instructions("Remember the conversation.") .provider(OpenAI::from_env()?) .model("gpt-6.1-sol") .build()?;
let engine = Engine::new();let session = engine.create(agent);let session_id: SessionId = session.session_id();session.send_and_wait("My project is Atlas.").await?;
drop(session);let resumed = engine.resume(session_id).await?;resumed.send_and_wait("Continue with that project.").await?;resume verifies the ID against the engine’s session catalog. It
does not infer identity from a non-empty transcript: a valid session can have no
messages, and stray events do not create a resumable session. An unknown ID
returns a typed not-found error. The resumed session uses the immutable Agent
snapshot attached to that engine; it never reconstructs behavior from events.
Read bounded history
Section titled “Read bounded history”Session::history creates an owned query. Calling page returns at most 100
messages by default in canonical event-sequence order, oldest first:
let page = session.history().page().await?;for message in &page.messages { println!("{:?}: {}", message.role, message.text());}Set a smaller or larger page size with limit. The maximum is 256 messages;
an excessive value returns HistoryError::InvalidLimit with the allowed
maximum. A page never claims to contain the entire transcript. Continue from
its opaque cursor:
let first = session.history().limit(25)?.page().await?;if let Some(cursor) = first.next_cursor { let second = session.history().limit(25)?.after(cursor)?.page().await?; // `second` continues the same stable snapshot.}HistoryCursor is opaque, session-bound, and safe to store as a string with
Display and restore with FromStr. A cursor fixes the snapshot’s high-water
mark: events appended after the first page do not appear midway through that
page walk. Start a new query to see them. Passing a malformed, cross-session,
expired, or incompatible cursor returns a distinct typed history error.
History projection also applies a bounded raw-event replay safety limit; an
unusually lifecycle-heavy snapshot that exceeds it returns
HistoryError::HistoryTooLarge instead of performing an unbounded scan.
For callers that intentionally walk the whole snapshot, pages is a lazy
convenience that still reads one bounded page at a time:
let mut pages = session.history().limit(50)?.pages();while let Some(page) = pages.next_page().await? { for message in page.messages { println!("{}", message.text()); }}After the final page, next_page remains fused and returns None. It does not
re-read the backend or produce repeated empty terminal pages.
Persistence
Section titled “Persistence”Framework history is a read-only projection of canonical events. Normal execution has one write path, the engine’s event log, so a resumed session and a running session cannot disagree about the conversation.
| Deployment | Conversation state | Recovery boundary | Use when |
|---|---|---|---|
Engine::new() | Volatile coherent memory authority | One process | Embedding, tests and short-lived tools |
Engine with SqliteHosting | Transactional local session authority | The configured disk plus native supervisor | Durable single-node Framework services |
Engine with ObjectHosting | Per-session object authority | Platform storage and alarms | Native or Wasm execution on Cloudflare/celld |
Legacy LocalConfig | Local canonical events and catalog | One trusted application process | Existing local-store integrations |
| Everruns Platform | PostgreSQL canonical events and actor authority | Distributed server and workers | Horizontal workers and remote clients |
Default: engine-lifetime memory
Section titled “Default: engine-lifetime memory”By default, Engine owns a volatile session catalog and event log. It
retains the immutable Agent snapshot associated with each session and requires
no database, server, network connection, credential, or filesystem access.
Dropping a Session does not immediately discard its committed history. Reopen
it by passing its typed SessionId to the engine that created it. A separate
engine cannot infer the session’s Agent configuration, and process exit loses
volatile history.
This default fits tests, command-line tools, short-lived workers, and applications that deliberately own a higher-level record elsewhere.
Coherent native and Durable Object hosting
Section titled “Coherent native and Durable Object hosting”For durable admission and independently recoverable execution, choose a coherent
session authority on Engine. Native hosting::SqliteHosting owns one transactional
database; the session hosting SPI supports external
authorities for native or Wasm Engine placement. A source-only Durable Object
reference demonstrates the extension. Register immutable AgentBuild
identities and retained Environment factories before creating sessions. Start the
native supervisor or configure platform alarms so recovery does not depend on a
client reconnecting. See Durable Object hosting.
create_registered and send_with_id accept caller-retained identities for retry
after uncertain responses. Admissions, approvals, client results and cancellation
are authority commands; the journal and wakeup obligation commit together.
Resources such as workspace files and compute still require explicit host services.
Checkpoints and rewind
Section titled “Checkpoints and rewind”Engine::checkpoints(session_id) (experimental) returns a handle for
conversation checkpoints on a branch-aware authority such as SqliteHosting.
A host can build checkpoint commands, a restore picker or a conversational
restore tool on it alone:
use everruns::checkpoints::RestoreMode;use everruns::hosting::{AgentBuild, SqliteHosting};use everruns::{Agent, Engine, Model, SessionId};
let build = AgentBuild::new("assistant", "v1");let agent = Agent::builder() .instructions("Be concise.") .model(Model::simulated("Done.")) .build()?;let engine = Engine::builder() .hosting(SqliteHosting::open("authority.db")?) .register(build.clone(), agent) .build();let id = SessionId::new();let session = engine.create_registered(id, &build).await?;let checkpoints = engine.checkpoints(id);
session.send_and_wait("Plan the migration.").await?;let saved = checkpoints.create_labeled("plan agreed").await?;session.send_and_wait("Now rewrite it in Go.").await?;
// Show the user what a restore would undo, then restore.let preview = checkpoints.preview(saved.id).await?;for turn in &preview.dropped { println!("undo: {}", turn.input.as_deref().unwrap_or(""));}let restored = checkpoints.restore(saved.id, RestoreMode::Branch).await?;
// The undone turns stay addressable: redo brings them back.if let Some(undone) = &restored.undone { checkpoints.redo(undone).await?;}createmarks the end of the last finished turn, so a tool can call it while its own turn runs.list,getandpreviewread without changing anything, anddeleteforgets a checkpoint.- A
CheckpointSummarycarries itsid,turn_index, themessage_idthat started its last turn,created_at, an optional label and a display-safepreview.on_active_branchisfalsefor a checkpoint left on an undone branch; restoring it brings those turns back. RestorePreviewlists the turns that leave context (dropped) and the turns a restore brings back from another branch (restored), with exact totals. Text excerpts are short and have control and bidirectional characters removed, so they are safe to show in a terminal or a single UI line.RestoreMode::Branchkeeps the undone turns as a branch named inRestoreOutcome::undone, whichredoreselects. Restoring to a point a retained branch already holds reselects that branch instead of adding one.RestoreMode::Truncatedrops the current branch from the branch catalog, and checkpoints that only it held are no longer listed. For a checkpoint on the current branch that is just the undone turns. For a checkpoint withon_active_branch == falseit is the whole current branch, including the turns before the point where the two branches split.- A session keeps at most 1024 branches, the active one included. Once a
Branchrestore would exceed that, it fails; delete retained branches you no longer need withdelete_branch, or restore withTruncate.delete_branchnever deletes the active branch, and checkpoints only the deleted branch held are no longer listed. A session also keeps at most 1024 checkpoints, not counting ones no branch reaches;deletefrees room.
Nothing is deleted from the journal: a restore changes which branch is the
conversation, so context, history and new input follow it while raw exports
keep every event. Checkpoints and branches survive a restart and
Engine::resume. Restore and redo need a quiescent session, with no running
turn, pending wait or unconsumed input; otherwise they fail without changing
anything, so a restore tool should apply its choice after its turn ends. The
default volatile engine refuses checkpoints. Checkpoints cover the
conversation only: workspace files are not rewound.
Local: crash-durable events
Section titled “Local: crash-durable events”For local applications, the feature-gated LocalConfig adds a crash-durable
event log under the configured application data directory. It also supplies a
trusted real-disk workspace plus SQLite-backed task and schedule state:
use everruns::{Agent, Engine, LocalConfig, OpenAI};
let local = LocalConfig::new(".everruns-data").workspace("./workspace");let agent = Agent::builder() .instructions("Work inside the configured workspace.") .provider(OpenAI::from_env()?) .model("gpt-6.1-sol") .local(local) .build()?;let engine = Engine::new();let session = engine.create(agent);Enable it with cargo add everruns --features local. Select both directories
from trusted application configuration. After a restart, rebuild the Agent
from trusted application configuration, attach it to a new engine, and resume
the committed session by ID. For a session created with an explicit Harness,
also deserialize its portable definition and call
Engine::attach_with_harness; Engine::attach remains the no-Harness path.
The local profile is designed for one embedded process at a time. Coordinate process ownership before handing the directory to another application process. Within one process, every live Engine configured with the same local data directory shares one backend bundle, so concurrent Engine values cannot build divergent JSONL indexes or SQLite handles for that profile.
The event-log file format and host backends are not Framework APIs. Do not edit
the log or build application writes around its representation. Use
Session::history for bounded reads and Engine::resume to continue a session;
see History and resume for the complete lifecycle.
Applications remain responsible for filesystem permissions, backups, retention, and selecting a data directory that is not controlled by model or request input. New local state files are created owner-only on Unix, but applications must still protect copied files and backups. Message content is application data and may be sensitive even though provider credentials are not written there by Framework configuration.
Resume after a process restart
Section titled “Resume after a process restart”Enable local and configure a trusted application data directory when sessions
must survive a new Agent or process:
use everruns::{Agent, Engine, LocalConfig, OpenAI};
let build_agent = || -> Result<Agent, Box<dyn std::error::Error>> { Ok(Agent::builder() .instructions("Remember the conversation.") .provider(OpenAI::from_env()?) .model("gpt-6.1-sol") .local(LocalConfig::new(".everruns-data")) .build()?)};
let first_engine = Engine::new();let session = first_engine.create(build_agent()?);session.start().await?;let session_id = session.session_id();
// In a later process, rebuild trusted behavior before resuming persisted state.let restarted_engine = Engine::new();restarted_engine.attach(session_id, build_agent()?).await?;let resumed = restarted_engine.resume(session_id).await?;The local profile stores a durable session catalog and crash-durable canonical
event log alongside its workspace, task, and schedule state. After restarting,
build another Agent with the same trusted data directory, call
engine.attach(session_id, agent), then engine.resume(session_id). Attachment
rejects IDs absent from that Agent’s configured local catalog. A new session is
made durable by its first async operation (run, inspect, or a history page
read); merely allocating a synchronous handle does not commit it.
A running turn, or one waiting on a person (a tool approval or an ask_user
question), lives inside the process, so a process exit leaves it in the log
without an end. After resuming, resumed.interrupted_turn() reports such a
turn and the tool calls it had not finished, and
resumed.resume_interrupted_turn() continues it in the same turn. A call runs
again only when that is safe: it waited on a person, which asks the approver
or ask_user responder again under the same tool call id, its tool is
marked FunctionTool::idempotent(), or it never started (the log has no
tool.started for it). Any other unfinished call is recorded as
interrupted (listed in not_rerun), so the model learns its outcome is
unknown and nothing runs twice. A turn cut off between steps reasons again.
For a session created with an explicit Harness, persist its serialized portable
definition, deserialize it after restart, and call
engine.attach_with_harness(session_id, agent, harness) instead. Harness
deserialization validates the definition and generates a new process-local
runtime identity.
The local profile is for one embedded process at a time. Do not write or edit its files as application data: messages are a read-only projection of committed events, and the storage formats are not Framework APIs.
History does not contain model credentials or application secrets unless an application deliberately includes them in message content or event metadata. Choose and protect the local data directory accordingly.
Canonical host persistence
Section titled “Canonical host persistence”Durable conversation truth belongs to canonical events; history and context
are projections of that record. Advanced hosts use EventLog and
EventHistory from everruns-core (host feature), including JsonlEventLog when a local
append-only event log is appropriate. Framework applications continue sessions
with Engine::resume and traverse bounded event-derived pages from
Session::history.
A host that needs its own storage implements the public EventLog/EventReader
SPI and supplies it through HostBackends::with_event_log; see
Implementing a custom event log.
JsonlEventLog bounds startup recovery before indexing: the default accepts at
most 128 MiB and 1,000,000 canonical events. Oversize logs fail to open with a
typed recovery-limit error instead of allocating or scanning without bound.
Do not design new application persistence around a legacy storage representation.
Moving legacy sessions to SqliteHosting
Section titled “Moving legacy sessions to SqliteHosting”Engine::cut_over_legacy_session (experimental) moves an existing LocalConfig
or custom-backend session into SqliteHosting with the same SessionId. The
import is lossless and atomic: the full event history keeps its event ids and
sequences, and admissions, parked client calls and approvals, compaction
checkpoints, session values, finished task records and the workspace binding
come along. Retrying after a crash or a lost reply returns the same result. A
cutover to a different build fails. cut_over_legacy_session_with_metadata
also records binding metadata the legacy lane never stored, such as the
parent_session_id of a child session.
let profile = SqliteHosting::open("authority.db")?;let engine = Engine::builder().hosting(profile.clone()).build();engine.register_agent_with_environment( build.clone(), agent.clone(), None, "imported-workspace", ImportedWorkspaceFactory::new(agent, profile),)?;let report = engine.cut_over_legacy_session(session_id, &legacy_agent, &build).await?;let session = engine.resume(session_id).await?;The legacy lane is frozen first. After that, Engine::attach with the legacy
Agent returns ResumeError::CutOver and no legacy turn starts, in any process
that shares the store. The JSONL file is never written again; when a tool still
needs JSONL, rebuild it from the authority with
SqliteHosting::rebuild_jsonl_export(session_id, path), which writes the same
line format atomically and can be repeated at any time. If a cutover
fails before the authority commits, the session stays frozen until you retry or
call Engine::abandon_legacy_cutover.
The session must be quiescent. A cutover refuses, without writing anything to
the authority, while a legacy turn is running or while the session has a task
still running under its legacy owner. Schedules move with the session and fire
from SqliteHosting::supervise; the legacy lane no longer delivers them. Tasks whose
owner is gone move with the session; the authority re-attaches or settles them
on the next activation without re-running uncertain work. Session secrets move only when the
authority has secret keys (SqliteHosting::with_secret_keys, the same
key_id:base64_key format as SECRETS_ENCRYPTION_KEY); they are stored
encrypted and the cutover refuses without keys. It also refuses when the
target build cannot reopen the session’s workspace head. Use
ImportedWorkspaceFactory so the authority reopens that head after restarts.
The Agent’s in-memory default workspace is not durable on either lane, so its
files are not migrated; the report sets volatile_workspace.
Rewinding and branching history
Section titled “Rewinding and branching history”SqliteHosting keeps every event forever and tracks which events form the
conversation (experimental). A branch is a list of event-sequence ranges made of
whole turns. The model context, Session::history and Session::events_after
follow the active branch. SqliteHosting::export_jsonl still returns every
event with its original id and sequence. New input extends the active branch, so
sequences on a branch can have gaps.
let lineage = engine.history_lineage(session_id).await?;// Rewind to just after sequence 12; the old branch stays retained.let ranges = lineage.rewind_ranges(12).expect("12 is on the active branch");engine .select_history_branch(session_id, command_id, lineage.revision, "undo-1", Some(ranges)) .await?;// Redo: reselect the retained branch by name.engine .select_history_branch(session_id, redo_id, lineage.revision + 1, "main", None) .await?;A selection is accepted only when the session is quiescent: no execution, no
open turn, no pending tool call or approval, and no unconsumed input. It also
checks the revision you read. Anything else is refused, never queued or
discarded. Retrying the same command id returns the first reply. Compaction
checkpoints follow the branch too. A checkpoint can be used only on a branch
that shares the history it summarized, so a summary of an abandoned branch never
shows up on another branch. Checkpoints of a shared earlier part stay usable.
MemoryHosting and other authorities without branch support refuse these
calls.
To import saved history that already has branches, convert your own timeline
format into a ConversationLineage and pass it with
Engine::cut_over_legacy_session_with_options(.., CutoverOptions::new().lineage(lineage)).
The whole journal is imported. The lineage names the active branch, the
retained branches and each branch’s compaction checkpoints. A retry must pass
the same lineage.
One process runs a session at a time
Section titled “One process runs a session at a time”Each session runs as an actor: its event log is its state, and a turn holds the session’s lease while it runs. The lease is taken when a turn starts, renewed while it runs (including while it waits on an approval or a question), and given up when the turn ends. With the local profile the leases live in the profile’s SQLite database, so if two processes share a data directory, a turn started in one while the other runs the same session fails with an error saying the session runs in another process. Between turns no process holds a session, so either one can pick it up. A lease lasts 10 seconds unless renewed, so after a crash the restarted process waits at most that long before it resumes a turn the old process was running.
Platform: distributed durable execution
Section titled “Platform: distributed durable execution”The Everruns Platform uses the same everruns-core (engine feature) turn state machine and
turn loop as the Framework. The server stores each input and marks the session runnable; a
worker leases the session over gRPC and runs the whole turn, and PostgreSQL stores the canonical
events. If a worker disappears mid-turn, its lease expires and a later worker resumes the turn
from the session’s event log.
The Platform is a deployment boundary, not another configuration mode on
everruns::Engine. Remote applications use the Platform API or an SDK; product
hosts compose the lower-level durable crates. See Framework
Architecture for the layer map.