Core types
| Type | Module | Purpose |
|---|---|---|
Agent | meerkat_core | Main agent execution engine |
AgentBuilder | meerkat_core | Builder pattern for agent construction |
Session | meerkat_core | Conversation state container |
SessionId | meerkat_core | Unique session identifier (UUIDv7) |
Message | meerkat_core | Conversation message enum (System, User, Assistant, BlockAssistant, ToolResults) |
ToolDef | meerkat_core | Tool definition (name, description, JSON Schema) |
ToolCall | meerkat_core | Tool invocation request from the model |
ToolCallView | meerkat_core | Zero-allocation borrowed view of a tool call |
ToolResult | meerkat_core | Tool execution result |
Usage | meerkat_core | Token usage tracking |
StopReason | meerkat_core | Why the LLM stopped (EndTurn, ToolUse, MaxTokens, StopSequence, ContentFilter, Cancelled) |
RunResult | meerkat_core | Agent execution result (text, session ID, usage, structured output) |
AgentEvent | meerkat_core | Streaming events during execution |
AgentError | meerkat_core | Error types (LLM, tool, budget, hook, cancellation) |
BudgetLimits | meerkat_core | Resource constraints (tokens, duration, tool calls) |
RetryPolicy | meerkat_core | Exponential backoff configuration |
MobRun | meerkat_mob | Persisted flow run aggregate |
MobRunStatus | meerkat_mob | Flow run lifecycle (pending, running, completed, failed, canceled) |
StepLedgerEntry | meerkat_mob | Per-target step execution record |
FailureLedgerEntry | meerkat_mob | Flow-level failure log record |
FlowRunConfig | meerkat_mob | Immutable per-run config snapshot |
Traits
| Trait | Module | Purpose | Detailed docs |
|---|---|---|---|
AgentLlmClient | meerkat_core | LLM provider abstraction | Rust SDK: providers |
AgentToolDispatcher | meerkat_core | Tool routing abstraction | Rust SDK: tool system |
AgentSessionStore | meerkat_core | Session persistence abstraction | Rust SDK: session stores |
SessionService | meerkat_core::service | Session lifecycle (create/turn/interrupt/read/list/archive) | Rust SDK: sessions |
Compactor | meerkat_core | Context compaction strategy | Memory guide |
MemoryStore | meerkat_core | Semantic memory indexing | Memory guide |
SkillEngine | meerkat_core::skills | Skill loading and injection | Skills guide |
SkillSource | meerkat_core::skills | Skill discovery from various sources | Skills guide |
HookEngine | meerkat_core | Hook pipeline execution | Hooks guide |
FlowTurnExecutor | meerkat_mob | Runtime boundary between flow engine and dispatch/turn transport | Mobs |
Mobs (Rust SDK)
Mob runtime APIs live primarily in:meerkat_mob(core runtime)meerkat_mob_mcp(tool-dispatch helpers)
Core Rust types
| Type | Purpose |
|---|---|
MobDefinition | Declarative mob structure (profiles, wiring, topology, limits, flows) |
MobStorage | Event/run/spec storage bundle (in-memory or redb) |
MobBuilder | Construct or resume mob runtime |
MobHandle | Runtime handle for lifecycle, membership, wiring, turns, flows, tasks |
MobSessionService | Session-service bridge trait required by mob runtime |
MobState | Lifecycle state (Creating, Running, Stopped, Completed, Destroyed) |
MobRun | Persisted flow run aggregate |
SpawnMemberSpec | Batch spawn input contract (profile_name, meerkat_id, initial_message, runtime_mode, backend) |
MobBuilder methods
| Method | Purpose |
|---|---|
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().await | Validate + create runtime |
resume().await | Rehydrate runtime from store |
MobHandle methods
| Method | Purpose |
|---|---|
status() | Current lifecycle state |
roster().await / list_members().await | Membership inspection |
spawn(...).await | Spawn member (returns MemberRef) |
spawn_many(Vec<SpawnMemberSpec>).await | Batch spawn members in parallel (results preserve input order) |
spawn_with_backend(...).await | Spawn member with explicit backend override |
spawn_with_options(...).await | Spawn member with runtime mode and backend overrides |
retire(...).await | Retire member |
wire(...).await / unwire(...).await | Peer graph mutation |
member(...).send(...).await / internal_turn(...).await | Turn dispatch |
stop().await / resume().await / complete().await / destroy().await | Lifecycle transitions |
list_flows() / run_flow(...).await / flow_status(...).await / cancel_flow(...).await | Flow runtime control |
task_create(...).await / task_update(...).await / task_list().await | Shared task board |
events().poll(...) / poll_events(...) | Event stream access |
Rust example
Cross-surface mob integration (meerkat-mob-mcp)
Mob capability for non-Rust-SDK surfaces is exposed by composing:
meerkat_mob_mcp::MobMcpStatemeerkat_mob_mcp::MobMcpDispatcher
SessionBuildOptions.external_tools(meerkat_core::service).
mob_* tool capability.
For cross-surface behavior and examples (CLI/RPC/REST/MCP/Python/TypeScript), see Mobs.
SDK entry points
| Function / Type | Purpose | Detailed docs |
|---|---|---|
AgentFactory::new(store_root) | Create a factory for building agents | Rust 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 embedding | Rust SDK |
build_persistent_service(factory, config, cap, persistence) | Build the runtime-backed persistent session substrate used by the main Rust path | Rust SDK |
build_ephemeral_service(factory, config, cap) | Build an in-memory Queue-only substrate for testing and embedded use | Rust SDK |
Config::load() | Load layered config (legacy/global-project flow) | Configuration |
Structured output types
| Type | Purpose |
|---|---|
OutputSchema | Schema definition with compat/strict/format options |
MeerkatSchema | Normalized JSON Schema newtype |
SchemaCompat | Lossy (best-effort lowering) or Strict (reject unsupported features) |
SchemaFormat | Schema format version (MeerkatV1) |
SchemaWarning | Provider-specific compilation warning |
CompiledSchema | Provider-compiled schema output |
SchemaError | InvalidRoot or UnsupportedFeatures |
Hook types
| Type | Purpose |
|---|---|
HookPoint | 8 extension points (RunStarted through TurnBoundary) |
HookCapability | Observe, Guardrail, Rewrite |
HookExecutionMode | Foreground (blocking) or Background (async) |
HookEntryConfig | Per-hook configuration (id, point, priority, runtime, failure policy) |
HookRunOverrides | Per-run hook customization (add entries, disable by ID) |
HookDecision | Allow or Deny with reason code |
HookPatch | Mutations: LlmRequest, AssistantText, ToolArgs, ToolResult, RunResult |
HookFailurePolicy | FailOpen or FailClosed |
Skill types
| Type | Purpose |
|---|---|
SkillId | Newtype skill identifier |
SkillScope | Builtin, Project, User |
SkillDescriptor | Skill metadata (id, name, description, required capabilities) |
SkillDocument | Loaded skill with body content |
SkillError | NotFound, CapabilityUnavailable, Ambiguous, Load, Parse, SourceUuidCollision, SourceUuidMutationWithoutLineage, MissingSkillRemaps, RemapWithoutLineage, InvalidLegacySkillRefFormat, UnknownSkillAlias, RemapCycle |
Wire types (meerkat-contracts)
| Type | Purpose |
|---|---|
CapabilityId | All known capabilities (Sessions, Streaming, Hooks, Shell, etc.) |
CapabilityStatus | Available, DisabledByPolicy, NotCompiled, NotSupportedByProtocol |
ErrorCode | Stable error codes with projections to JSON-RPC, HTTP, and CLI exit codes |
WireError | Canonical error envelope (code, message, details, capability hint) |
WireRunResult | Canonical response (session_id, session_ref, text, turns, tool_calls, usage, structured_output, schema_warnings, skill_diagnostics) |
WireSessionInfo | Session metadata |
WireSessionSummary | Lightweight session summary |
WireEvent | Event wire format |
WireUsage | Token/cost usage breakdown |
ContractVersion | Semver version (0.5.0 currently) |
CoreCreateParams | Session creation parameters |
StructuredOutputParams | Schema + retry count |
CommsParams | Keep-alive + comms identity parameters |
HookParams | Hook override entries |
SkillsParams | Skill enablement + references |
Error code reference
EveryErrorCode maps to a stable string, JSON-RPC code, HTTP status, and CLI exit code:
| Error | Code string | JSON-RPC | HTTP | CLI |
|---|---|---|---|---|
| Session not found | SESSION_NOT_FOUND | -32001 | 404 | 10 |
| Session busy | SESSION_BUSY | -32002 | 409 | 11 |
| Session not running | SESSION_NOT_RUNNING | -32003 | 409 | 12 |
| Provider error | PROVIDER_ERROR | -32010 | 502 | 20 |
| Budget exhausted | BUDGET_EXHAUSTED | -32011 | 429 | 21 |
| Hook denied | HOOK_DENIED | -32012 | 403 | 22 |
| Agent error | AGENT_ERROR | -32013 | 500 | 30 |
| Capability unavailable | CAPABILITY_UNAVAILABLE | -32020 | 501 | 40 |
| Skill not found | SKILL_NOT_FOUND | -32021 | 404 | 41 |
| Skill resolution failed | SKILL_RESOLUTION_FAILED | -32022 | 422 | 42 |
| Invalid params | INVALID_PARAMS | -32602 | 400 | 2 |
| Internal error | INTERNAL_ERROR | -32603 | 500 | 1 |
Provider clients
| Client | Provider | Detailed docs |
|---|---|---|
AnthropicClient | Anthropic Claude | Rust SDK: providers |
OpenAiClient | OpenAI GPT | Rust SDK: providers |
GeminiClient | Google Gemini | Rust SDK: providers |
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
| Store | Feature flag | Purpose | Detailed docs |
|---|---|---|---|
JsonlStore | jsonl-store | File-based JSONL persistence | Rust SDK: session stores |
RedbSessionStore | session-store | Embedded database (redb) | Rust SDK: session stores |
MemoryStore | memory-store | In-memory (testing) | Rust SDK: session stores |
Custom (dyn SessionStore) | — | User-provided via AgentFactory::session_store() | Rust SDK: custom stores |
See also
- Rust SDK reference - full API with examples
- Architecture - crate structure and agent loop
- Capability matrix - build profiles and feature behavior
- Session contracts - lifecycle operational contracts
