Skip to main content
This page is a quick-lookup index. For settled 0.5 session/runtime semantics, see Session contracts. For detailed usage with examples, see the Rust SDK reference.

Core types

TypeModulePurpose
Agentmeerkat_coreMain agent execution engine
AgentBuildermeerkat_coreBuilder pattern for agent construction
Sessionmeerkat_coreConversation state container
SessionIdmeerkat_coreUnique session identifier (UUIDv7)
Messagemeerkat_coreConversation message enum (System, User, Assistant, BlockAssistant, ToolResults)
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
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

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

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 redb)
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, meerkat_id, 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 MemberRef)
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
task_create(...).await / task_update(...).await / task_list().awaitShared task board
events().poll(...) / poll_events(...)Event stream access

Rust example

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

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::redb("./mob.redb")?;

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

    handle
        .spawn(ProfileName::from("lead"), MeerkatId::from("lead-1"), None)
        .await?;
    handle
        .spawn(ProfileName::from("worker"), MeerkatId::from("worker-1"), None)
        .await?;
    handle
        .wire(MeerkatId::from("lead-1"), MeerkatId::from("worker-1"))
        .await?;
    let lead = handle.member(&MeerkatId::from("lead-1")).await?;
    lead.send("Coordinate work.", HandlingMode::Queue, None).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(())
}

Cross-surface mob integration (meerkat-mob-mcp)

Mob capability for non-Rust-SDK surfaces is exposed by composing:
  • meerkat_mob_mcp::MobMcpState
  • meerkat_mob_mcp::MobMcpDispatcher
into:
  • SessionBuildOptions.external_tools (meerkat_core::service).
use std::sync::Arc;
use meerkat_core::service::SessionBuildOptions;
use meerkat_core::AgentToolDispatcher;
use meerkat_mob::MobSessionService;
use meerkat_mob_mcp::{MobMcpDispatcher, MobMcpState};

fn with_mob_tools(session_service: Arc<dyn MobSessionService>) -> SessionBuildOptions {
    let state = Arc::new(MobMcpState::new(session_service));
    let tools: Arc<dyn AgentToolDispatcher> = Arc::new(MobMcpDispatcher::new(state));
    SessionBuildOptions {
        external_tools: Some(tools),
        ..Default::default()
    }
}
This is the shared mechanism used by session-driven surfaces (MCP/REST/RPC and SDKs) to provide mob_* tool capability. 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
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
HookPatchMutations: LlmRequest, AssistantText, ToolArgs, ToolResult, RunResult
HookFailurePolicyFailOpen or FailClosed
See the hooks guide for usage details.

Skill types

TypePurpose
SkillIdNewtype skill identifier
SkillScopeBuiltin, Project, User
SkillDescriptorSkill metadata (id, name, description, required capabilities)
SkillDocumentLoaded skill with body content
SkillErrorNotFound, CapabilityUnavailable, Ambiguous, Load, Parse, SourceUuidCollision, SourceUuidMutationWithoutLineage, MissingSkillRemaps, RemapWithoutLineage, InvalidLegacySkillRefFormat, 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, schema_warnings, skill_diagnostics)
WireSessionInfoSession metadata
WireSessionSummaryLightweight session summary
WireEventEvent wire format
WireUsageToken/cost usage breakdown
ContractVersionSemver version (0.5.0 currently)
CoreCreateParamsSession creation parameters
StructuredOutputParamsSchema + retry count
CommsParamsKeep-alive + comms identity parameters
HookParamsHook override entries
SkillsParamsSkill enablement + references

Error code reference

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
Skill not foundSKILL_NOT_FOUND-3202140441
Skill resolution failedSKILL_RESOLUTION_FAILED-3202242242
Invalid paramsINVALID_PARAMS-326024002
Internal errorINTERNAL_ERROR-326035001

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
RedbSessionStoresession-storeEmbedded database (redb)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