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.
- 2Tool call requestedRun the test suite
ToolCallRequested - 3ApprovedYou allowed it
ToolCallApproved - 4Tool call completedOne failure, with the output kept for replay
ToolCallCompleted - 5File changedtests/login.test.ts
FileChanged - 6Artifact recordedA structured diff of the fix
ArtifactRecorded - 7CheckpointA point a later run can restore from
CheckpointProduced
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.
- 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.
- 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
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
- Requested
- Approved
- Started
- Crash
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.
- 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
- Session Aggregate
- Session Crash Boundaries
- Session Tool Effects
- Session Provider Faults
- Session Schema Boundaries
Reading sessions
- Session Query Contract
- Session Projection Freshness
- Session Pagination
- Session Resume Index
- Session Title and Preview
- Session Presentation Caches
Artifacts and replay
Operating sessions
