Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.rkat.ai/llms.txt

Use this file to discover all available pages before exploring further.

This page is a quick-lookup index. For current session/runtime semantics, see Session contracts. For detailed usage with examples, see the Rust SDK reference.

Generated wire catalogs

The public protocol catalogs are generated from meerkat-contracts and committed with the repository:
ArtifactSourcePurpose
artifacts/schemas/rpc-methods.jsonmeerkat_contracts::rpc_method_catalogCanonical JSON-RPC method names, descriptions, parameter types, result types, and request lifecycle rules
artifacts/schemas/rest-openapi.jsonREST router/OpenAPI emissionCanonical HTTP paths, methods, summaries, and schema references
artifacts/schemas/wire-types.jsonmeerkat-contracts schemasWire request/result/event types shared by protocol and SDK layers
artifacts/schemas/errors.jsonmeerkat-contracts error catalogStable wire error strings, JSON-RPC codes, HTTP statuses, and CLI exits
artifacts/schemas/runtime-host.jsonRuntime host schema emissionRuntime host info, capability, and health projections
rkat-rpc initialize returns the compiled feature subset at runtime. The catalog above is the full documented surface with blob, sessions, events, streams, schedule, skills, runtime, live channels, mob, MCP, comms, auth, realm, and approval methods enabled.

Surface entry points

SurfaceAPI authority
CLIrkat commands in CLI commands
RESTHTTP paths in REST API and artifacts/schemas/rest-openapi.json
JSON-RPCrkat-rpc methods in JSON-RPC API and artifacts/schemas/rpc-methods.json
MCPrkat-mcp public meerkat_* tools in MCP
Rust SDKSessionService, AgentFactory, and runtime build modes in Rust SDK overview
Python SDKAsync wrappers over rkat-rpc; see Python SDK reference
TypeScript SDKNode wrappers over rkat-rpc; see TypeScript SDK reference
Web SDKBrowser/WASM runtime and mobpack deployment target; see WASM example

Core types

TypeModulePurpose
Agentmeerkat_coreMain agent execution engine
AgentBuildermeerkatPublic facade builder that routes through AgentFactory
meerkat_core::AgentBuildermeerkat_coreLow-level primitive builder used internally by the facade; standalone public construction is not a supported embedding API
Sessionmeerkat_coreConversation state container
SessionIdmeerkat_coreUnique session identifier (UUIDv7)
Messagemeerkat_coreConversation message enum (System, SystemNotice, User, Assistant, BlockAssistant, ToolResults, with runtime notices carried through SystemNotice)
ToolDefmeerkat_coreTool definition (name, description, JSON Schema)
ToolCallmeerkat_coreTool invocation request from the model
ToolCallViewmeerkat_coreZero-allocation borrowed view of a tool call
ToolResultmeerkat_coreTool execution result
Usagemeerkat_coreToken usage tracking
StopReasonmeerkat_coreWhy the LLM stopped (EndTurn, ToolUse, MaxTokens, StopSequence, ContentFilter, Cancelled)
RunResultmeerkat_coreAgent execution result (text, session ID, usage, structured output)
AgentEventmeerkat_coreStreaming events during execution
AgentErrormeerkat_coreError types (LLM, tool, budget, hook, cancellation)
BudgetLimitsmeerkat_coreResource constraints (tokens, duration, tool calls)
RetryPolicymeerkat_coreExponential backoff configuration
RuntimeBuildModemeerkat_coreExplicit runtime ownership mode (SessionOwned vs StandaloneEphemeral)
SessionRuntimeBindingsmeerkat_coreRuntime-backed session bindings (session_id, epoch_id, ops lifecycle, cursor state, tool visibility owner, and session-owned DSL handles)
SessionBuildOptionsmeerkat_core::serviceBuild-time surface options including provider params, structured output, hooks, skills, auth binding, external callback/MCP tools, mob tools, schedule tools, and runtime mode
AuthBindingRefmeerkat_coreRealm-scoped provider credential binding reference carried by sessions and mob members
BlobPayloadmeerkat_coreBlob metadata and bytes returned by blob fetch APIs
ArtifactRecordmeerkat_coreStable artifact metadata for blob-backed generated content
MobRunmeerkat_mobPersisted flow run aggregate
MobRunStatusmeerkat_mobFlow run lifecycle (pending, running, completed, failed, canceled)
StepLedgerEntrymeerkat_mobPer-target step execution record
FailureLedgerEntrymeerkat_mobFlow-level failure log record
FlowRunConfigmeerkat_mobImmutable per-run config snapshot
LiveAdapterStatusmeerkat_coreLive channel adapter status
LiveChannelCapabilitiesmeerkat_coreCapabilities advertised by an open live channel (input/output modalities, continuity mode, tool semantics)
ModelCapabilitiesmeerkat_core::model_profilePer-model capability set; realtime: bool gates whether live/open succeeds for a session

