realm_id.
Lifecycle
| Operation | What it does |
|---|---|
create_session | Build an agent, run first turn, persist session metadata |
start_turn | Continue existing session; returns SESSION_BUSY if a turn is already running |
interrupt | Cancel in-flight turn |
read | Return session state + usage |
read_history | Return committed transcript messages with optional pagination |
list | List sessions in the active realm |
archive | Commit the durable archived verdict, retire the live runtime handle, and hide the session from normal listing; committed history stays readable on persistent backends |
Realm visibility rules
| Scenario | Result |
|---|---|
CLI + RPC with same realm_id | Shared session visibility |
CLI + RPC with different realm_id | Strict isolation |
| 100 RPC servers, no realm provided | Each gets its own isolated realm by default |
100 agents, same explicit realm_id | Shared state and consistent visibility |
Session metadata
Session metadata now carries realm context:realm_idinstance_idbackendconfig_generation
Session history
Public surfaces now expose full transcript history separately from lightweight metadata reads.- REST:
GET /sessions/{id}/history - RPC:
session/history - MCP:
meerkat_history - Python SDK:
read_session_history(),Session.history(),DeferredSession.history() - TypeScript SDK:
readSessionHistory(),Session.history(),DeferredSession.history()
offset / limit pagination. They do not expose in-flight partial output.
Archive ownership is uniform across profiles: the canonical SessionDocumentMachine owns the session’s lifecycle-terminal fact, and archiving commits the durable archived verdict first, then retires the live runtime handle, so a half-archived “resurrection window” is unrepresentable. Archived sessions are hidden from listing and blocked from further mutation. On persistent backends the committed transcript stays readable through history reads; the in-memory ephemeral service keeps a final read-only state view but answers archived history reads with SESSION_PERSISTENCE_DISABLED. It is a lifecycle visibility change, not a history wipe.
Persistence and backend pinning
Backends are selected once per realm and pinned inrealm_manifest.json.
| Backend | Notes |
|---|---|
sqlite | Durable embedded database; default for new persistent realms when compiled |
jsonl | File-based, inspectable, useful for debugging |
memory | In-process session storage for throwaway runs; not durable across process restart |
realm_manifest.json.
Concurrency guarantees
- One turn per session at a time.
- No implicit queueing for concurrent turns.
interrupt()is explicit cancellation.- Config writes can be synchronized with generation CAS (
expected_generation) to avoid lost updates during concurrent operations. - SQLite-backed realms support the standard same-realm multi-process workflow across CLI, REST, RPC, MCP, and SDK surfaces.