Skip to main content
Sessions are realm-scoped. A session is visible across surfaces only when they use the same realm_id.

​
Lifecycle

​
Realm visibility rules

See realms for default surface behavior.

​
Session metadata

Session metadata now carries realm context:
  • realm_id
  • instance_id
  • backend
  • config_generation
This allows deterministic resume behavior and cross-surface observability.

​
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()
History responses return committed messages oldest-to-newest and support 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 in realm_manifest.json. A realm stays pinned to the backend recorded in 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.

​
See also