Traits

TraitModulePurposeDetailed docs
AgentLlmClientmeerkat_coreLLM provider abstractionRust SDK: providers
AgentToolDispatchermeerkat_coreTool routing abstractionRust SDK: tool system
AgentSessionStoremeerkat_coreSession persistence abstractionRust SDK: session stores
SessionServicemeerkat_core::serviceSession lifecycle (create/turn/interrupt/read/list/archive)Rust SDK: sessions
Compactormeerkat_coreContext compaction strategyMemory guide
MemoryStoremeerkat_coreSemantic memory indexingMemory guide
SkillEnginemeerkat_core::skillsSkill loading and injectionSkills guide
SkillSourcemeerkat_core::skillsSkill discovery from various sourcesSkills guide
HookEnginemeerkat_coreHook pipeline executionHooks guide
FlowTurnExecutormeerkat_mobRuntime boundary between flow engine and dispatch/turn transportMobs

Runtime-backed build seam

For runtime-backed Rust surfaces, the canonical path is:
  1. MeerkatMachine::prepare_bindings(session_id)
  2. SessionBuildOptions.runtime_build_mode = RuntimeBuildMode::SessionOwned(bindings)
  3. SessionService::create_session(...)
For standalone/testing/embedded paths, prefer RuntimeBuildMode::StandaloneEphemeral explicitly.

Mobs (Rust SDK)

Mob runtime APIs live primarily in:
  • meerkat_mob (core runtime)
  • meerkat_mob_mcp (tool-dispatch helpers)

Core Rust types

TypePurpose
MobDefinitionDeclarative mob structure (profiles, wiring, topology, limits, flows)
MobStorageEvent/run/spec storage bundle (in-memory or SQLite)
MobBuilderConstruct or resume mob runtime
MobHandleRuntime handle for lifecycle, membership, wiring, turns, flows, tasks
MobSessionServiceSession-service bridge trait required by mob runtime
MobStateLifecycle state (Creating, Running, Stopped, Completed, Destroyed)
MobRunPersisted flow run aggregate
SpawnMemberSpecBatch spawn input contract (profile_name, agent_identity, initial_message, runtime_mode, backend)

MobBuilder methods

MethodPurpose
MobBuilder::new(definition, storage)Build a new mob
MobBuilder::for_resume(storage)Resume from persisted events
with_session_service(Arc<dyn MobSessionService>)Attach required session bridge
allow_ephemeral_sessions(bool)Allow non-persistent session services (dev/test)
notify_orchestrator_on_resume(bool)Control resume notification behavior
register_tool_bundle(name, dispatcher)Register named Rust tool bundle
create().awaitValidate + create runtime
resume().awaitRehydrate runtime from store

MobHandle methods

MethodPurpose
status()Current lifecycle state
roster().await / list_members().awaitMembership inspection
spawn(...).awaitSpawn member (returns SpawnResult)
spawn_many(Vec<SpawnMemberSpec>).awaitBatch spawn members in parallel (results preserve input order)
spawn_with_backend(...).awaitSpawn member with explicit backend override
spawn_with_options(...).awaitSpawn member with runtime mode and backend overrides
retire(...).awaitRetire member
wire(...).await / unwire(...).awaitPeer graph mutation
member(...).send(...).await / internal_turn(...).awaitTurn dispatch
stop().await / resume().await / complete().await / destroy().awaitLifecycle transitions
list_flows() / run_flow(...).await / flow_status(...).await / cancel_flow(...).awaitFlow runtime control
events().poll(...) / poll_events(...)Event stream access

Rust example

use std::sync::Arc;
use meerkat_core::types::HandlingMode;
use meerkat_mob::{
    AgentIdentity, FlowId, MobBuilder, MobDefinition, MobSessionService, MobStorage,
    SpawnMemberSpec,
};

async fn orchestrate(
    definition_toml: &str,
    session_service: Arc<dyn MobSessionService>,
) -> Result<(), Box<dyn std::error::Error>> {
    let definition = MobDefinition::from_toml(definition_toml)?;
    let storage = MobStorage::persistent("./mob.db")?;

    let handle = MobBuilder::new(definition, storage)
        .with_session_service(session_service)
        .create()
        .await?;

    handle
        .spawn_spec(SpawnMemberSpec::new("lead", AgentIdentity::from("lead-1")))
        .await?;
    handle
        .spawn_spec(SpawnMemberSpec::new("worker", AgentIdentity::from("worker-1")))
        .await?;
    handle
        .wire(
            AgentIdentity::from("lead-1"),
            AgentIdentity::from("worker-1"),
        )
        .await?;
    let lead = handle.member(&AgentIdentity::from("lead-1")).await?;
    lead.send("Coordinate work.", HandlingMode::Queue).await?;

    let run_id = handle
        .run_flow(FlowId::from("release_flow"), serde_json::json!({"severity":"critical"}))
        .await?;
    let _run = handle.flow_status(run_id).await?;
    Ok(())
}

