MeerkatMachineowns session-scoped runtime state.MobMachineowns multi-agent orchestration.
SessionService and AgentFactory.
Request Path
Runtime-backed surfaces askMeerkatMachine to prepare session bindings before
they build or resume an agent. Those bindings carry the session-owned handles
for turn state, ops lifecycle, tool visibility, MCP lifecycle, peer interaction,
model routing, auth leases, and completion cursors.
The factory consumes that bundle through
RuntimeBuildMode::SessionOwned(bindings). It does not invent a second runtime
authority when the bundle is present.
Runtime-Backed Surfaces
Runtime-backed surfaces are the normal product path when you need durable
sessions, keep-alive behavior, completion-feed wakeups, cross-process
observability, or shared realm state.
Standalone Surfaces
Standalone mode is explicit. It is used by tests, narrow Rust embeddings, and the browser/WASM runtime.
Standalone describes runtime-authority composition, not storage durability. An
embedded Rust host may pair standalone runtime bindings with an explicit
persistent session store, while browser/WASM uses its own in-memory substrate.
The mode is intended for hosts that do not need shared runtime control-plane
semantics such as keep-alive and recovery.
Session State
SessionService owns the lifecycle used by runtime-backed product surfaces:
- create or resume a session
- start a turn
- stream events
- interrupt active work
- read transcript and metadata
- archive or delete state
AgentBuilder to construct a
standalone agent directly through AgentFactory; that path has no service
lifecycle or runtime recovery semantics unless the host composes them.
Persistent sessions use realm storage. When SQLite support is compiled, new
persistent realms default to SQLite because it supports normal same-realm
multi-process use. JSONL remains available as an explicit inspectable backend.
The serialized Session is domain state, not proof that it is current. Its
released envelope contains the conversation, metadata, usage, and compact
transcript-rewrite graph, but no embedded migration, recovery, or persistence
authority. The selected store issues one physical authority profile:
WholeBlobbinds a session ID, store revision, and exact blob digest.HeadCanonicalbinds a session ID, store revision, boundary head, and committed head token.
RunCheckpointReceipt. Despite that compatibility type name, there is no
embedded checkpointed session state. The final runtime boundary promotes the
latest receipt without reserializing or reapplying the turn. A shutdown tail is
classified by SessionDocumentMachine, authorized by MeerkatMachine, and
committed atomically by RuntimeStore; ambiguous evidence is held intact.
StorageLayout selects paths. RealmStorageProvider supplies the session,
runtime, schedule, WorkGraph, job, blob, and artifact stores with one durability
declaration per domain. Realm configuration may inherit through parent realms;
state never does.
Runtime State
MeerkatMachine owns session runtime facts, while adjacent domain machines
retain their own authority and compose into the runtime:
Detached work is not folded into the runtime ops map. Reusable background work
belongs to
DetachedJobMachine and the job store. Blob payloads belong to the
realm blob store. The runtime carries references and wakeups for those domains;
it does not become their second owner.
Durable Events And Projections
Built-in realm-backed persistent sessions install an optional durable event audit projection. The projection path uses a dedicated unbounded queue and shares eachArc<EventEnvelope<AgentEvent>> with the UI stream without making the bounded
UI broadcast its source. If a UI subscriber falls behind, it receives a typed
StreamTruncated marker with the dropped count and can resynchronize.
The projector is an optional PersistentSessionService composition seam and
asynchronous best-effort derived state. A projection append fault latches replay
and later resume checks fail closed, but it does not fail or roll back the
already-committed turn. Custom persistent hosts that do not install it have
store-backed sessions but must not claim durable event replay or ATIF evidence.
Durable audit append failure is fail-closed for replay: the session latches a
typed projection halt and never appends past a sequence hole. The committed
turn remains owned by the RuntimeStore/backend carrier. The .rkat session view is a
further rebuildable projection, and meerkat-atif exports the envelopes that
were successfully projected.
Any checkpoint persisted by a derived projector is only a rebuild cursor for
derived output. It is never embedded session-resume or persistence authority.
Durable Jobs And Delivery
meerkat-jobs owns durable submit and deduplication, fenced attempts, leases,
progress, cancellation, terminal results, subscriptions, and its terminal
outbox. meerkat-runtime owns the delivery inbox: stable delivery identity,
monotonic sequence, exact replay, and ordered application cursor.
The canonical job_runtime_delivery composition transfers a job terminal or
notification outbox entry into the runtime inbox, then acknowledges successful
transfer back to the job store. The projector in meerkat/src/job_delivery.rs
is mechanical. Schedule and WorkGraph may reference or await a job, but their
own machines remain the authority for occurrence and work-item truth.
Live Channels
Live audio/text channels with model-gated image input are caller-initiated through thelive/* JSON-RPC method family. ModelCapabilities.realtime
gates whether live/open can attach to a session; the returned image_in
capability gates still-image input for that binding. The --live-ws <addr>
flag on rkat-rpc enables the WebSocket listener. Builds with the
live-webrtc feature expose the opt-in --live-webrtc runtime flag. With that
flag enabled and no WebSocket listener configured, live/open selects WebRTC.
The live channel does not replace session history. It is a transport adapter for
the same canonical conversation, tool, and turn-boundary semantics.