Capability matrix

​

Build profiles

​

Capability behavior

​

Error codes

• Session transport mapping: how SessionError is projected by session-facing transports
• Canonical wire ErrorCode mapping: the higher-level meerkat-contracts envelope model used across public protocol surfaces

​

Transport error mapping summary

• JSON-RPC: NotFound/Busy keep dedicated codes (-32001/-32002); typed agent causes use the canonical meerkat_contracts::ErrorCode::jsonrpc_code() values; all other session variants collapse to -32603 with the message preserved.
• REST: Endpoint-typed ApiError mapping (NotFound -> 404; Busy -> 400 on create/turn, 409 on interrupt conflicts; archived/unavailable history -> 400; agent/internal -> 500). Where canonical wire errors are emitted, ErrorCode::http_status() decides the status. Error body includes { "code": "...", "message": "..." }.
• MCP Server: Tool calls return is_error: true with the error message and code in the content.
• CLI: Exit codes are coarse: 0 success, 1 error, 2 graceful budget exhaustion. Error details are printed to stderr.

​

Pick only what you need

# Minimal: just the agent loop
[dependencies]
meerkat = { version = "0.7.11", default-features = false, features = ["anthropic"] }

# Add persistence
meerkat = { version = "0.7.11", default-features = false, features = ["anthropic", "session-store"] }

# Add compaction
meerkat = { version = "0.7.11", default-features = false, features = ["anthropic", "session-store", "session-compaction"] }

# Add scheduling
meerkat = { version = "0.7.11", default-features = false, features = ["anthropic", "session-store", "schedule"] }

# Kitchen sink
meerkat = { version = "0.7.11", features = [
  "all-providers", "openai-realtime", "session-store", "session-compaction",
  "memory-store-session", "comms", "mcp", "skills", "schedule", "workgraph", "live"
] }

​

Runtime Capabilities

​

Model capabilities

• view_image tool visibility — hidden via the capability-base ToolFilter (capability_base_filter_for_image_tool_results) when image_tool_results is false.
• ContentBlock::Image in tool results — providers that do not support image_tool_results will receive image content blocks converted to text descriptions.
• ContentBlock::Image in user messages — providers that do not support vision will not receive image content blocks in user messages.
• Provider-native web search — injected by default when supports_web_search is true and the corresponding provider_tools.* config is enabled.

​

Provider-native web search

• Config-level: set the matching config key from the table above to false
• CLI: rkat run --no-web-search "...".
• Per-request Anthropic/OpenAI: provider_params: {"provider_tag": {"provider": "anthropic", "web_search": false}} (or "provider": "open_ai")
• Per-request Gemini: provider_params: {"provider_tag": {"provider": "gemini", "google_search": false}}
• An explicit non-object value (false or null) in the typed search slot blocks the build-derived default and no search tool is emitted

​

MCP server loading

• Per-server timeout: connect_timeout_secs in MCP config (default: 10s)
• CLI: --wait-for-mcp blocks before the first turn until all servers finish connecting
• SDK: McpRouterAdapter::wait_until_ready(timeout) provides the same blocking behavior programmatically

​

Compaction behavior

• Trigger: last_input_tokens >= threshold OR estimated_history_tokens >= threshold
• Guards: Never on first turn. Minimum 3 turns between compactions.
• Failure: Non-fatal. CompactionFailed event emitted, agent continues with uncompacted history.
• Budget: Compaction LLM call draws from the same token budget as regular turns.

​

Concurrency

• At most one turn runs per session at a time.
• Second start_turn while one is in-flight returns SESSION_BUSY.
• interrupt() cancels the in-flight turn.
• read() and list() are non-blocking.
• No queueing: callers retry on Busy.

​

Durability

• Ephemeral: Process death loses all state.
• Persistent: Snapshot saved after turn completion according to the pinned realm backend.
• Backends are pinned per realm (realm_manifest.json) and shared across surfaces only when realm_id matches.
• SQLite-backed realms are the standard same-realm multi-process mode.

​

See also

• Session contracts — concurrency, durability, and compaction semantics
• Architecture — crate structure and agent loop details