Rust SDK

This page documents MobKit v0.8.34 (mirrored from v0.8.34). The Rust crate meerkat-mobkit is the primary interface for MobKit. All other interfaces (JSON-RPC, SDKs, console) are built on top of it.

Installation

Cargo.toml

[dependencies]
meerkat-mobkit = "0.8.34"
tokio = { version = "1", features = ["full"] }
serde_json = "1"

Quick start

Host-supplied modules are optional. This runnable baseline starts no module processes; add module declarations only for executables or MCP transports your host actually supplies.

use meerkat_mobkit::{start_mobkit_runtime, DiscoverySpec, MobKitConfig};
use std::time::Duration;

let config = MobKitConfig {
    modules: vec![],
    discovery: DiscoverySpec {
        namespace: "my-app".into(),
        modules: vec![],
    },
    pre_spawn: vec![],
};

let runtime = start_mobkit_runtime(config, vec![], Duration::from_secs(30))?;

Core types

MobKitConfig

Top-level configuration for the module runtime.

struct MobKitConfig {
    modules: Vec<ModuleConfig>,
    discovery: DiscoverySpec,
    pre_spawn: Vec<PreSpawnData>,
}

ModuleConfig

Configuration for a single module.

struct ModuleConfig {
    id: String,
    command: String,
    args: Vec<String>,
    restart_policy: RestartPolicy,
}

EventEnvelope

Timestamped event wrapper.

struct EventEnvelope<T> {
    event_id: String,
    source: String,
    timestamp_ms: u64,
    event: T,
}

UnifiedEvent

Agent or module event discriminator.

enum UnifiedEvent {
    Agent {
        agent_id: String,
        event_type: String,
        payload: Option<Value>,
    },
    Module(ModuleEvent),
}

struct ModuleEvent {
    module: String,
    event_type: String,
    payload: Value,
}

Runtime functions

`start_mobkit_runtime`

Bootstrap a module-only runtime:

fn start_mobkit_runtime(
    config: MobKitConfig,
    agent_events: Vec<EventEnvelope<UnifiedEvent>>,
    timeout: Duration,
) -> Result<MobkitRuntimeHandle, MobkitRuntimeError>

`start_mobkit_runtime_with_options`

Bootstrap with additional options:

fn start_mobkit_runtime_with_options(
    config: MobKitConfig,
    agent_events: Vec<EventEnvelope<UnifiedEvent>>,
    timeout: Duration,
    options: RuntimeOptions,
) -> Result<MobkitRuntimeHandle, MobkitRuntimeError>

`UnifiedRuntime::builder`

Builder for the combined mob + module runtime:

UnifiedRuntime::builder()
    .mob_spec(spec)
    .module_config(config)
    .timeout(duration)
    .build()
    .await?

For identity-first runtimes with a roster provider, the Rust builder can enable identity-scoped agent memory injection. Open the SQLite authority explicitly and pass it through the provider seam:

use std::sync::Arc;
use meerkat_mobkit::{AgentMemoryConfig, SqliteAgentMemoryStore, UnifiedRuntime};

let memory = Arc::new(SqliteAgentMemoryStore::open(".mobkit/state/agent-memory")?);

let runtime = UnifiedRuntime::builder()
    .definition_path("config/mob.toml")
    .persistent_state(".mobkit/state")
    .roster_provider(roster_provider)
    .agent_memory(memory, AgentMemoryConfig::default())
    .build()
    .await?;

The SQLite provider stores one database per realm. When a realm is first accessed and its SQLite connection is opened, it imports that realm’s legacy markdown files from the same agent-memory directory. Markdown is not a live provider. To supply another storage or retrieval authority, pass any Arc<dyn AgentMemoryProvider> with .agent_memory(provider, config). Rust callers can write, read, and delete durable records through the unified runtime:

use meerkat_mobkit::{AgentMemoryRecallRequest, AgentMemorySelection, NewAgentMemory};

let record = runtime
    .remember_agent_memory(
        "default",
        &identity,
        NewAgentMemory {
            title: "Deployment preference".into(),
            body: "Use the staging realm before production deploys.".into(),
            tags: vec!["deploy".into()],
        },
    )
    .await?;

let records = runtime
    .recall_agent_memory(AgentMemoryRecallRequest {
        identity: identity.clone(),
        realm: "default".into(),
        selection: AgentMemorySelection::Contextual,
        query_text: Some("What should I check before deploying?".into()),
        query_terms: vec!["deploy".into()],
        max_entries: 4,
    })
    .await?;

if let Some(record) = records.first() {
    runtime
        .forget_agent_memory("default", &identity, &record.memory_id)
        .await?;
}

Module routing

`route_module_call`

Route a typed call to a module:

pub fn route_module_call(
    runtime: &MobkitRuntimeHandle,
    request: &ModuleRouteRequest,
    timeout: Duration,
) -> Result<ModuleRouteResponse, ModuleRouteError>

`route_module_call_rpc_json`

Route a JSON-encoded request and receive a JSON-encoded response:

pub fn route_module_call_rpc_json(
    runtime: &MobkitRuntimeHandle,
    request_json: &str,
    timeout: Duration,
) -> Result<String, RpcRouteError>

Operational subsystem functions

Decisions

