Skip to main content
Meerkat has one agent execution pipeline and two product runtime kernels:
  • MeerkatMachine owns session-scoped runtime state.
  • MobMachine owns multi-agent orchestration.
Auth and scheduling are modeled with their own auxiliary machines, but user turns still reach the same agent loop through SessionService and AgentFactory.

​
Request Path

Runtime-backed surfaces ask MeerkatMachine 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 paths are not a degraded runtime. They are an intentional embedding mode for places where filesystem, TCP, and durable runtime services are absent.

​
Session State

SessionService owns the lifecycle that all surfaces use:
  • create or resume a session
  • start a turn
  • stream events
  • interrupt active work
  • read transcript and metadata
  • archive or delete state
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.

​
Runtime State

MeerkatMachine owns runtime facts that are not just transcript data:

​
Live Channels

Live audio/text channels with model-gated image input are caller-initiated through the live/* 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 used for audio transport bootstrap. The live channel does not replace session history. It is a transport adapter for the same canonical conversation, tool, and turn-boundary semantics.

​
Source Pointers

​
See Also