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.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.
Generated wire catalogs
The public protocol catalogs are generated frommeerkat-contracts and
committed with the repository:
| Artifact | Source | Purpose |
|---|---|---|
artifacts/schemas/rpc-methods.json | meerkat_contracts::rpc_method_catalog | Canonical JSON-RPC method names, descriptions, parameter types, result types, and request lifecycle rules |
artifacts/schemas/rest-openapi.json | REST router/OpenAPI emission | Canonical HTTP paths, methods, summaries, and schema references |
artifacts/schemas/wire-types.json | meerkat-contracts schemas | Wire request/result/event types shared by protocol and SDK layers |
artifacts/schemas/errors.json | meerkat-contracts error catalog | Stable wire error strings, JSON-RPC codes, HTTP statuses, and CLI exits |
artifacts/schemas/runtime-host.json | Runtime host schema emission | Runtime 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
| Surface | API authority |
|---|---|
| CLI | rkat commands in CLI commands |
| REST | HTTP paths in REST API and artifacts/schemas/rest-openapi.json |
| JSON-RPC | rkat-rpc methods in JSON-RPC API and artifacts/schemas/rpc-methods.json |
| MCP | rkat-mcp public meerkat_* tools in MCP |
| Rust SDK | SessionService, AgentFactory, and runtime build modes in Rust SDK overview |
| Python SDK | Async wrappers over rkat-rpc; see Python SDK reference |
| TypeScript SDK | Node wrappers over rkat-rpc; see TypeScript SDK reference |
| Web SDK | Browser/WASM runtime and mobpack deployment target; see WASM example |
Core types
| Type | Module | Purpose |
|---|---|---|
Agent | meerkat_core | Main agent execution engine |
AgentBuilder | meerkat | Public facade builder that routes through AgentFactory |
meerkat_core::AgentBuilder | meerkat_core | Low-level primitive builder used internally by the facade; standalone public construction is not a supported embedding API |
Session | meerkat_core | Conversation state container |
SessionId | meerkat_core | Unique session identifier (UUIDv7) |
Message | meerkat_core | Conversation message enum (System, SystemNotice, User, Assistant, BlockAssistant, ToolResults, with runtime notices carried through SystemNotice) |
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 |
RuntimeBuildMode | meerkat_core | Explicit runtime ownership mode (SessionOwned vs StandaloneEphemeral) |
SessionRuntimeBindings | meerkat_core | Runtime-backed session bindings (session_id, epoch_id, ops lifecycle, cursor state, tool visibility owner, and session-owned DSL handles) |
SessionBuildOptions | meerkat_core::service | Build-time surface options including provider params, structured output, hooks, skills, auth binding, external callback/MCP tools, mob tools, schedule tools, and runtime mode |
AuthBindingRef | meerkat_core | Realm-scoped provider credential binding reference carried by sessions and mob members |
BlobPayload | meerkat_core | Blob metadata and bytes returned by blob fetch APIs |
ArtifactRecord | meerkat_core | Stable artifact metadata for blob-backed generated content |
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 |
LiveAdapterStatus | meerkat_core | Live channel adapter status |
LiveChannelCapabilities | meerkat_core | Capabilities advertised by an open live channel (input/output modalities, continuity mode, tool semantics) |
ModelCapabilities | meerkat_core::model_profile | Per-model capability set; realtime: bool gates whether live/open succeeds for a session |
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 |
Runtime-backed build seam
For runtime-backed Rust surfaces, the canonical path is:MeerkatMachine::prepare_bindings(session_id)SessionBuildOptions.runtime_build_mode = RuntimeBuildMode::SessionOwned(bindings)SessionService::create_session(...)
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
| Type | Purpose |
|---|---|
MobDefinition | Declarative mob structure (profiles, wiring, topology, limits, flows) |
MobStorage | Event/run/spec storage bundle (in-memory or SQLite) |
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, agent_identity, 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 SpawnResult) |
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 |
events().poll(...) / poll_events(...) | Event stream access |
Rust example
Agent-Side Mob Integration (meerkat-mob-mcp)
Agent-side mob capability is exposed by composing:
meerkat_mob_mcp::MobMcpStatemeerkat_mob_mcp::AgentMobToolSurfaceFactory
SessionBuildOptions.mob_tools(meerkat_core::service).
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
meerkat-mob-mcp also exposes:
meerkat_mob_mcp::public_tools_listmeerkat_mob_mcp::handle_public_tools_call
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-internalmob_* tool dispatcher:
| Surface | Contract | ||||
|---|---|---|---|---|---|
| JSON-RPC / SDKs | mob/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 | ||||
| MCP | meerkat_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_create | get | list | update | delete`) |
| REST | Helper and observation endpoints (/mob/{id}/events, helper spawn/fork, member status/cancel/respawn, wait kickoff); full typed lifecycle remains RPC/SDK |
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 (retired compatibility label; no patch authority) |
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 | Retired patch surface; no valid semantic mutation variants |
HookFailurePolicy | FailOpen or FailClosed |
Skill types
| Type | Purpose |
|---|---|
SourceUuid | Stable source identity |
SkillName | Lowercase dash-separated skill slug |
SkillKey | Canonical skill identifier: source_uuid + skill_name |
SkillRef | Tagged per-turn skill reference (kind: "structured") |
SkillScope | Builtin, Project, User |
SkillDescriptor | Skill metadata (key, name, description, required capabilities, source name) |
SkillDocument | Loaded skill with body content |
SkillError | NotFound, CapabilityUnavailable, Load, Parse, SourceUuidCollision, SourceUuidMutationWithoutLineage, MissingSkillRemaps, RemapWithoutLineage, 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, extraction_error, schema_warnings, skill_diagnostics) |
WireSessionInfo | Session metadata |
WireSessionSummary | Lightweight session summary |
WireEvent | Event wire format |
WireUsage | Token/cost usage breakdown |
ContractVersion | Semver version (0.6.5 currently) |
CoreCreateParams | Session creation parameters |
OutputSchema + structured_output_retries | Structured-output schema and retry settings carried directly on session/turn request surfaces |
CommsParams | Keep-alive + comms identity parameters |
HookParams | Hook override entries |
SkillsParams | Skill enablement + references |
Error code reference
This table describes the higher-level canonicalErrorCode/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:
| 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 |
| Duplicate input | DUPLICATE_INPUT | -32004 | 409 | 13 |
| Request cancelled | REQUEST_CANCELLED | -32005 | 499 | 14 |
| 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 |
SqliteSessionStore | session-store | Embedded database (sqlite) | 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