Agent-Side Mob Integration (meerkat-mob-mcp)

Agent-side mob capability is exposed by composing:
  • meerkat_mob_mcp::MobMcpState
  • meerkat_mob_mcp::AgentMobToolSurfaceFactory
into:
  • SessionBuildOptions.mob_tools (meerkat_core::service).
use std::sync::Arc;
use meerkat_core::service::SessionBuildOptions;
use meerkat_mob::MobSessionService;
use meerkat_mob_mcp::{AgentMobToolSurfaceFactory, MobMcpState};

fn with_mob_tools(session_service: Arc<dyn MobSessionService>) -> SessionBuildOptions {
    let state = Arc::new(MobMcpState::new(session_service));
    SessionBuildOptions {
        mob_tools: Some(Arc::new(AgentMobToolSurfaceFactory::new(state))),
        ..Default::default()
    }
}
This is the in-session mechanism for granting mob_* tools to the agent. external_tools remains the surface for custom callback tools and MCP-backed dispatchers. Mob orchestration has its own late-bound mob_tools factory slot, which receives session-scoped runtime authority before producing the dispatcher. Public host surfaces use typed control planes instead:
  • JSON-RPC / SDKs: typed mob/* methods
  • Public MCP hosts: typed meerkat_mob_* tools
For mob-only MCP hosts, meerkat-mob-mcp also exposes:
  • meerkat_mob_mcp::public_tools_list
  • meerkat_mob_mcp::handle_public_tools_call
Those helpers are for public host control-plane tools. AgentMobToolSurface remains the agent-side mob_* tool surface, late-bound through SessionBuildOptions.mob_tools.

Public mob host methods

Public application hosts should use the typed control planes rather than the agent-internal mob_* tool dispatcher:
SurfaceContract
JSON-RPC / SDKsmob/create, mob/list, mob/status, mob/lifecycle, mob/spawn, mob/spawn_many, mob/ensure_member, mob/reconcile, mob/list_members_matching, mob/members, mob/retire, mob/respawn, mob/wire, mob/unwire, mob/member_send, mob/turn_start, mob/ingress_interaction, mob/append_system_context, mob/events, flow methods, helper methods, work-lane methods, mob/wait_kickoff, mob/wait_ready, mob/snapshot, mob/destroy, supervisor methods, profile methods, and stream open/close
MCPmeerkat_mob_* tools from meerkat-mob-mcp::public_tools_list(), including lifecycle, membership, wiring, member interaction, events, flows, meerkat_mob_wait_kickoff, meerkat_mob_wait_ready, and profile CRUD (`meerkat_mob_profile_creategetlistupdatedelete`)
RESTHelper and observation endpoints (/mob/{id}/events, helper spawn/fork, member status/cancel/respawn, wait kickoff); full typed lifecycle remains RPC/SDK
For cross-surface behavior and examples (CLI/RPC/REST/MCP/Python/TypeScript), see Mobs.

SDK entry points

Function / TypePurposeDetailed docs
AgentFactory::new(store_root)Create a factory for building agentsRust SDK
AgentFactory::session_store(store)Override session store (e.g. BigQuery, DynamoDB)Rust SDK: custom stores
open_realm_persistence_in(root, realm, backend, origin)Open a realm-backed persistence bundle for runtime-backed Rust embeddingRust SDK
build_persistent_service(factory, config, cap, persistence)Build the runtime-backed persistent session substrate used by the main Rust pathRust SDK
build_ephemeral_service(factory, config, cap)Build an in-memory Queue-only substrate for testing and embedded useRust SDK
Config::load()Load layered config (legacy/global-project flow)Configuration

Structured output types

TypePurpose
OutputSchemaSchema definition with compat/strict/format options
MeerkatSchemaNormalized JSON Schema newtype
SchemaCompatLossy (best-effort lowering) or Strict (reject unsupported features)
SchemaFormatSchema format version (MeerkatV1)
SchemaWarningProvider-specific compilation warning
CompiledSchemaProvider-compiled schema output
SchemaErrorInvalidRoot or UnsupportedFeatures
See the structured output guide for usage details.

Hook types

TypePurpose
HookPoint8 extension points (RunStarted through TurnBoundary)
HookCapabilityObserve, Guardrail, Rewrite (retired compatibility label; no patch authority)
HookExecutionModeForeground (blocking) or Background (async)
HookEntryConfigPer-hook configuration (id, point, priority, runtime, failure policy)
HookRunOverridesPer-run hook customization (add entries, disable by ID)
HookDecisionAllow or Deny with reason code
HookPatchRetired patch surface; no valid semantic mutation variants
HookFailurePolicyFailOpen or FailClosed
See the hooks guide for usage details.

Skill types

TypePurpose
SourceUuidStable source identity
SkillNameLowercase dash-separated skill slug
SkillKeyCanonical skill identifier: source_uuid + skill_name
SkillRefTagged per-turn skill reference (kind: "structured")
SkillScopeBuiltin, Project, User
SkillDescriptorSkill metadata (key, name, description, required capabilities, source name)
SkillDocumentLoaded skill with body content
SkillErrorNotFound, CapabilityUnavailable, Load, Parse, SourceUuidCollision, SourceUuidMutationWithoutLineage, MissingSkillRemaps, RemapWithoutLineage, UnknownSkillAlias, RemapCycle
See the skills guide for usage details.

Wire types (meerkat-contracts)

TypePurpose
CapabilityIdAll known capabilities (Sessions, Streaming, Hooks, Shell, etc.)
CapabilityStatusAvailable, DisabledByPolicy, NotCompiled, NotSupportedByProtocol
ErrorCodeStable error codes with projections to JSON-RPC, HTTP, and CLI exit codes
WireErrorCanonical error envelope (code, message, details, capability hint)
WireRunResultCanonical response (session_id, session_ref, text, turns, tool_calls, usage, structured_output, extraction_error, schema_warnings, skill_diagnostics)
WireSessionInfoSession metadata
WireSessionSummaryLightweight session summary
WireEventEvent wire format
WireUsageToken/cost usage breakdown
ContractVersionSemver version (0.6.5 currently)
CoreCreateParamsSession creation parameters
OutputSchema + structured_output_retriesStructured-output schema and retry settings carried directly on session/turn request surfaces
CommsParamsKeep-alive + comms identity parameters
HookParamsHook override entries
SkillsParamsSkill enablement + references

Error code reference

This table describes the higher-level canonical ErrorCode/wire envelope view. It is not identical to the lower-level SessionError transport mapping used by the session service adapters. Every ErrorCode maps to a stable string, JSON-RPC code, HTTP status, and CLI exit code:
ErrorCode stringJSON-RPCHTTPCLI
Session not foundSESSION_NOT_FOUND-3200140410
Session busySESSION_BUSY-3200240911
Session not runningSESSION_NOT_RUNNING-3200340912
Provider errorPROVIDER_ERROR-3201050220
Budget exhaustedBUDGET_EXHAUSTED-3201142921
Hook deniedHOOK_DENIED-3201240322
Agent errorAGENT_ERROR-3201350030
Capability unavailableCAPABILITY_UNAVAILABLE-3202050140
Duplicate inputDUPLICATE_INPUT-3200440913
Request cancelledREQUEST_CANCELLED-3200549914
Skill not foundSKILL_NOT_FOUND-3202140441
Skill resolution failedSKILL_RESOLUTION_FAILED-3202242242
Invalid paramsINVALID_PARAMS-326024002
Internal errorINTERNAL_ERROR-326035001
For session-service transport behavior specifically, see the Capability matrix.

Provider clients

ClientProviderDetailed docs
AnthropicClientAnthropic ClaudeRust SDK: providers
OpenAiClientOpenAI GPTRust SDK: providers
GeminiClientGoogle GeminiRust SDK: providers
All implement AgentLlmClient and normalize streaming responses to LlmEvent (text deltas, tool call deltas, usage updates, done). LlmError variants: RateLimited, ServerOverloaded, NetworkTimeout, ConnectionReset, ServerError, InvalidRequest, AuthenticationFailed, ContentFiltered, ContextLengthExceeded, ModelNotFound, InvalidApiKey, Unknown, StreamParseError, IncompleteResponse. Use error.is_retryable() to check if an error should be retried.

Storage implementations

StoreFeature flagPurposeDetailed docs
JsonlStorejsonl-storeFile-based JSONL persistenceRust SDK: session stores
SqliteSessionStoresession-storeEmbedded database (sqlite)Rust SDK: session stores
MemoryStorememory-storeIn-memory (testing)Rust SDK: session stores
Custom (dyn SessionStore)User-provided via AgentFactory::session_store()Rust SDK: custom stores

See also