Skip to content
Docs
GitHub

Sessions

Keep conversation history across turns, read and resume Framework sessions, and choose how session state persists.

18 min readEdit on GitHub

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.

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.

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.

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.

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.

DeploymentConversation stateRecovery boundaryUse when
Engine::new()Volatile coherent memory authorityOne processEmbedding, tests and short-lived tools
Engine with SqliteHostingTransactional local session authorityThe configured disk plus native supervisorDurable single-node Framework services
Engine with ObjectHostingPer-session object authorityPlatform storage and alarmsNative or Wasm execution on Cloudflare/celld
Legacy LocalConfigLocal canonical events and catalogOne trusted application processExisting local-store integrations
Everruns PlatformPostgreSQL canonical events and actor authorityDistributed server and workersHorizontal workers and remote clients

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.

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?;
}
  • create marks the end of the last finished turn, so a tool can call it while its own turn runs. list, get and preview read without changing anything, and delete forgets a checkpoint.
  • A CheckpointSummary carries its id, turn_index, the message_id that started its last turn, created_at, an optional label and a display-safe preview. on_active_branch is false for a checkpoint left on an undone branch; restoring it brings those turns back.
  • RestorePreview lists 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::Branch keeps the undone turns as a branch named in RestoreOutcome::undone, which redo reselects. Restoring to a point a retained branch already holds reselects that branch instead of adding one.
  • RestoreMode::Truncate drops 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 with on_active_branch == false it 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 Branch restore would exceed that, it fails; delete retained branches you no longer need with delete_branch, or restore with Truncate. delete_branch never 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; delete frees 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.

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.

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.

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.

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.

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.

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.

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.