Skip to content

Sessions In progress

Durable, replayable history of everything an agent did.

A session is the full record of an agent's work: every message, tool call, file change and artifact, in the order it happened. The record is the source of truth, so a session can survive a crash, be resumed or forked, and be replayed exactly as it happened.

In progress, not ready for use

The session contracts and platform foundations are in place. The service that records and serves sessions is still being built. Where it stands has the detail.

Everything the agent did, in order ​

Each step becomes an event in the session's log. Large output such as diffs and terminal logs is kept alongside, so the log stays small and replay stays exact.

Fix the flaky login testAppend-onlyReplayable
  1. 1YouMake the login test stop flakingUserMessageRecorded
  2. 2Tool call requestedRun the test suiteToolCallRequested
  3. 3ApprovedYou allowed itToolCallApproved
  4. 4Tool call completedOne failure, with the output kept for replayToolCallCompleted
  5. 5File changedtests/login.test.tsFileChanged
  6. 6Artifact recordedA structured diff of the fixArtifactRecorded
  7. 7CheckpointA point a later run can restore fromCheckpointProduced
  8. 8Assistant replyFixed: the test raced a timerAssistantMessageCompleted
Replaying from the first eventMessagesTool callsFilesArtifactsCheckpoints

One log, every view ​

Writes pass through one gate and land in one log. Every screen and query reads a view built from that log, so a view can always be rebuilt and never overrules it.

Write
You or an agentSends a command
DeciderChecks the command against the history so far
Session logOne append-only stream per session. The only source of truth.Never rewritten, never purged
Read
Read modelsViews folded from the log, never the authority
QueriesSessions, history and the one to resume
Artifact storeDiffs, terminal output and files. The bytes are stored first, then the log points at them.
Every answer says how fresh it is
  • CurrentReflects every event up to now
  • LaggingStill answers, and says how far behind it is
  • IndeterminateCould not check, and says so

Ask to see your own write and you get it, or a clear error when the view cannot catch up in time. Never a plausible wrong answer.

Built on events ​

Every change to a session is an event, published on NATS. That one decision is what makes sessions easy to extend, watch and change: anything that needs to know about a session follows its events instead of calling the service that wrote them.

One event, as it travels
subject
session.sessions.events.<id>Which session it belongs to
type
ToolCallCompletedWhat happened
event id
stable, from the commandA retry is recognized
correlation
the request it servesFollow one request end to end
causation
what led to itWalk the chain of cause
trace
W3C trace contextJoins your traces
  • Session listRecent sessions, titles and previews
  • Resume indexThe session to pick up next
  • SearchFind a session by what happened in it
  • Your serviceNotify, export or index. It replays from the first event.

Pluggable

New features read the log. They never ask the writer to change.

  • A view catches up from its last checkpoint, or replays from the startIn the platform
  • Follow one session or every session with a subject filterIn the platform
  • Add a view later and it still sees the whole historyDesigned

Observable

The log already says what happened. Telemetry says how it went.

  • Every command is traced with its outcome and its write guardIn the platform
  • Metrics for replays, snapshots and write conflictsIn the platform
  • Correlation, causation and trace context ride on every eventDesigned

Safe to change

Behavior is plain logic over events, so it is easy to test and replace.

  • Decisions are pure functions, tested by replaying eventsIn the platform
  • Deciders run as sandboxed WebAssembly, upgraded while work is in flightIn the platform
  • Rebuild any view, or see a session as it was at any pointDesigned
In the platform means the shared event-sourcing runtime ships today: deciders, snapshots, projections and their telemetry. The session service built on top of it is still designed.

Honest after a crash ​

Runners crash, networks drop and retries happen. A session records what it knows and nothing more, so recovery starts from the truth.

A runner dies mid tool call

  1. Requested
  2. Approved
  3. Started
  4. Crash
Failed Interrupted, not failed

The call started and nothing settled it, so the session says exactly that. Calling it failed would claim something nobody knows.

  • It is confirmed to have runCompleted
  • It is confirmed not to have runFailed
  • Nobody can tell yetUnknown, until the truth is learned

Every write gets a straight answer

  • CommittedIt is in the log.
  • DeduplicatedA retry found it already there. Nothing is doubled.
  • Not appendedRefused before it was sent. Safe to retry.
  • ConflictSomeone else wrote first. Re-read and decide again.
  • UnknownSent but not confirmed. A retry commits it or finds the copy.

No write ends as "best effort". Every event has a stable identity, so a retried write is recognized instead of recorded twice.

Start, fork, delegate, recover ​

Sessions branch the way work does, and every branch keeps its own history.

  • StartA fresh session with an empty history.
  • ForkBranch off an existing session to try another way. The original stays as it was.
  • DelegateHand part of the work to another agent in a child session, linked to its parent.
  • RecoverSalvage a damaged session into a new one. Running the salvage twice never makes a second copy.
Inside a session, history is only ever added to
  • RewindHides later turns from readers and the next run. What ran still counts.
  • CompactMarks a summary point so the model reads less. The full history stays.
  • Rename, archive, hideEach is a new event. Hiding a session deletes nothing.

What we promise ​

  • Nothing is rewrittenEvents are never edited or purged. Hiding a session deletes nothing from its log.
  • Honest about unknownsA step the session cannot confirm is recorded as unknown, never guessed as failed.
  • Safe to retryA repeated command or write is recognized, so a retry never records an event twice.
  • Fresh, or it says soEvery read reports how current it is. A read that must see your write gets it or a clear error.
  • Artifacts are checkedReaders check artifact bytes against the digest in the log. When verification is required, a mismatch is refused, not warned about.
  • One bad call stays oneA malformed tool call from a provider is set aside without throwing out the good calls next to it.
  • Repairs never touch historyThe session doctor finds and fixes problems in views and indexes. No repair touches the event stream.

Where it stands ​

  • Event-sourcing runtimeDeciders, snapshots, projections and their telemetry, shared across the platform. Sessions will run on it.Built
  • Session event, command and state contractsProtobuf schemas define every event, command and state a session can have.In progress
  • Query, artifact, doctor and maintenance contractsThe wire contracts for reading and operating sessions are defined in protobuf.In progress
  • Session log and decider on NATS JetStreamOne stream per session, with guarded appends and duplicate detection.Designed
  • Read models and the query serviceViews folded from the log, with freshness on every answer and reads of your own writes.Designed
  • Crash recovery and safe retriesReconciling interrupted tool calls, and a typed outcome for every write.Designed
  • Artifacts, structured diffs and terminal replayLarge output stored outside the log and verified against the digest the log records.Designed
  • Doctor and maintenanceHealth reports, view repair, schema migration and salvage of damaged sessions.Designed

Learn more ​

Understand the design

Reading sessions

Artifacts and replay

Operating sessions

Released under the Apache License 2.0.