> ## 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. # API reference > Index of public types, traits, and error codes in Meerkat. This page is a quick-lookup index. For current session/runtime semantics, see [Session contracts](/reference/session-contracts). For detailed usage with examples, see the [Rust SDK reference](/rust/overview). ## Generated wire catalogs The public protocol catalogs are generated from `meerkat-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](/cli/commands) | | REST | HTTP paths in [REST API](/api/rest) and `artifacts/schemas/rest-openapi.json` | | JSON-RPC | `rkat-rpc` methods in [JSON-RPC API](/api/rpc) and `artifacts/schemas/rpc-methods.json` | | MCP | `rkat-mcp` public `meerkat_*` tools in [MCP](/api/mcp) | | Rust SDK | `SessionService`, `AgentFactory`, and runtime build modes in [Rust SDK overview](/rust/overview) | | Python SDK | Async wrappers over `rkat-rpc`; see [Python SDK reference](/sdks/python/reference) | | TypeScript SDK | Node wrappers over `rkat-rpc`; see [TypeScript SDK reference](/sdks/typescript/reference) | | Web SDK | Browser/WASM runtime and mobpack deployment target; see [WASM example](/examples/wasm) | ## 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](/rust/advanced#providers) | | `AgentToolDispatcher` | `meerkat_core` | Tool routing abstraction | [Rust SDK: tool system](/rust/tools-and-stores#tool-system) | | `AgentSessionStore` | `meerkat_core` | Session persistence abstraction | [Rust SDK: session stores](/rust/tools-and-stores#session-stores) | | `SessionService` | `meerkat_core::service` | Session lifecycle (create/turn/interrupt/read/list/archive) | [Rust SDK: sessions](/rust/overview#sessions) | | `Compactor` | `meerkat_core` | Context compaction strategy | [Memory guide](/guides/memory) | | `MemoryStore` | `meerkat_core` | Semantic memory indexing | [Memory guide](/guides/memory) | | `SkillEngine` | `meerkat_core::skills` | Skill loading and injection | [Skills guide](/guides/skills) | | `SkillSource` | `meerkat_core::skills` | Skill discovery from various sources | [Skills guide](/guides/skills) | | `HookEngine` | `meerkat_core` | Hook pipeline execution | [Hooks guide](/guides/hooks) | | `FlowTurnExecutor` | `meerkat_mob` | Runtime boundary between flow engine and dispatch/turn transport | [Mobs](/guides/mobs) | ## 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 | 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)` | 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).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 ```rust theme={null} 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, ) -> Result<(), Box> { 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`). ```rust theme={null} 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) -> 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: | 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 | | | | | For cross-surface behavior and examples (CLI/RPC/REST/MCP/Python/TypeScript), see [Mobs](/guides/mobs). ## SDK entry points | Function / Type | Purpose | Detailed docs | | ------------------------------------------------------------- | -------------------------------------------------------------------------------- | ---------------------------------------------------------------- | | `AgentFactory::new(store_root)` | Create a factory for building agents | [Rust SDK](/rust/overview#quick-start) | | `AgentFactory::session_store(store)` | Override session store (e.g. BigQuery, DynamoDB) | [Rust SDK: custom stores](/rust/tools-and-stores#session-stores) | | `open_realm_persistence_in(root, realm, backend, origin)` | Open a realm-backed persistence bundle for runtime-backed Rust embedding | [Rust SDK](/rust/overview#quick-start) | | `build_persistent_service(factory, config, cap, persistence)` | Build the runtime-backed persistent session substrate used by the main Rust path | [Rust SDK](/rust/overview#quick-start) | | `build_ephemeral_service(factory, config, cap)` | Build an in-memory Queue-only substrate for testing and embedded use | [Rust SDK](/rust/overview#quick-start) | | `Config::load()` | Load layered config (legacy/global-project flow) | [Configuration](/concepts/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` | See the [structured output guide](/guides/structured-output) for usage details. ## 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` | See the [hooks guide](/guides/hooks) for usage details. ## 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` | See the [skills guide](/guides/skills) for usage details. ## 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.6` 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 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: | 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 | For session-service transport behavior specifically, see the [Capability matrix](/reference/capability-matrix#error-codes). ## Provider clients | Client | Provider | Detailed docs | | ----------------- | ---------------- | ----------------------------------------------- | | `AnthropicClient` | Anthropic Claude | [Rust SDK: providers](/rust/advanced#providers) | | `OpenAiClient` | OpenAI GPT | [Rust SDK: providers](/rust/advanced#providers) | | `GeminiClient` | Google Gemini | [Rust SDK: providers](/rust/advanced#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 | Store | Feature flag | Purpose | Detailed docs | | --------------------------- | --------------- | ------------------------------------------------- | ----------------------------------------------------------------- | | `JsonlStore` | `jsonl-store` | File-based JSONL persistence | [Rust SDK: session stores](/rust/tools-and-stores#session-stores) | | `SqliteSessionStore` | `session-store` | Embedded database (sqlite) | [Rust SDK: session stores](/rust/tools-and-stores#session-stores) | | `MemoryStore` | `memory-store` | In-memory (testing) | [Rust SDK: session stores](/rust/tools-and-stores#session-stores) | | Custom (`dyn SessionStore`) | — | User-provided via `AgentFactory::session_store()` | [Rust SDK: custom stores](/rust/tools-and-stores#session-stores) | ## See also * [Rust SDK reference](/rust/overview) - full API with examples * [Architecture](/reference/architecture) - crate structure and agent loop * [Capability matrix](/reference/capability-matrix) - build profiles and feature behavior * [Session contracts](/reference/session-contracts) - lifecycle operational contracts