fn validate_bigquery_naming(naming: &BigQueryNaming) -> Result<(), DecisionPolicyError>
fn load_trusted_mobkit_modules_from_toml(toml: &str) -> Result<Vec<ModuleConfig>, DecisionPolicyError>
fn enforce_console_route_access(auth: &AuthPolicy, console: &ConsolePolicy, req: &ConsoleAccessRequest) -> Result<(), DecisionPolicyError>
fn validate_runtime_ops_policy(policy: &RuntimeOpsPolicy) -> Result<(), DecisionPolicyError>
fn validate_trusted_oidc_runtime_config(config: &TrustedOidcRuntimeConfig) -> Result<(), DecisionPolicyError>
fn build_runtime_decision_state(input: RuntimeDecisionInputs) -> Result<RuntimeDecisionState, DecisionRuntimeError>
impl RuntimeDecisionState {
    // Explicit opt-out: a console that trusts no identity provider.
    fn local_console(console: ConsolePolicy, bigquery: Option<BigQueryNaming>) -> Self
    // Trusted module set for a local_console state (starts empty).
    fn with_modules(self, modules: Vec<ModuleConfig>) -> Self
}

build_runtime_decision_state is the validating constructor; it checks the trusted OIDC snapshot only when console.require_app_auth is true. RuntimeDecisionState::local_console is the explicit opt-out for local or host-protected consoles; at serve time the runtime reads console, the session-store naming and modules, and a host with trusted modules adds them with .with_modules(...). The default stays fail-closed: ConsolePolicy::default() requires app auth, and a state that trusts no key refuses every request. See Decisions for every check and when it runs. gateway_composition also exports the HTTP exposure vocabulary both binaries use: GatewaySurface (RpcGateway | MobkitGateway, Display is the binary name), ConsoleAuthPosture::of(&decisions) (Open | ClosedToEveryCaller | Enforced, the one classifier behind the bind gate and the non-loopback warning), HttpBindPolicy, validate_http_bind_policy(surface, listen, policy), warn_on_non_loopback_bind(surface, bound, &decisions), and the typed HttpExposureParseError behind parse_http_listen_addr, parse_http_public_base_url and parse_http_listen_arg. The error enums (HttpBindPolicyError, HttpExposureParseError, GatewayHostConfigError, HostConfigTableInMobToml) are #[non_exhaustive].

Authentication

fn inspect_jwt_header(token: &str) -> Result<JwtHeaderView, JwtValidationError>
fn validate_jwt_locally(token: &str, config: &JwtValidationConfig) -> Result<ValidatedJwt, JwtValidationError>
fn parse_oidc_discovery_json(json: &str) -> Result<OidcDiscoveryDocument, OidcContractError>
fn parse_jwks_json(json: &str) -> Result<JwksDocument, OidcContractError>

Governance

fn validate_governance_state(state: &str) -> Result<(), GovernanceValidationError>
fn validate_traceability_statuses(statuses: &[&str]) -> Result<(), GovernanceValidationError>

HTTP routers

Build Axum routers for serving the console and interactions:

// Decision state. Explicit opt-out for a local console that trusts no
// identity provider; ConsolePolicy::default() would require app auth and,
// with no trusted key, refuse every request.
let decisions = RuntimeDecisionState::local_console(
    ConsolePolicy { require_app_auth: false, ..ConsolePolicy::default() },
    None,
);
// Authenticated console: build_runtime_decision_state(RuntimeDecisionInputs { .. })?

// Console frontend (HTML + JS + CSS)
let frontend: Router = console_frontend_router();

// Console JSON API, JSON-RPC, timeline SSE, multipart upload/send, and blobs
let json_api_without_runtime: Router = console_json_router(decisions.clone());
let json_api_with_runtime: Router =
    console_json_router_with_runtime(decisions, mob_runtime, None, None);

Binding is separate from routing. GatewayHttpBinding::bind_loopback() is the default posture (loopback, ephemeral port) and GatewayHttpBinding::bind(addr) takes any SocketAddr; http_base_url() always returns the same-host form (127.0.0.1 for 0.0.0.0 and :: binds) and with_advertised_base_url(..) carries a proxy-facing base for your init reply. Run validate_http_bind_policy("my-host", addr, HttpBindPolicy::for_gateway(allow_remote, &decisions)) before binding to get the gateways’ fail-closed rule (non-loopback needs enforced console auth or the allow_remote acknowledgement) and warn_on_non_loopback_bind for their WARN line; all four live in meerkat_mobkit::gateway_composition. See Deployment.

Rust

TypeScript

Python

Installation

Quick start

Core types

MobKitConfig

ModuleConfig

EventEnvelope

UnifiedEvent

Runtime functions

`start_mobkit_runtime`

`start_mobkit_runtime_with_options`

`UnifiedRuntime::builder`

Module routing

`route_module_call`

`route_module_call_rpc_json`

Operational subsystem functions

Decisions

Authentication

Governance

HTTP routers

See also

​Installation

​Quick start

​Core types

​MobKitConfig

​ModuleConfig

​EventEnvelope

​UnifiedEvent

​Runtime functions

​start_mobkit_runtime

​start_mobkit_runtime_with_options

​UnifiedRuntime::builder

​Module routing

​route_module_call

​route_module_call_rpc_json

​Operational subsystem functions

​Decisions

​Authentication

​Governance

​HTTP routers

​See also

Installation

Quick start

Core types

MobKitConfig

ModuleConfig

EventEnvelope

UnifiedEvent

Runtime functions

`start_mobkit_runtime`

`start_mobkit_runtime_with_options`

`UnifiedRuntime::builder`

Module routing

`route_module_call`

`route_module_call_rpc_json`

Operational subsystem functions

Decisions

Authentication

Governance

HTTP routers

See also